mirror of
https://github.com/boostorg/context.git
synced 2026-01-23 17:32:16 +00:00
117 lines
3.4 KiB
Plaintext
117 lines
3.4 KiB
Plaintext
[/
|
|
Copyright Oliver Kowalke 2009.
|
|
Distributed under the Boost Software License, Version 1.0.
|
|
(See accompanying file LICENSE_1_0.txt or copy at
|
|
http://www.boost.org/LICENSE_1_0.txt
|
|
]
|
|
|
|
[section:stack Stack allocation]
|
|
|
|
A __fcontext__ requires a stack which will be allocated/deallocated
|
|
by a __stack_allocator__.
|
|
__boost_context__ uses `stack_allocator` by default but a
|
|
customized `stack allocator` can be passed to the context constructor
|
|
instead.
|
|
If a context is constructed it invokes __stack_alloc__ function and by its
|
|
destruction the stack gets released by __stack_dealloc__.
|
|
|
|
[heading __stack_allocator_concept__]
|
|
A __stack_allocator__ must satisfy the __stack_allocator_concept__ requirements
|
|
shown in the following table, in which `a` is an object of a
|
|
__stack_allocator__ type, `p` is a `void *`, and `s` is a `std::size_t`:
|
|
|
|
[table
|
|
[[expression][return type][notes]]
|
|
[
|
|
[`a.allocate( s)`]
|
|
[`void *`]
|
|
[returns a pointer to `s` bytes allocated from the stack]
|
|
]
|
|
[
|
|
[`a.deallocate( p, s)`]
|
|
[`void`]
|
|
[deallocates `s` bytes of memory beginning at `p`,
|
|
a pointer previously returned by `a.allocate()`]
|
|
]
|
|
]
|
|
|
|
[important The implementation of `allocate()` might include logic to protect
|
|
against exceeding the context's available stack size rather than leaving it as
|
|
undefined behaviour.]
|
|
|
|
[important Calling `deallocate()` with a pointer not returned by `allocate()`
|
|
results in undefined behaviour.]
|
|
|
|
[note The stack is not required to be aligned; alignment takes place inside
|
|
`make_fcontext()`.]
|
|
|
|
|
|
[section:stack_allocator Class `stack_allocator`]
|
|
|
|
__boost_context__ provides a __stack_allocator__ `stack_allocator` which models
|
|
the __stack_allocator_concept__ concept.
|
|
It appends a __guard_page__ to protect against exceeding the stack. If the guard
|
|
page is accessed (read or write operation) a segmentation fault/access violation
|
|
is generated by the operating system.
|
|
|
|
[endsect]
|
|
|
|
|
|
[section:stack_helper Helper functions]
|
|
|
|
__boost_context__ provides easy access to the stack related limits defined by
|
|
the environment.
|
|
|
|
std::size_t default_stacksize();
|
|
|
|
std::size_t minimum_stacksize();
|
|
|
|
std::size_t maximum_stacksize();
|
|
|
|
bool is_stack_unbound();
|
|
|
|
std::size_t pagesize();
|
|
|
|
std::size_t page_count( std::size_t stacksize);
|
|
|
|
[heading `std::size_t default_stacksize()`]
|
|
[variablelist
|
|
[[Returns:] [Returns a default stack size, which may be platform specific.
|
|
The present implementation returns a value of 256 kB.]]
|
|
]
|
|
|
|
[heading `std::size_t minimum_stacksize()`]
|
|
[variablelist
|
|
[[Returns:] [Returns the minimum size in bytes of stack defined by the environment.]]
|
|
[[Throws:] [Nothing.]]
|
|
]
|
|
|
|
[heading `std::size_t maximum_stacksize()`]
|
|
[variablelist
|
|
[[Preconditions:] [`is_stack_unbound()` returns `false`.]]
|
|
[[Returns:] [Returns the maximum size in bytes of stack defined by the environment.]]
|
|
[[Throws:] [Nothing.]]
|
|
]
|
|
|
|
[heading `bool is_stack_unbound()`]
|
|
[variablelist
|
|
[[Returns:] [Returns `true` if the environment defines no limit for the size of a stack.]]
|
|
[[Throws:] [Nothing.]]
|
|
]
|
|
|
|
[heading `std::size_t pagesize()`]
|
|
[variablelist
|
|
[[Returns:] [Returns how many bytes the operating system allocates for one page.]]
|
|
[[Throws:] [Nothing.]]
|
|
]
|
|
|
|
[heading `std::size_t page_count( std::size_t stacksize)`]
|
|
[variablelist
|
|
[[Returns:] [Returns how many pages have to be allocated for a stack of `stacksize` bytes.]]
|
|
[[Throws:] [Nothing.]]
|
|
]
|
|
|
|
[endsect]
|
|
|
|
[endsect]
|