| Home | Libraries | People | FAQ | More

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