mirror of
https://github.com/boostorg/fiber.git
synced 2026-01-30 07:52:07 +00:00
a2b18c51de
As Paul points out, links of the form [@boost:/libs/something/index.html] (as recommended by http://www.boost.org/doc/libs/release/doc/html/quickbook/syntax/phrase.html#quickbook.syntax.phrase.links) do not work when generating PDF, or even when locally generating just one library's HTML documentation. He suggests linking explicitly to the relevant boost.org URL. This is much more satisfying as the link can be tested.
93 lines
3.3 KiB
Plaintext
93 lines
3.3 KiB
Plaintext
[/
|
|
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 a __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__.
|
|
|
|
[#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].
|
|
|
|
[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.]
|
|
|
|
|
|
[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()`.
|
|
|
|
|
|
[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] at b2/bjam
|
|
command line.]
|
|
|
|
[endsect]
|