Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for a snapshot of the develop branch, built from commit 4e6c143b17.
PrevUpHomeNext

Fiber local storage

Synopsis

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

Cleanup at fiber exit

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] 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] 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.


PrevUpHomeNext