| [/ |
| 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, `sctx` is a `stack_context`, and `size` is a `std::size_t`: |
| |
| [table |
| [[expression][return type][notes]] |
| [ |
| [`a.allocate( sctx, size)`] |
| [`void`] |
| [creates a stack of at least `size` bytes and stores its pointer and |
| length in `sctx`] |
| ] |
| [ |
| [`a.deallocate( sctx)`] |
| [`void`] |
| [deallocates the stack created 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 `stack_context` not set 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()` stores an address from the |
| top of the stack (growing downwards) or the bottom of the stack (growing |
| upwards).] |
| |
| class __coro_allocator__ is a typedef of __standard_allocator__. |
| |
| |
| [section:protected_stack_allocator Class ['protected_stack_allocator]] |
| |
| __boost_coroutine__ provides the class __protected_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. |
| |
| [important Using __protected_allocator__ is expensive. That is, launching a |
| new coroutine with a new stack is expensive; the allocated stack is just as |
| efficient to use as any other stack.] |
| |
| [note The appended `guard page` is [*not] mapped to physical memory, only |
| virtual addresses are used.] |
| |
| #include <boost/coroutine/protected_stack_allocator.hpp> |
| |
| template< typename traitsT > |
| struct basic_protected_stack_allocator |
| { |
| typedef traitT traits_type; |
| |
| void allocate( stack_context &, std::size_t size); |
| |
| void deallocate( stack_context &); |
| } |
| |
| typedef basic_protected_stack_allocator< stack_traits > protected_stack_allocator |
| |
| [heading `void allocate( stack_context & sctx, std::size_t size)`] |
| [variablelist |
| [[Preconditions:] [`traits_type::minimum:size() <= size` and |
| `! traits_type::is_unbounded() && ( traits_type::maximum:size() >= size)`.]] |
| [[Effects:] [Allocates memory of at least `size` Bytes and stores a pointer |
| to the stack and its actual size in `sctx`. Depending |
| on the architecture (the stack grows downwards/upwards) the stored address is |
| the highest/lowest address of the stack.]] |
| ] |
| |
| [heading `void deallocate( stack_context & sctx)`] |
| [variablelist |
| [[Preconditions:] [`sctx.sp` is valid, `traits_type::minimum:size() <= sctx.size` and |
| `! traits_type::is_unbounded() && ( traits_type::maximum:size() >= sctx.size)`.]] |
| [[Effects:] [Deallocates the stack space.]] |
| ] |
| |
| [endsect] |
| |
| |
| [section:standard_stack_allocator Class ['standard_stack_allocator]] |
| |
| __boost_coroutine__ provides the class __standard_allocator__ which models |
| the __stack_allocator_concept__. |
| In contrast to __protected_allocator__ it does not append a guard page at the |
| end of each stack. The memory is simply managed by `std::malloc()` and |
| `std::free()`. |
| |
| [note The __standard_allocator__ is the default stack allocator.] |
| |
| #include <boost/coroutine/standard_stack_allocator.hpp> |
| |
| template< typename traitsT > |
| struct standard_stack_allocator |
| { |
| typedef traitT traits_type; |
| |
| void allocate( stack_context &, std::size_t size); |
| |
| void deallocate( stack_context &); |
| } |
| |
| typedef basic_standard_stack_allocator< stack_traits > standard_stack_allocator |
| |
| [heading `void allocate( stack_context & sctx, std::size_t size)`] |
| [variablelist |
| [[Preconditions:] [`traits_type::minimum:size() <= size` and |
| `! traits_type::is_unbounded() && ( traits_type::maximum:size() >= size)`.]] |
| [[Effects:] [Allocates memory of at least `size` Bytes and stores a pointer to |
| the stack and its actual size in `sctx`. Depending on the architecture (the |
| stack grows downwards/upwards) the stored address is the highest/lowest |
| address of the stack.]] |
| ] |
| |
| [heading `void deallocate( stack_context & sctx)`] |
| [variablelist |
| [[Preconditions:] [`sctx.sp` is valid, `traits_type::minimum:size() <= sctx.size` and |
| `! traits_type::is_unbounded() && ( traits_type::maximum:size() >= sctx.size)`.]] |
| [[Effects:] [Deallocates the stack space.]] |
| ] |
| |
| [endsect] |
| |
| |
| [section:segmented_stack_allocator Class ['segmented_stack_allocator]] |
| |
| __boost_coroutine__ supports usage of a __segmented_stack__, e. g. the size of |
| the stack grows on demand. The coroutine is created with a minimal stack size |
| and will be increased as required. |
| Class __segmented_allocator__ models the __stack_allocator_concept__. |
| In contrast to __protected_allocator__ and __standard_allocator__ it creates a |
| stack which grows on demand. |
| |
| [note Segmented stacks are currently only supported by [*gcc] from version |
| [*4.7] [*clang] from version [*3.4] onwards. In order to use a |
| __segmented_stack__ __boost_coroutine__ must be built with |
| [*toolset=gcc segmented-stacks=on] at b2/bjam command-line. Applications |
| must be compiled with compiler-flags |
| [*-fsplit-stack -DBOOST_USE_SEGMENTED_STACKS].] |
| |
| #include <boost/coroutine/segmented_stack_allocator.hpp> |
| |
| template< typename traitsT > |
| struct basic_segmented_stack_allocator |
| { |
| typedef traitT traits_type; |
| |
| void allocate( stack_context &, std::size_t size); |
| |
| void deallocate( stack_context &); |
| } |
| |
| typedef basic_segmented_stack_allocator< stack_traits > segmented_stack_allocator; |
| |
| [heading `void allocate( stack_context & sctx, std::size_t size)`] |
| [variablelist |
| [[Preconditions:] [`traits_type::minimum:size() <= size` and |
| `! traits_type::is_unbounded() && ( traits_type::maximum:size() >= size)`.]] |
| [[Effects:] [Allocates memory of at least `size` Bytes and stores a pointer to |
| the stack and its actual size in `sctx`. Depending on the architecture (the |
| stack grows downwards/upwards) the stored address is the highest/lowest |
| address of the stack.]] |
| ] |
| |
| [heading `void deallocate( stack_context & sctx)`] |
| [variablelist |
| [[Preconditions:] [`sctx.sp` is valid, `traits_type::minimum:size() <= sctx.size` and |
| `! traits_type::is_unbounded() && ( traits_type::maximum:size() >= sctx.size)`.]] |
| [[Effects:] [Deallocates the stack space.]] |
| ] |
| |
| [endsect] |
| |
| |
| [section:stack_traits Class ['stack_traits]] |
| |
| ['stack_traits] models a __stack_traits__ providing a way to access certain |
| properites defined by the enironment. Stack allocators use __stack_traits__ to |
| allocate stacks. |
| |
| #include <boost/coroutine/stack_traits.hpp> |
| |
| struct stack_traits |
| { |
| static bool is_unbounded() noexcept; |
| |
| static std::size_t page_size() noexcept; |
| |
| static std::size_t default_size() noexcept; |
| |
| static std::size_t minimum_size() noexcept; |
| |
| static std::size_t maximum_size() noexcept; |
| } |
| |
| |
| [heading `static bool is_unbounded()`] |
| [variablelist |
| [[Returns:] [Returns `true` if the environment defines no limit for the size of |
| a stack.]] |
| [[Throws:] [Nothing.]] |
| ] |
| |
| [heading `static std::size_t page_size()`] |
| [variablelist |
| [[Returns:] [Returns the page size in bytes.]] |
| [[Throws:] [Nothing.]] |
| ] |
| |
| [heading `static std::size_t default_size()`] |
| [variablelist |
| [[Returns:] [Returns a default stack size, which may be platform specific. |
| If the stack is unbounded then the present implementation returns the maximum of |
| `64 kB` and `minimum_size()`.]] |
| [[Throws:] [Nothing.]] |
| ] |
| |
| [heading `static std::size_t minimum_size()`] |
| [variablelist |
| [[Returns:] [Returns the minimum size in bytes of stack defined by the |
| environment (Win32 4kB/Win64 8kB, defined by rlimit on POSIX).]] |
| [[Throws:] [Nothing.]] |
| ] |
| |
| [heading `static std::size_t maximum_size()`] |
| [variablelist |
| [[Preconditions:] [`is_unbounded()` returns `false`.]] |
| [[Returns:] [Returns the maximum size in bytes of stack defined by the |
| environment.]] |
| [[Throws:] [Nothing.]] |
| ] |
| |
| |
| [endsect] |
| |
| |
| [section:stack_context Class ['stack_context]] |
| |
| __boost_coroutine__ provides the class __stack_context__ which will contain |
| the stack pointer and the size of the stack. |
| In case of a __segmented_stack__, __stack_context__ contains some extra control |
| structures. |
| |
| struct stack_context |
| { |
| void * sp; |
| std::size_t size; |
| |
| // might contain additional control structures |
| // for instance for segmented stacks |
| } |
| |
| [heading `void * sp`] |
| [variablelist |
| [[Value:] [Pointer to the beginning of the stack.]] |
| ] |
| |
| [heading `std::size_t size`] |
| [variablelist |
| [[Value:] [Actual size of the stack.]] |
| ] |
| |
| [endsect] |
| |
| |
| [section:valgrind Support for valgrind] |
| |
| Running programs that switch stacks under valgrind causes problems. |
| Property (b2 command-line) `valgrind=on` let valgrind treat the memory regions |
| as stack space which suppresses the errors. |
| |
| [endsect] |
| |
| |
| [endsect] |