Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/pool/doc/interfaces/singleton_pool.html @ 29

Last change on this file since 29 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 8.0 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2"http://www.w3.org/TR/html4/loose.dtd">
3
4<html>
5<head>
6  <meta http-equiv="Content-Language" content="en-us">
7  <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
8  <link href="../pool.css" rel="stylesheet" type="text/css">
9
10  <title>Singleton Pool</title>
11</head>
12
13<body>
14  <img src="../../../../boost.png" width="276" height="86" alt="C++ Boost">
15
16  <h1 align="center">Singleton Pool</h1>
17
18  <h2>Introduction</h2>
19
20  <p>singleton_pool.hpp provides a template class <span class=
21  "code">singleton_pool</span>, which provides access to a <span class=
22  "code">pool</span> as a singleton object. For information on other
23  pool-based interfaces, see <a href="../interfaces.html">the other pool
24  interfaces</a>.</p>
25
26  <h2>Synopsis</h2>
27  <pre class="code">
28template &lt;typename Tag, unsigned RequestedSize,
29    typename UserAllocator = default_user_allocator_new_delete&gt;
30struct singleton_pool
31{
32  public:
33    typedef Tag tag;
34    typedef UserAllocator user_allocator;
35    typedef typename pool&lt;UserAllocator&gt;::size_type size_type;
36    typedef typename pool&lt;UserAllocator&gt;::difference_type difference_type;
37
38    static const unsigned requested_size = RequestedSize;
39
40  private:
41    static pool&lt;size_type&gt; p; // exposition only!
42
43    singleton_pool();
44
45  public:
46    static bool is_from(void * ptr);
47
48    static void * malloc();
49    static void * ordered_malloc();
50    static void * ordered_malloc(size_type n);
51
52    static void free(void * ptr);
53    static void ordered_free(void * ptr);
54    static void free(void * ptr, std::size_t n);
55    static void ordered_free(void * ptr, size_type n);
56
57    static bool release_memory();
58    static bool purge_memory();
59};
60</pre>
61
62  <h2>Notes</h2>
63
64  <p>The underlying pool <span class="code">p</span> referenced by the static
65  functions in <span class="code">singleton_pool</span> is actually declared
66  in a way that it is:</p>
67
68  <ul>
69    <li>Thread-safe if there is only one thread running before main() begins
70    and after main() ends -- all of the static functions of <span class=
71    "code">singleton_pool</span> synchronize their access to <span class=
72    "code">p</span>.</li>
73
74    <li>Guaranteed to be constructed before it is used -- thus, the simple
75    static object in the synopsis above would actually be an incorrect
76    implementation. The actual <a href=
77    "../implementation/singleton_pool.html">implementation</a> to guarantee
78    this is considerably more complicated.</li>
79  </ul>
80
81  <p>Note that a different underlying pool <span class="code">p</span> exists
82  for each different set of template parameters, including <a href=
83  "../implementation/singleton_pool.html">implementation-specific
84  ones</a>.</p>
85
86  <h2>Template Parameters</h2>
87
88  <h3>Tag</h3>
89
90  <p>The <span class="code">Tag</span> template parameter allows different
91  unbounded sets of singleton pools to exist. For example, the <a href=
92  "pool_alloc.html">pool allocators</a> use two tag classes to ensure that
93  the two different allocator types never share the same underlying singleton
94  pool.</p>
95
96  <p><span class="code">Tag</span> is never actually used by <span class=
97  "code">singleton_pool</span>.</p>
98
99  <h3>RequestedSize</h3>
100
101  <p>The requested size of memory chunks to allocate. This is passed as a
102  constructor parameter to the underlying <span class="code">pool</span>.
103  Must be greater than 0.</p>
104
105  <h3>UserAllocator</h3>
106
107  <p>Defines the method that the underlying <span class="code">pool</span>
108  will use to allocate memory from the system. See <a href=
109  "user_allocator.html">User Allocators</a> for details.</p>
110
111  <h2>Semantics</h2>
112
113  <table border align="center" summary="">
114    <caption>
115      <em>Symbol Table</em>
116    </caption>
117
118    <tr>
119      <th>Symbol</th>
120
121      <th>Meaning</th>
122    </tr>
123
124    <tr>
125      <td class="code">SingletonPool</td>
126
127      <td class="code">singleton_pool&lt;Tag, RequestedSize,
128      UserAllocator&gt;</td>
129    </tr>
130
131    <tr>
132      <td class="code">chunk</td>
133
134      <td>value of type <span class="code">void *</span></td>
135    </tr>
136
137    <tr>
138      <td class="code">n</td>
139
140      <td>value of type <span class="code">size_type</span></td>
141    </tr>
142  </table><br>
143
144  <table border align="center" summary="">
145    <caption>
146      <em>Typedefs/Static Const Values</em>
147    </caption>
148
149    <tr>
150      <th>Expression</th>
151
152      <th>Type/Value</th>
153    </tr>
154
155    <tr>
156      <td class="code">SingletonPool::tag</td>
157
158      <td class="code">Tag</td>
159    </tr>
160
161    <tr>
162      <td class="code">SingletonPool::user_allocator</td>
163
164      <td class="code">UserAllocator</td>
165    </tr>
166
167    <tr>
168      <td class="code">SingletonPool::size_type</td>
169
170      <td class="code">pool&lt;UserAllocator&gt;::size_type</td>
171    </tr>
172
173    <tr>
174      <td class="code">SingletonPool::difference_type</td>
175
176      <td class="code">pool&lt;UserAllocator&gt;::difference_type</td>
177    </tr>
178
179    <tr>
180      <td class="code">SingletonPool::requested_size</td>
181
182      <td class="code">RequestedSize</td>
183    </tr>
184  </table><br>
185
186  <table border align="center" summary="">
187    <caption>
188      <em>Functions</em>
189    </caption>
190
191    <tr>
192      <th>Expression</th>
193
194      <th>Return Type</th>
195
196      <th>Semantic Equivalent</th>
197    </tr>
198
199    <tr>
200      <td class="code">SingletonPool::is_from(chunk)</td>
201
202      <td class="code">bool</td>
203
204      <td><span class="code">SingletonPool::p.is_from(chunk);</span>
205      synchronized</td>
206    </tr>
207
208    <tr>
209      <td class="code">SingletonPool::malloc()</td>
210
211      <td class="code">void *</td>
212
213      <td><span class="code">SingletonPool::p.malloc();</span>
214      synchronized</td>
215    </tr>
216
217    <tr>
218      <td class="code">SingletonPool::ordered_malloc(n)</td>
219
220      <td class="code">void *</td>
221
222      <td><span class="code">SingletonPool::p.ordered_malloc(n);</span>
223      synchronized</td>
224    </tr>
225
226    <tr>
227      <td class="code">SingletonPool::free(chunk)</td>
228
229      <td class="code">void</td>
230
231      <td><span class="code">SingletonPool::p.free(chunk);</span>
232      synchronized</td>
233    </tr>
234
235    <tr>
236      <td class="code">SingletonPool::ordered_free(chunk)</td>
237
238      <td class="code">void</td>
239
240      <td><span class="code">SingletonPool::p.ordered_free(chunk);</span>
241      synchronized</td>
242    </tr>
243
244    <tr>
245      <td class="code">SingletonPool::free(chunk, n)</td>
246
247      <td class="code">void</td>
248
249      <td><span class="code">SingletonPool::p.free(chunk, n);</span>
250      synchronized</td>
251    </tr>
252
253    <tr>
254      <td class="code">SingletonPool::ordered_free(chunk, n)</td>
255
256      <td class="code">void</td>
257
258      <td><span class="code">SingletonPool::p.ordered_free(chunk, n);</span>
259      synchronized</td>
260    </tr>
261
262    <tr>
263      <td class="code">SingletonPool::release_memory()</td>
264
265      <td class="code">bool</td>
266
267      <td><span class="code">SingletonPool::p.release_memory();</span>
268      synchronized</td>
269    </tr>
270
271    <tr>
272      <td class="code">SingletonPool::purge_memory()</td>
273
274      <td class="code">bool</td>
275
276      <td><span class="code">SingletonPool::p.purge_memory();</span>
277      synchronized</td>
278    </tr>
279  </table>
280
281  <p>For more information on the semantics of these functions, see the
282  <a href="pool.html">pool interface</a>.</p>
283
284  <h2>Symbols</h2>
285
286  <ul>
287    <li>boost::singleton_pool</li>
288  </ul>
289
290  <h2><a href="../implementation/singleton_pool.html">Implementation
291  Details</a></h2>
292  <hr>
293
294  <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
295  "http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01 Transitional"
296  height="31" width="88"></a></p>
297
298  <p>Revised
299  <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05 December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38516" --></p>
300
301  <p><i>Copyright &copy; 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)</i></p>
302
303  <p><i>Distributed under the Boost Software License, Version 1.0. (See
304  accompanying file <a href="../../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a>
305  or copy at <a href=
306  "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
307</body>
308</html>
Note: See TracBrowser for help on using the repository browser.