context/doc/stack.qbk

[/
          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__ provides the default implementation `stack_allocator` but a
customized __stack_allocator__ can be used instead.

[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()`.]

[note Depending on the architecture `allocate()` returns an address from the
top of the stack (growing downwards) or the bottom of the stack (growing
upwards).]


[section:guarded_stack_allocator Class `guarded_stack_allocator`]

__boost_context__ provides the class `guarded_stack_allocator` which models
the __stack_allocator_concept__ 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.]

        class guarded_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( std::size_t size);

            void deallocate( void * sp, std::size_t size);
        }

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

[heading `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 std::size_t default_stacksize()`]
[variablelist
[[Returns:] [Returns a default stack size, which may be platform specific.
If the stack is unbound then the present implementation returns the maximum of
`64 kB` and `minimum_stacksize()`.]]
]

[heading `static std::size_t minimum_stacksize()`]
[variablelist
[[Returns:] [Returns the minimum size in bytes of stack defined by the
environment (Win32 4kB/Win64 8kB, defined by rlimit on POSIX).]]
]

[heading `void * allocate( std::size_t size)`]
[variablelist
[[Preconditions:] [`minimum_stacksize() > size` and
`! is_stack_unbound() && ( maximum_stacksize() < size)`.]]
[[Effects:] [Allocates memory of `size` Bytes and appends one guard page at the
end of the allocated memory.]]
[[Returns:] [Returns pointer to the start address of the new stack. Depending
on the architecture the stack grows downwards/upwards the returned address is
the highest/lowest address of the stack.]]
]

[heading `void deallocate( void * sp, std::size_t size)`]
[variablelist
[[Preconditions:] [`sp` is valid, `minimum_stacksize() > size` and
`! is_stack_unbound() && ( maximum_stacksize() < size)`.]]
[[Effects:] [Deallocates the stack space.]]
]

[endsect]


[section:simple_stack_allocator Template `simple_stack_allocator< size_t, size_t, size_t >`]

__boost_context__ provides the class `simple_stack_allocator` which models
the __stack_allocator_concept__ concept. The template arguments define the
limits for the stack size.
The class simply allocates memory on the heap via `calloc()` - in contrast to
`guarded_stack_allocator` no guard page is appended.

[important The user is responsible for valid stack limits (e.g. maximum, minimum
and default stacksize.]

        template< size_t Max, size_t Default, size_t Min >
        class simple_stack_allocator
        {
            static std::size_t maximum_stacksize();

            static std::size_t default_stacksize();

            static std::size_t minimum_stacksize();

            void * allocate( std::size_t size);

            void deallocate( void * sp, std::size_t size);
        }

[heading `static std::size_t maximum_stacksize()`]
[variablelist
[[Returns:] [Returns the maximum size in bytes of stack defined by the first
tempalte argument.]]
]

[heading `static std::size_t default_stacksize()`]
[variablelist
[[Returns:] [Returns a default stack size in bytes defined by the second
template argument.]]
]

[heading `static std::size_t minimum_stacksize()`]
[variablelist
[[Returns:] [Returns the minimum size in bytes of stack defined by the
third template argument.]]
]

[heading `void * allocate( std::size_t size)`]
[variablelist
[[Preconditions:] [`minimum_stacksize() > size` and
`maximum_stacksize() < size`.]]
[[Effects:] [Allocates memory of `size` bytes (memory is set to NULL).]]
[[Returns:] [Returns pointer to the start address of the new stack. Depending
on the architecture the stack grows downwards/upwards the returned address is
the highest/lowest address of the stack.]]
]

[heading `void deallocate( void * sp, std::size_t size)`]
[variablelist
[[Preconditions:] [`sp` is valid, `minimum_stacksize() > size` and
`maximum_stacksize() < size`.]]
[[Effects:] [Deallocates the stack space.]]
]

[endsect]


[section:pagesize Free function `pagesize()`]

        std::size_t pagesize();

[heading `std::size_t pagesize()`]
[variablelist
[[Returns:] [Returns the size of a page in bytes.]]
]

This function

[endsect]

[endsect]