123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303 |
- [/
- Copyright Oliver Kowalke 2009-2013.
- 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
- ]
- [#stack]
- [section:stack Stack allocation]
- A __fiber__ uses internally an __econtext__ 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__.
- A __stack_allocator__ can be passed to [link fiber_fiber `fiber::fiber()`] or
- to [ns_function_link fibers..async].
- [#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(size)`]
- []
- [creates a stack allocator]
- ]
- [
- [`a.allocate()`]
- [__stack_context__]
- [creates a stack]
- ]
- [
- [`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 obtained from
- `allocate()` results in undefined behaviour.]
- [note The memory for the stack is not required to be aligned; alignment takes
- place inside __econtext__.]
- See also [@http://www.boost.org/doc/libs/release/libs/context/doc/html/context/stack.html Boost.Context stack allocation].
- In particular, `traits_type` methods are as described for
- [@http://www.boost.org/doc/libs/release/libs/context/doc/html/context/stack/stack_traits.html
- `boost::context::stack_traits`].
- [class_heading protected_fixedsize_stack]
- __boost_fiber__ provides the class __pfixedsize_stack__ 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 __pfixedsize_stack__ is expensive. Launching a new fiber with
- a stack of this type incurs the overhead of setting the memory protection;
- once allocated, this stack is just as efficient to use as __fixedsize_stack__.]
- [note The appended `guard page` is [*not] mapped to physical memory, only
- virtual addresses are used.]
- #include <boost/fiber/protected_fixedsize.hpp>
- namespace boost {
- namespace fibers {
- struct protected_fixedsize {
- protected_fixesize(std::size_t size = traits_type::default_size());
- stack_context allocate();
- void deallocate( stack_context &);
- }
- }}
- [member_heading protected_fixedsize..allocate]
- stack_context allocate();
- [variablelist
- [[Preconditions:] [`traits_type::minimum_size() <= size` and
- `traits_type::is_unbounded() || ( size <= traits_type::maximum_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.]]
- ]
- [member_heading protected_fixesize..deallocate]
- void deallocate( stack_context & sctx);
- [variablelist
- [[Preconditions:] [`sctx.sp` is valid, `traits_type::minimum_size() <= sctx.size` and
- `traits_type::is_unbounded() || ( sctx.size <= traits_type::maximum_size() )`.]]
- [[Effects:] [Deallocates the stack space.]]
- ]
- [class_heading pooled_fixedsize_stack]
- __boost_fiber__ provides the class __ofixedsize_stack__ which models
- the __stack_allocator_concept__.
- In contrast to __pfixedsize_stack__ it does not append a guard page at the
- end of each stack. The memory is managed internally by
- [@http://www.boost.org/doc/libs/release/libs/pool/doc/html/boost/pool.html `boost::pool<>`].
- #include <boost/fiber/pooled_fixedsize_stack.hpp>
- namespace boost {
- namespace fibers {
- struct pooled_fixedsize_stack {
- pooled_fixedsize_stack(std::size_t stack_size = traits_type::default_size(), std::size_t next_size = 32, std::size_t max_size = 0);
- stack_context allocate();
- void deallocate( stack_context &);
- }
- }}
- [hding pooled_fixedsize..Constructor]
- pooled_fixedsize_stack(std::size_t stack_size, std::size_t next_size, std::size_t max_size);
- [variablelist
- [[Preconditions:] [`traits_type::is_unbounded() || ( traits_type::maximum_size() >= stack_size)`
- and `0 < next_size`.]]
- [[Effects:] [Allocates memory of at least `stack_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. Argument `next_size` determines the number of stacks to
- request from the system the first time that `*this` needs to allocate system
- memory. The third argument `max_size` controls how much memory might be
- allocated for stacks [mdash] a value of zero means no upper limit.]]
- ]
- [member_heading pooled_fixedsize..allocate]
- stack_context allocate();
- [variablelist
- [[Preconditions:] [`traits_type::is_unbounded() || ( traits_type::maximum_size() >= stack_size)`.]]
- [[Effects:] [Allocates memory of at least `stack_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.]]
- ]
- [member_heading pooled_fixesize..deallocate]
- void deallocate( stack_context & sctx);
- [variablelist
- [[Preconditions:] [`sctx.sp` is valid,
- `traits_type::is_unbounded() || ( traits_type::maximum_size() >= sctx.size)`.]]
- [[Effects:] [Deallocates the stack space.]]
- ]
- [note This stack allocator is not thread safe.]
- [class_heading fixedsize_stack]
- __boost_fiber__ provides the class __fixedsize_stack__ which models
- the __stack_allocator_concept__.
- In contrast to __pfixedsize_stack__ it does not append a guard page at the
- end of each stack. The memory is simply managed by `std::malloc()` and
- `std::free()`.
- #include <boost/context/fixedsize_stack.hpp>
- namespace boost {
- namespace fibers {
- struct fixedsize_stack {
- fixedsize_stack(std::size_t size = traits_type::default_size());
- stack_context allocate();
- void deallocate( stack_context &);
- }
- }}
- [member_heading fixedsize..allocate]
- stack_context allocate();
- [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.]]
- ]
- [member_heading fixesize..deallocate]
- 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.]]
- ]
- [#segmented]
- [class_heading segmented_stack]
- __boost_fiber__ supports usage of a __segmented_stack__, i.e.
- the stack grows on demand. The fiber is created with a minimal stack size
- which will be increased as required.
- Class __segmented_stack__ models the __stack_allocator_concept__.
- In contrast to __pfixedsize_stack__ and __fixedsize_stack__ 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_fiber__ must be built with
- property `segmented-stacks`, e.g. [*toolset=gcc segmented-stacks=on]
- and applying BOOST_USE_SEGMENTED_STACKS at b2/bjam command line.]
- [note Segmented stacks can only be used with callcc() using property
- `context-impl=ucontext`.]
- #include <boost/fiber/segmented_stack.hpp>
- namespace boost {
- namespace fibers {
- struct segmented_stack {
- segmented_stack(std::size_t stack_size = traits_type::default_size());
- stack_context allocate();
- void deallocate( stack_context &);
- }
- }}
- [member_heading segmented..allocate]
- stack_context allocate();
- [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.]]
- ]
- [member_heading segmented..deallocate]
- 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.]]
- ]
- [note If the library is compiled for segmented stacks, __segmented_stack__ is the only
- available stack allocator.]
- [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]
- [section:sanitizers Support for sanitizers]
- Sanitizers (GCC/Clang) are confused by the stack switches.
- The library (and Boost.Context too) is required to be compiled with property (b2 command-line)
- `context-impl=ucontext` and compilers santizer options.
- Users must define `BOOST_USE_ASAN` before including any Boost.Context headers
- when linking against Boost binaries.
- [endsect]
- [endsect]
|