-[/
- Copyright Oliver Kowalke 2009.
+[/ 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__.
+by a __stack_allocator__ (examples contain an implementation
+of [@boost:/libs/context/example/simple_stack_allocator.hpp
+simple_stack_allocator]).
-[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
+[note The implementation of a __stack_allocator__ 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();
+__make_fcontext__.]
- 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]
+[note Depending on the architecture __stack_allocator__ returns an address from
+the top of the stack (grows downwards) or the bottom of the stack (grows
+upwards).]
[endsect]
projects / platform / upstream / boost.git / blobdiff