fiber/doc/stack.qbk

[/
          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
]

[section:stack Stack allocation]

A __fiber__ uses internally a __coro__ 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 both values 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 previously passed
to `allocate()` results in undefined behaviour.]

[note The memory for the stack is not required to be aligned; alignment takes
place inside __coro__.]


[heading 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.]

        #include <boost/fiber/stack_allocator.hpp>

        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( stack_context &, std::size_t size);

            void deallocate( stack_context &);
        }

[heading Constructor `static bool is_stack_unbound()`]

            static bool is_stack_unbound();

[variablelist
[[Returns:] [Returns `true` if the environment defines no limit for the size of a stack.]]
]

[heading Static member function `static std::size_t maximum_stacksize()`]

            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 member function `static std::size_t default_stacksize()`]

            static std::size_t default_stacksize();

[variablelist
[[Returns:] [Returns a default stack size, which may be platform specific. If
`is_stack_unbound()` returns `true` then the present implementation returns
the maximum of `64 kB` and `minimum_stacksize()`.]]
]

[heading Static member function `static std::size_t minimum_stacksize()`]

            static std::size_t minimum_stacksize();

[variablelist
[[Returns:] [Returns the minimum size in bytes of stack required by the
environment: Win32 4kB, Win64 8kB, defined by rlimit on POSIX.]]
]

[heading Member function `void allocate()`]

            void allocate( stack_context &, std::size_t size);

[variablelist
[[Preconditions:] [`minimum_stacksize() > size` and
`! is_stack_unbound() && ( maximum_stacksize() < size)`.]]
[[Effects:] [Allocates memory of at least `size` Bytes and stores a pointer
to the stack and its actual size in `sctx`.]]
[[Returns:] [`void`]]
[[Note:] [Stores pointer to the start address of the new stack. Depending
on the architecture (stack grows downwards vs. upwards), the stored address is
the highest/lowest address of the stack.]]
]

[heading Member function `void deallocate()`]

            void deallocate( stack_context &);

[variablelist
[[Preconditions:] [`sctx.sp` is valid, `minimum_stacksize() > sctx.size` and
`! is_stack_unbound() && ( maximum_stacksize() < size)`.]]
[[Effects:] [Deallocates the stack space.]]
[[Note:][Oliver: wouldn't it be simpler to say something like: `sctx` must
have been set by a previous call to `allocate()` since it was most recently
passed to `deallocate()` ?]]
]


[heading 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 Member variable `void * sp`]
[variablelist
[[Value:] [Pointer to the beginning of the stack.]]
[[Note:] [Whether the "beginning" of the stack is its lowest address or its
highest address is architecture-dependent.]]
]

[heading Member variable `std::size_t size`]
[variablelist
[[Value:] [Actual size of the stack, in bytes.]]
]


[heading Segmented stacks]

__boost_fiber__ supports use of a __segmented_stack__, whose size
grows on demand. The fiber is created with a minimal stack size, which
will be increased as required.

Segmented stacks are currently only supported by [*gcc] from version [*4.7]
onwards. In order to use a __segmented_stack__, __boost_fiber__ 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].

[endsect]