Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

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

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

updated boost from 1_33_1 to 1_34_1
File size: 5.1 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>Boost Pool Interfaces</title>
11</head>
12
13<body>
14  <img src="../../../boost.png" width="276" height="86" alt="C++ Boost">
15
16  <h1 align="center">Boost Pool Interfaces</h1>
17
18  <h2>Introduction</h2>
19
20  <p>There are several interfaces provided which allow users great flexibility
21  in how they want to use Pools. Review the <a href=
22  "concepts.html">concepts document</a> to get the basic understanding of how
23  Pools work.</p>
24
25  <h2>Terminology and Tradeoffs</h2>
26
27  <h3>Object Usage vs. Singleton Usage</h3>
28
29  <p><em>Object Usage</em> is the method where each Pool is an object that may
30  be created and destroyed. Destroying a Pool implicitly frees all chunks that
31  have been allocated from it.</p>
32
33  <p><em>Singleton Usage</em> is the method where each Pool is an object with
34  static duration; that is, it will not be destroyed until program exit. Pool
35  objects with Singleton Usage may be shared; thus, Singleton Usage implies
36  thread-safety as well. System memory allocated by Pool objects with
37  Singleton Usage may be freed through <span class=
38  "code">release_memory</span> or <span class="code">purge_memory</span>.</p>
39
40  <h3>Out-of-Memory Conditions: Exceptions vs. Null Return</h3>
41
42  <p>Some Pool interfaces throw exceptions when out-of-memory; others will
43  return 0. In general, unless mandated by the Standard, Pool interfaces will
44  always prefer to return 0 instead of throw an exception.</p>
45
46  <h2>The Interfaces</h2>
47
48  <h3>pool</h3>
49
50  <p>The <a href="interfaces/pool.html">pool interface</a> is a simple Object
51  Usage interface with Null Return.</p>
52
53  <p>Example:</p>
54  <pre class="code">
55void func()
56{
57  boost::pool&lt;&gt; p(sizeof(int));
58  for (int i = 0; i &lt; 10000; ++i)
59  {
60    int * const t = p.malloc();
61    ... // Do something with t; don't take the time to free() it
62  }
63} // on function exit, p is destroyed, and all malloc()'ed ints are implicitly freed
64</pre>
65
66  <h3>object_pool</h3>
67
68  <p>The <a href="interfaces/object_pool.html">object_pool interface</a> is an
69  Object Usage interface with Null Return, but is aware of the type of the
70  object for which it is allocating chunks. On destruction, any chunks that
71  have been allocated from that object_pool will have their destructors
72  called.</p>
73
74  <p>Example:</p>
75  <pre class="code">
76struct X { ... }; // has destructor with side-effects
77
78void func()
79{
80  boost::object_pool&lt;X&gt; p;
81  for (int i = 0; i &lt; 10000; ++i)
82  {
83    X * const t = p.malloc();
84    ... // Do something with t; don't take the time to free() it
85  }
86} // on function exit, p is destroyed, and all destructors for the X objects are called
87</pre>
88
89  <h3>singleton_pool</h3>
90
91  <p>The <a href="interfaces/singleton_pool.html">singleton_pool interface</a> 
92  is a Singleton Usage interface with Null Return. It's just the same as the
93  pool interface but with Singleton Usage instead.</p>
94
95  <p>Example:</p>
96  <pre class="code">
97struct MyPoolTag { };
98
99typedef boost::singleton_pool&lt;MyPoolTag, sizeof(int)&gt; my_pool;
100void func()
101{
102  for (int i = 0; i &lt; 10000; ++i)
103  {
104    int * const t = my_pool::malloc();
105    ... // Do something with t; don't take the time to free() it
106  }
107  // Explicitly free all malloc()'ed int's
108  my_pool::purge_memory();
109}
110</pre>
111
112  <h3>pool_alloc</h3>
113
114  <p>The <a href="interfaces/pool_alloc.html">pool_alloc interface</a> is a
115  Singleton Usage interface with Exceptions. It is built on the singleton_pool
116  interface, and provides a Standard Allocator-compliant class (for use in
117  containers, etc.).</p>
118
119  <p>Example:</p>
120  <pre class="code">
121void func()
122{
123  std::vector&lt;int, boost::pool_allocator&lt;int&gt; &gt; v;
124  for (int i = 0; i &lt; 10000; ++i)
125    v.push_back(13);
126} // Exiting the function does NOT free the system memory allocated by the pool allocator
127  // You must call
128  //  boost::singleton_pool&lt;boost::pool_allocator_tag, sizeof(int)&gt;::release_memory()
129  // in order to force that
130</pre>
131
132  <h2>Future Directions</h2>
133
134  <p>Another pool interface will be written: a base class for per-class pool
135  allocation. This &quot;pool_base&quot; interface will be Singleton Usage with
136  Exceptions, and built on the singleton_pool interface.</p>
137  <hr>
138
139  <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
140  "http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01 Transitional"
141  height="31" width="88"></a></p>
142
143  <p>Revised
144  <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05 December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38516" --></p>
145
146  <p><i>Copyright &copy; 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)</i></p>
147
148  <p><i>Distributed under the Boost Software License, Version 1.0. (See
149  accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
150  copy at <a href=
151  "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
152</body>
153</html>
Note: See TracBrowser for help on using the repository browser.