123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148 |
- [/
- (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]
|