]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [/ |
2 | (C) Copyright 2007-8 Anthony Williams. | |
3 | (C) Copyright 2013 Oliver Kowalke. | |
4 | Distributed under the Boost Software License, Version 1.0. | |
5 | (See accompanying file LICENSE_1_0.txt or copy at | |
6 | http://www.boost.org/LICENSE_1_0.txt). | |
7 | ] | |
8 | ||
9 | [section:fls Fiber local storage] | |
10 | ||
11 | [heading Synopsis] | |
12 | ||
13 | Fiber local storage allows a separate instance of a given data item for | |
14 | each fiber. | |
15 | ||
16 | [heading Cleanup at fiber exit] | |
17 | ||
18 | When a fiber exits, the objects associated with each __fsp__ instance are | |
19 | destroyed. By default, the object pointed to by a pointer `p` is destroyed by | |
20 | invoking `delete p`, but this can be overridden for a specific instance of | |
21 | __fsp__ by providing a cleanup routine `func` to the constructor. In this case, the | |
22 | object is destroyed by invoking `func(p)`. The cleanup functions are called in an unspecified | |
23 | order. | |
24 | ||
25 | [class_heading fiber_specific_ptr] | |
26 | ||
27 | #include <boost/fiber/fss.hpp> | |
28 | ||
29 | namespace boost { | |
30 | namespace fibers { | |
31 | ||
32 | template< typename T > | |
33 | class fiber_specific_ptr { | |
34 | public: | |
35 | typedef T element_type; | |
36 | ||
37 | fiber_specific_ptr(); | |
38 | ||
39 | explicit fiber_specific_ptr( void(*fn)(T*) ); | |
40 | ||
41 | ~fiber_specific_ptr(); | |
42 | ||
43 | fiber_specific_ptr( fiber_specific_ptr const&) = delete; | |
44 | fiber_specific_ptr & operator=( fiber_specific_ptr const&) = delete; | |
45 | ||
46 | T * get() const noexcept; | |
47 | ||
48 | T * operator->() const noexcept; | |
49 | ||
50 | T & operator*() const noexcept; | |
51 | ||
52 | T * release(); | |
53 | ||
54 | void reset( T *); | |
55 | }; | |
56 | ||
57 | }} | |
58 | ||
59 | [heading Constructor] | |
60 | ||
61 | fiber_specific_ptr(); | |
62 | explicit fiber_specific_ptr( void(*fn)(T*) ); | |
63 | ||
64 | [variablelist | |
65 | [[Requires:] [`delete this->get()` is well-formed; `fn(this->get())` does not | |
66 | throw]] | |
67 | [[Effects:] [Construct a __fsp__ object for storing a pointer to an object of | |
68 | type `T` specific to each fiber. When `reset()` is called, or the | |
69 | fiber exits, __fsp__ calls `fn(this->get())`. If the no-arguments constructor | |
70 | is used, the default `delete`-based cleanup function | |
71 | will be used to destroy the fiber-local objects.]] | |
72 | [[Throws:] [__fiber_error__ if an error occurs.]] | |
73 | ] | |
74 | ||
75 | [heading Destructor] | |
76 | ||
77 | ~fiber_specific_ptr(); | |
78 | ||
79 | [variablelist | |
80 | [[Requires:] [All the fiber specific instances associated to this __fsp__ | |
81 | (except maybe the one associated to this fiber) must be nullptr.]] | |
82 | [[Effects:] [Calls `this->reset()` to clean up the associated value for the | |
83 | current fiber, and destroys `*this`.]] | |
84 | [[Remarks:] [The requirement is an implementation restriction. If the | |
85 | destructor promised to delete instances for all fibers, the implementation | |
86 | would be forced to maintain a list of all the fibers having an associated | |
87 | specific ptr, which is against the goal of fiber specific data. In general, a | |
88 | __fsp__ should outlive the fibers that use it.]] | |
89 | ] | |
90 | [note Care needs to be taken to ensure that any fibers still running after an | |
91 | instance of __fsp__ has been destroyed do not call any member functions on that | |
92 | instance.] | |
93 | ||
94 | [member_heading fiber_specific_ptr..get] | |
95 | ||
96 | T * get() const noexcept; | |
97 | ||
98 | [variablelist | |
99 | [[Returns:] [The pointer associated with the current fiber.]] | |
100 | [[Throws:] [Nothing.]] | |
101 | ] | |
102 | [note The initial value associated with an instance of __fsp__ is `nullptr` for | |
103 | each fiber.] | |
104 | ||
105 | [operator_heading fiber_specific_ptr..operator_arrow..operator->] | |
106 | ||
107 | T * operator->() const noexcept; | |
108 | ||
109 | [variablelist | |
110 | [[Requires:] [`this->get()` is not `nullptr`.]] | |
111 | [[Returns:] [`this->get()`]] | |
112 | [[Throws:] [Nothing.]] | |
113 | ] | |
114 | ||
115 | [operator_heading fiber_specific_ptr..operator_star..operator*] | |
116 | ||
117 | T & operator*() const noexcept; | |
118 | ||
119 | [variablelist | |
120 | [[Requires:] [`this->get()` is not `nullptr`.]] | |
121 | [[Returns:] [`*(this->get())`]] | |
122 | [[Throws:] [Nothing.]] | |
123 | ] | |
124 | ||
125 | [member_heading fiber_specific_ptr..release] | |
126 | ||
127 | T * release(); | |
128 | ||
129 | [variablelist | |
130 | [[Effects:] [Return `this->get()` and store `nullptr` as the pointer associated | |
131 | with the current fiber without invoking the cleanup function.]] | |
132 | [[Postcondition:] [`this->get()==nullptr`]] | |
133 | [[Throws:] [Nothing.]] | |
134 | ] | |
135 | ||
136 | [member_heading fiber_specific_ptr..reset] | |
137 | ||
138 | void reset( T * new_value); | |
139 | ||
140 | [variablelist | |
141 | [[Effects:] [If `this->get()!=new_value` and `this->get()` is not `nullptr`, | |
142 | invoke `delete this->get()` or `fn(this->get())` as appropriate. Store | |
143 | `new_value` as the pointer associated with the current fiber.]] | |
144 | [[Postcondition:] [`this->get()==new_value`]] | |
145 | [[Throws:] [Exception raised during cleanup of previous value.]] | |
146 | ] | |
147 | ||
148 | [endsect] |