← Back to branch summary

~ubuntu-branches/ubuntu/wily/davix/wily

« back to all changes in this revision

Viewing changes to deps/boost_intern/src/thread/doc/tss.qbk

  • Committer: Package Import Robot
  • Author(s): Mattias Ellert
  • Date: 2015-07-31 13:17:55 UTC
  • mfrom: (5.1.3 sid)
  • Revision ID: package-import@ubuntu.com-20150731131755-mizprbmn7ogv33te
Tags: 0.4.1-1
* Update to version 0.4.1
* Implement Multi-Arch support

Show diffs side-by-side

added added

removed removed

Lines of Context:
deps/boost_intern/src/thread/doc/tss.qbk
1
 
[/
2
 
  (C) Copyright 2007-8 Anthony Williams.
3
 
  Distributed under the Boost Software License, Version 1.0.
4
 
  (See accompanying file LICENSE_1_0.txt or copy at
5
 
  http://www.boost.org/LICENSE_1_0.txt).
6
 
]
7
 
 
8
 
[section Thread Local Storage]
9
 
 
10
 
[heading Synopsis]
11
 
 
12
 
Thread local storage allows multi-threaded applications to have a separate instance of a given data item for each thread. Where a
13
 
single-threaded application would use static or global data, this could lead to contention, deadlock or data corruption in a
14
 
multi-threaded application. One example is the C `errno` variable, used for storing the error code related to functions from the
15
 
Standard C library. It is common practice (and required by POSIX) for compilers that support multi-threaded applications to provide
16
 
a separate instance of `errno` for each thread, in order to avoid different threads competing to read or update the value.
17
 
 
18
 
Though compilers often provide this facility in the form of extensions to the declaration syntax (such as `__declspec(thread)` or
19
 
`__thread` annotations on `static` or namespace-scope variable declarations), such support is non-portable, and is often limited in
20
 
some way, such as only supporting POD types.
21
 
 
22
 
[heading Portable thread-local storage with `boost::thread_specific_ptr`]
23
 
 
24
 
`boost::thread_specific_ptr` provides a portable mechanism for thread-local storage that works on all compilers supported by
25
 
__boost_thread__. Each instance of `boost::thread_specific_ptr` represents a pointer to an object (such as `errno`) where each
26
 
thread must have a distinct value. The value for the current thread can be obtained using the `get()` member function, or by using
27
 
the `*` and `->` pointer deference operators. Initially the pointer has a value of `NULL` in each thread, but the value for the
28
 
current thread can be set using the `reset()` member function.
29
 
 
30
 
If the value of the pointer for the current thread is changed using `reset()`, then the previous value is destroyed by calling the
31
 
cleanup routine. Alternatively, the stored value can be reset to `NULL` and the prior value returned by calling the `release()`
32
 
member function, allowing the application to take back responsibility for destroying the object.
33
 
 
34
 
[heading Cleanup at thread exit]
35
 
 
36
 
When a thread exits, the objects associated with each `boost::thread_specific_ptr` instance are destroyed. By default, the object
37
 
pointed to by a pointer `p` is destroyed by invoking `delete p`, but this can be overridden for a specific instance of
38
 
`boost::thread_specific_ptr` by providing a cleanup routine to the constructor. In this case, the object is destroyed by invoking
39
 
`func(p)` where `func` is the cleanup routine supplied to the constructor. The cleanup functions are called in an unspecified
40
 
order. If a cleanup routine sets the value of associated with an instance of `boost::thread_specific_ptr` that has already been
41
 
cleaned up, that value is added to the cleanup list. Cleanup finishes when there are no outstanding instances of
42
 
`boost::thread_specific_ptr` with values.
43
 
 
44
 
Note: on some platforms, cleanup of thread-specific data is not
45
 
performed for threads created with the platform's native API. On those
46
 
platforms such cleanup is only done for threads that are started with
47
 
`boost::thread` unless `boost::on_thread_exit()` is called manually
48
 
from that thread.
49
 
 
50
 
[heading Rationale about the nature of the key]
51
 
 
52
 
Boost.Thread uses the address of the `thread_specific_ptr` instance as key of the thread specific pointers. This avoids to create/destroy a key which will need a lock to protect from race conditions. This has a little performance liability, as the access must be done using an associative container.
53
 
 
54
 
[section:thread_specific_ptr Class `thread_specific_ptr`]
55
 
 
56
 
  //  #include <boost/thread/tss.hpp>
57
 
 
58
 
  namespace boost
59
 
  {
60
 
    template <typename T>
61
 
    class thread_specific_ptr
62
 
    {
63
 
    public:
64
 
        thread_specific_ptr();
65
 
        explicit thread_specific_ptr(void (*cleanup_function)(T*));
66
 
        ~thread_specific_ptr();
67
 
 
68
 
        T* get() const;
69
 
        T* operator->() const;
70
 
        T& operator*() const;
71
 
 
72
 
        T* release();
73
 
        void reset(T* new_value=0);
74
 
    };
75
 
  }
76
 
 
77
 
[section:default_constructor `thread_specific_ptr();`]
78
 
 
79
 
[variablelist
80
 
 
81
 
[[Requires:] [`delete this->get()` is well-formed.]]
82
 
 
83
 
[[Effects:] [Construct a `thread_specific_ptr` object for storing a pointer to an object of type `T` specific to each thread. The
84
 
default `delete`-based cleanup function will be used to destroy any thread-local objects when `reset()` is called, or the thread
85
 
exits.]]
86
 
 
87
 
[[Throws:] [`boost::thread_resource_error` if an error occurs.]]
88
 
 
89
 
]
90
 
 
91
 
[endsect]
92
 
 
93
 
[section:constructor_with_custom_cleanup `explicit thread_specific_ptr(void (*cleanup_function)(T*));`]
94
 
 
95
 
[variablelist
96
 
 
97
 
[[Requires:] [`cleanup_function(this->get())` does not throw any exceptions.]]
98
 
 
99
 
[[Effects:] [Construct a `thread_specific_ptr` object for storing a pointer to an object of type `T` specific to each thread. The
100
 
supplied `cleanup_function` will be used to destroy any thread-local objects when `reset()` is called, or the thread exits.]]
101
 
 
102
 
[[Throws:] [`boost::thread_resource_error` if an error occurs.]]
103
 
 
104
 
]
105
 
 
106
 
[endsect]
107
 
 
108
 
[section:destructor `~thread_specific_ptr();`]
109
 
 
110
 
[variablelist
111
 
 
112
 
[[Requires:] [All the thread specific instances associated to this thread_specific_ptr (except maybe the one associated to this thread) must be null.]]
113
 
 
114
 
[[Effects:] [Calls `this->reset()` to clean up the associated value for the current thread, and destroys `*this`.]]
115
 
 
116
 
[[Throws:] [Nothing.]]
117
 
 
118
 
[[Remarks:] [The requirement is due to the fact that in order to delete all these instances, the implementation should be forced to maintain a list of all the threads having an associated specific ptr, which is against the goal of thread specific data.]]
119
 
 
120
 
]
121
 
 
122
 
[note Care needs to be taken to ensure that any threads still running after an instance of `boost::thread_specific_ptr` has been
123
 
destroyed do not call any member functions on that instance.]
124
 
 
125
 
[endsect]
126
 
 
127
 
[section:get `T* get() const;`]
128
 
 
129
 
[variablelist
130
 
 
131
 
[[Returns:] [The pointer associated with the current thread.]]
132
 
 
133
 
[[Throws:] [Nothing.]]
134
 
 
135
 
]
136
 
 
137
 
[note The initial value associated with an instance of `boost::thread_specific_ptr` is `NULL` for each thread.]
138
 
 
139
 
[endsect]
140
 
 
141
 
[section:operator_arrow `T* operator->() const;`]
142
 
 
143
 
[variablelist
144
 
 
145
 
[[Returns:] [`this->get()`]]
146
 
 
147
 
[[Throws:] [Nothing.]]
148
 
 
149
 
]
150
 
 
151
 
[endsect]
152
 
 
153
 
[section:operator_star `T& operator*() const;`]
154
 
 
155
 
[variablelist
156
 
 
157
 
[[Requires:] [`this->get` is not `NULL`.]]
158
 
 
159
 
[[Returns:] [`*(this->get())`]]
160
 
 
161
 
[[Throws:] [Nothing.]]
162
 
 
163
 
]
164
 
 
165
 
[endsect]
166
 
 
167
 
[section:reset `void reset(T* new_value=0);`]
168
 
 
169
 
[variablelist
170
 
 
171
 
[[Effects:] [If `this->get()!=new_value` and `this->get()` is non-`NULL`, invoke `delete this->get()` or
172
 
`cleanup_function(this->get())` as appropriate. Store `new_value` as the pointer associated with the current thread.]]
173
 
 
174
 
[[Postcondition:] [`this->get()==new_value`]]
175
 
 
176
 
[[Throws:] [`boost::thread_resource_error` if an error occurs.]]
177
 
 
178
 
]
179
 
 
180
 
[endsect]
181
 
 
182
 
[section:release `T* release();`]
183
 
 
184
 
[variablelist
185
 
 
186
 
[[Effects:] [Return `this->get()` and store `NULL` as the pointer associated with the current thread without invoking the cleanup
187
 
function.]]
188
 
 
189
 
[[Postcondition:] [`this->get()==0`]]
190
 
 
191
 
[[Throws:] [Nothing.]]
192
 
 
193
 
]
194
 
 
195
 
[endsect]
196
 
 
197
 
 
198
 
[endsect]
199
 
 
200
 
[endsect]