123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295 |
- [/
- 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] and [*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]
|