mirror of
https://github.com/boostorg/coroutine.git
synced 2026-01-27 18:52:17 +00:00
121 lines
3.9 KiB
Plaintext
121 lines
3.9 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 __coro__ uses internally a __ctx__ which manages a set of registers and a stack.
|
|
The memory used by the stack is allocated/deallocated via a __stack_allocator__
|
|
which is required to model a __stack_allocator_concept__.
|
|
|
|
|
|
[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
|
|
__coro__.]
|
|
|
|
[note Depending on the architecture `allocate()` returns an address from the
|
|
top of the stack (growing downwards) or the bottom of the stack (growing
|
|
upwards).]
|
|
|
|
|
|
[section:stack_allocator Class ['stack_allocator]]
|
|
|
|
__boost_coroutine__ provides the class __coro_allocator__ which models
|
|
the __stack_allocator_concept__.
|
|
It appends a guard page at the end of each stack 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.
|
|
|
|
[note The appended `guard page` is [*not] mapped to physical memory, only
|
|
virtual addresses are used.]
|
|
|
|
class stack_allocator
|
|
{
|
|
static bool is_stack_unbound();
|
|
|
|
static std::size_t maximum_stacksize();
|
|
|
|
static std::size_t default_stacksize();
|
|
|
|
static std::size_t minimum_stacksize();
|
|
|
|
void * allocate( std::size_t size);
|
|
|
|
void deallocate( void * sp, std::size_t size);
|
|
}
|
|
|
|
[heading `static bool is_stack_unbound()`]
|
|
[variablelist
|
|
[[Returns:] [Returns `true` if the environment defines no limit for the size of a stack.]]
|
|
]
|
|
|
|
[heading `static 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.]]
|
|
]
|
|
|
|
[heading `static std::size_t default_stacksize()`]
|
|
[variablelist
|
|
[[Returns:] [Returns a default stack size, which may be platform specific.
|
|
If the stack is unbound then the present implementation returns the maximum of
|
|
`64 kB` and `minimum_stacksize()`.]]
|
|
]
|
|
|
|
[heading `static std::size_t minimum_stacksize()`]
|
|
[variablelist
|
|
[[Returns:] [Returns the minimum size in bytes of stack defined by the
|
|
environment (Win32 4kB/Win64 8kB, defined by rlimit on POSIX).]]
|
|
]
|
|
|
|
[heading `void * allocate( std::size_t size)`]
|
|
[variablelist
|
|
[[Preconditions:] [`minimum_stacksize() > size` and
|
|
`! is_stack_unbound() && ( maximum_stacksize() < size)`.]]
|
|
[[Effects:] [Allocates memory of `size` Bytes and appends one guard page at the
|
|
end of the allocated memory.]]
|
|
[[Returns:] [Returns pointer to the start address of the new stack. Depending
|
|
on the architecture the stack grows downwards/upwards the returned address is
|
|
the highest/lowest address of the stack.]]
|
|
]
|
|
|
|
[heading `void deallocate( void * sp, std::size_t size)`]
|
|
[variablelist
|
|
[[Preconditions:] [`sp` is valid, `minimum_stacksize() > size` and
|
|
`! is_stack_unbound() && ( maximum_stacksize() < size)`.]]
|
|
[[Effects:] [Deallocates the stack space.]]
|
|
]
|
|
|
|
[endsect]
|
|
|
|
[endsect]
|