fls.qbk
4.35 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
[/
(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]