Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/libs/pool/doc/interfaces.html @ 12

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

added boost
File size: 4.5 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 
2<HTML>
3<HEAD>
4<TITLE>Boost Pool Interfaces</TITLE>
5<LINK HREF="pool.css" REL="stylesheet" TYPE="text/css">
6</HEAD>
7<BODY>
8
9<IMG SRC="../../../boost.png" WIDTH=276 HEIGHT=86 ALT="C++ Boost">
10
11<H1 ALIGN=CENTER>Boost Pool Interfaces</H1>
12
13<P>
14<H2>Introduction</H2>
15
16<P>
17There are several interfaces provided which allow users great flexibility in how they want to use Pools.  Review the <A HREF="concepts.html">concepts document</A> to get the basic understanding of how Pools work.
18
19<P>
20<H2>Terminology and Tradeoffs</H2>
21
22<P>
23<H3>Object Usage vs. Singleton Usage</H3>
24
25<P>
26<EM>Object Usage</EM> is the method where each Pool is an object that may be created and destroyed.  Destroying a Pool implicitly frees all chunks that have been allocated from it.
27
28<P>
29<EM>Singleton Usage</EM> is the method where each Pool is an object with static duration; that is, it will not be destroyed until program exit.  Pool objects with Singleton Usage may be shared; thus, Singleton Usage implies thread-safety as well.  System memory allocated by Pool objects with Singleton Usage may be freed through <SPAN CLASS="code">release_memory</SPAN> or <SPAN CLASS="code">purge_memory</SPAN>.
30
31<P>
32<H3>Out-of-Memory Conditions: Exceptions vs. Null Return</H3>
33
34<P>
35Some Pool interfaces throw exceptions when out-of-memory; others will return 0.  In general, unless mandated by the Standard, Pool interfaces will always prefer to return 0 instead of throw an exception.
36
37<P>
38<H2>The Interfaces</H2>
39
40<P>
41<H3>pool</H3>
42
43<P>
44The <A HREF="interfaces/pool.html">pool interface</A> is a simple Object Usage interface with Null Return.
45
46<P>
47Example:
48<PRE CLASS="code">void func()
49{
50  boost::pool&lt;&gt; p(sizeof(int));
51  for (int i = 0; i < 10000; ++i)
52  {
53    int * const t = p.malloc();
54    ... // Do something with t; don't take the time to free() it
55  }
56} // on function exit, p is destroyed, and all malloc()'ed ints are implicitly freed</PRE>
57
58<P>
59<H3>object_pool</H3>
60
61<P>
62The <A HREF="interfaces/object_pool.html">object_pool interface</A> is an Object Usage interface with Null Return, but is aware of the type of the object for which it is allocating chunks.  On destruction, any chunks that have been allocated from that object_pool will have their destructors called.
63
64<P>
65Example:
66<PRE CLASS="code">struct X { ... }; // has destructor with side-effects
67
68void func()
69{
70  boost::object_pool&lt;X&gt; p;
71  for (int i = 0; i < 10000; ++i)
72  {
73    X * const t = p.malloc();
74    ... // Do something with t; don't take the time to free() it
75  }
76} // on function exit, p is destroyed, and all destructors for the X objects are called</PRE>
77
78<P>
79<H3>singleton_pool</H3>
80
81<P>
82The <A HREF="interfaces/singleton_pool.html">singleton_pool interface</A> is a Singleton Usage interface with Null Return.  It's just the same as the pool interface but with Singleton Usage instead.
83
84<P>
85Example:
86<PRE CLASS="code">struct MyPoolTag { };
87
88typedef boost::singleton_pool&lt;MyPoolTag, sizeof(int)&gt; my_pool;
89void func()
90{
91  for (int i = 0; i < 10000; ++i)
92  {
93    int * const t = my_pool::malloc();
94    ... // Do something with t; don't take the time to free() it
95  }
96  // Explicitly free all malloc()'ed int's
97  my_pool::purge_memory();
98}</PRE>
99
100<P>
101<H3>pool_alloc</H3>
102
103<P>
104The <A HREF="interfaces/pool_alloc.html">pool_alloc interface</A> is a Singleton Usage interface with Exceptions.  It is built on the singleton_pool interface, and provides a Standard Allocator-compliant class (for use in containers, etc.).
105
106<P>
107Example:
108<PRE CLASS="code">void func()
109{
110  std::vector&lt;int, boost::pool_allocator&lt;int&gt; &gt; v;
111  for (int i = 0; i < 10000; ++i)
112    v.push_back(13);
113} // Exiting the function does NOT free the system memory allocated by the pool allocator
114  // You must call
115  //  boost::singleton_pool&lt;boost::pool_allocator_tag, sizeof(int)&gt;::release_memory()
116  // in order to force that</PRE>
117
118<P>
119<H2>Future Directions</H2>
120
121<P>
122Another pool interface will be written: a base class for per-class pool allocation.  This &quot;pool_base&quot; interface will be Singleton Usage with Exceptions, and built on the singleton_pool interface.
123
124<P>
125<HR>
126
127<P>
128Copyright &copy; 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)
129
130<P>
131This file can be redistributed and/or modified under the terms found in <A HREF="copyright.html">copyright.html</A>
132
133<P>
134This software and its documentation is provided &quot;as is&quot; without express or implied warranty, and with no claim as to its suitability for any purpose.
135
136</BODY>
137</HTML>
Note: See TracBrowser for help on using the repository browser.