[/
  (C) Copyright 2007-8 Anthony Williams.
  (C) Copyright 2013 Oliver Kowalke.
  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:fls Fiber local storage]

[heading Synopsis]

Fiber local storage allows a separate instance of a given data item for
each fiber.

[heading Cleanup at fiber exit]

When a fiber exits, the objects associated with each __fsp__ instance are
destroyed. By default, the object pointed to by a pointer `p` is destroyed by
invoking `delete p`, but this can be overridden for a specific instance of
__fsp__ by providing a cleanup routine `func` to the constructor. In this case, the
object is destroyed by invoking `func(p)`. The cleanup functions are called in an unspecified
order.

[class_heading fiber_specific_ptr]

        #include <boost/fiber/fss.hpp>

        namespace boost {
        namespace fibers {

        template< typename T >
        class fiber_specific_ptr {
        public:
            typedef T   element_type;

            fiber_specific_ptr();

            explicit fiber_specific_ptr( void(*fn)(T*) );

            ~fiber_specific_ptr();

            fiber_specific_ptr( fiber_specific_ptr const&) = delete;
            fiber_specific_ptr & operator=( fiber_specific_ptr const&) = delete;

            T * get() const noexcept;

            T * operator->() const noexcept;

            T & operator*() const noexcept;

            T * release();

            void reset( T *);
        };

        }}

[heading Constructor]

        fiber_specific_ptr();
        explicit fiber_specific_ptr( void(*fn)(T*) );

[variablelist
[[Requires:] [`delete this->get()` is well-formed; `fn(this->get())` does not
throw]]
[[Effects:] [Construct a __fsp__ object for storing a pointer to an object of
type `T` specific to each fiber. When `reset()` is called, or the
fiber exits, __fsp__ calls `fn(this->get())`. If the no-arguments constructor
is used, the default `delete`-based cleanup function
will be used to destroy the fiber-local objects.]]
[[Throws:] [__fiber_error__ if an error occurs.]]
]

[heading Destructor]

        ~fiber_specific_ptr();

[variablelist
[[Requires:] [All the fiber specific instances associated to this __fsp__
(except maybe the one associated to this fiber) must be nullptr.]]
[[Effects:] [Calls `this->reset()` to clean up the associated value for the
current fiber, and destroys `*this`.]]
[[Remarks:] [The requirement is an implementation restriction. If the
destructor promised to delete instances for all fibers, the implementation
would be forced to maintain a list of all the fibers having an associated
specific ptr, which is against the goal of fiber specific data. In general, a
__fsp__ should outlive the fibers that use it.]]
]
[note Care needs to be taken to ensure that any fibers still running after an
instance of __fsp__ has been destroyed do not call any member functions on that
instance.]

[member_heading fiber_specific_ptr..get]

        T * get() const noexcept;

[variablelist
[[Returns:] [The pointer associated with the current fiber.]]
[[Throws:] [Nothing.]]
]
[note The initial value associated with an instance of __fsp__ is `nullptr` for
each fiber.]

[operator_heading fiber_specific_ptr..operator_arrow..operator->]

        T * operator->() const noexcept;

[variablelist
[[Requires:] [`this->get()` is not `nullptr`.]]
[[Returns:] [`this->get()`]]
[[Throws:] [Nothing.]]
]

[operator_heading fiber_specific_ptr..operator_star..operator*]

        T & operator*() const noexcept;

[variablelist
[[Requires:] [`this->get()` is not `nullptr`.]]
[[Returns:] [`*(this->get())`]]
[[Throws:] [Nothing.]]
]

[member_heading fiber_specific_ptr..release]

        T * release();

[variablelist
[[Effects:] [Return `this->get()` and store `nullptr` as the pointer associated
with the current fiber without invoking the cleanup function.]]
[[Postcondition:] [`this->get()==nullptr`]]
[[Throws:] [Nothing.]]
]

[member_heading fiber_specific_ptr..reset]

        void reset( T * new_value);

[variablelist
[[Effects:] [If `this->get()!=new_value` and `this->get()` is not `nullptr`,
invoke `delete this->get()` or `fn(this->get())` as appropriate. Store
`new_value` as the pointer associated with the current fiber.]]
[[Postcondition:] [`this->get()==new_value`]]
[[Throws:] [Exception raised during cleanup of previous value.]]
]

[endsect]