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