[/
          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 __fcontext__ requires a stack which will be allocated/deallocated
by a __stack_allocator__.
__boost_context__ uses `stack_allocator` by default but a
customized `stack allocator` can be passed to the context constructor
instead.
If a context is constructed it invokes __stack_alloc__ function and by its
destruction the stack gets released by __stack_dealloc__.

[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, `p` is a `void *`, and `s` is a `std::size_t`:

[table
    [[expression][return type][notes]]
    [
        [`a.allocate( s)`]
        [`void *`]
        [returns a pointer to `s` bytes allocated from the stack]
    ]
    [
        [`a.deallocate( p, s)`]
        [`void`]
        [deallocates `s` bytes of memory beginning at `p`,
        a pointer previously returned 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 pointer not returned by `allocate()`
results in undefined behaviour.]

[note The stack is not required to be aligned; alignment takes place inside
`make_fcontext()`.]


[section:stack_allocator Class `stack_allocator`]

__boost_context__ provides a __stack_allocator__ `stack_allocator` which models
the __stack_allocator_concept__ concept.
It appends a __guard_page__ 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.

[endsect]


[section:stack_helper Helper functions]

__boost_context__ provides easy access to the stack related limits defined by
the environment.

        std::size_t default_stacksize();

        std::size_t minimum_stacksize();

        std::size_t maximum_stacksize();

        bool is_stack_unbound();

        std::size_t pagesize();

        std::size_t page_count( std::size_t stacksize);

[heading `std::size_t default_stacksize()`]
[variablelist
[[Returns:] [Returns a default stack size, which may be platform specific.
The present implementation returns a value of 256 kB.]]
]

[heading `std::size_t minimum_stacksize()`]
[variablelist
[[Returns:] [Returns the minimum size in bytes of stack defined by the environment.]]
[[Throws:] [Nothing.]]
]

[heading `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.]]
[[Throws:] [Nothing.]]
]

[heading `bool is_stack_unbound()`]
[variablelist
[[Returns:] [Returns `true` if the environment defines no limit for the size of a stack.]]
[[Throws:] [Nothing.]]
]

[heading `std::size_t pagesize()`]
[variablelist
[[Returns:] [Returns how many bytes the operating system allocates for one page.]]
[[Throws:] [Nothing.]]
]

[heading `std::size_t page_count( std::size_t stacksize)`]
[variablelist
[[Returns:] [Returns how many pages have to be allocated for a stack of `stacksize` bytes.]]
[[Throws:] [Nothing.]]
]

[endsect]

[endsect]