mirror of
https://github.com/boostorg/fiber.git
synced 2026-02-21 02:52:18 +00:00
87551c5419
Highlight predicate condition_variable::wait() method in condition_variable front matter. Rewrite the explanation of wait()'s Precondition. Add a condition_variables subsection about no spurious condition_variable wakeups. Remove "or spuriously" from wakeup conditions in wait*() methods. First pass through "spurious wakeup" section in Rationale. First pass through migration.qbk. Use lock_t throughout work_sharing.cpp, instead of lock_t, lock_count and explicit std::unique_lock<std::mutex> declarations. Unify treatment of main and dispatcher fibers. Clarify thread-safety requirements on sched_algorithm::notify() and suspend_until(). Clarify disable_interruption when rethrowing fiber_interrupted. Consolidate future<T>::get(): returns T whether T is R, R& or void. Mention nesting of disable_interruption (which matters) versus nesting of restore_interruption (which doesn't). Mention that a disable_interruption constructed within the scope of another disable_interruption is a no-op, both itself and when passed to restore_interruption. When packaged_task::operator()() stores a value or an exception, state "as if" by promise::set_value() or set_exception(): the shared state is set ready. Similarly for ~packaged_task() and ~promise() setting broken_promise. Sprinkle links to the Allocator concept, std::allocator and std::allocator_arg_t where referenced. Similarly for StackAllocator. Add more cross-reference links where Fiber classes and methods are mentioned. Also things like std::unique_lock and std::mutex. Clarify error condition for value_pop() when channel is close()d. Since fiber_specific_ptr::release() does not invoke cleanup, it should not throw an exception raised during cleanup.
144 lines
4.3 KiB
Plaintext
144 lines
4.3 KiB
Plaintext
[/
|
|
(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>
|
|
|
|
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]
|