Fiber local storage

Synopsis

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

When a fiber exits, the objects associated with each fiber_specific_ptr 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 fiber_specific_ptr 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 `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 *);
};

}}

Constructor

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

Requires:: delete this->get() is well-formed; fn(this->get()) does not throw
Effects:: Construct a fiber_specific_ptr object for storing a pointer to an object of type T specific to each fiber. When reset() is called, or the fiber exits, fiber_specific_ptr 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.

Destructor

~fiber_specific_ptr();

Requires:: All the fiber specific instances associated to this fiber_specific_ptr (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 fiber_specific_ptr should outlive the fibers that use it.

	Note
	Care needs to be taken to ensure that any fibers still running after an instance of `fiber_specific_ptr` has been destroyed do not call any member functions on that instance.

Member function `get`()

T * get() const noexcept;

Returns:: The pointer associated with the current fiber.
Throws:: Nothing.

	Note
	The initial value associated with an instance of `fiber_specific_ptr` is `nullptr` for each fiber.

Member function `operator->`()

T * operator->() const noexcept;

Requires:: this->get() is not nullptr.
Returns:: this->get()
Throws:: Nothing.

Member function `operator*`()

T & operator*() const noexcept;

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

Member function `release`()

T * release();

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 function `reset`()

void reset( T * new_value);

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.

Boost C++ Libraries