boost/pool
2
0
Fork 0
mirror of https://github.com/boostorg/pool.git synced 2026-02-23 16:02:09 +00:00
Code Issues Projects Releases Wiki Activity

Merged L & C issue fixes & HTML conversions from trunk to branch.

Browse Source 
[SVN r36276]
This commit is contained in:
Andreas Huber
2006-12-05 12:49:43 +00:00
parent c8c2b3538f
commit 0f647e802e
31 changed files with 4261 additions and 1929 deletions
Download Patch File Download Diff File Expand all files Collapse all files

172
doc/interfaces.html
View File

@@ -1,137 +1,153 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<TITLE>Boost Pool Interfaces</TITLE>
<LINK HREF="pool.css" REL="stylesheet" TYPE="text/css">
</HEAD>
<BODY>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<IMG SRC="../../../boost.png" WIDTH=276 HEIGHT=86 ALT="C++ Boost">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<link href="pool.css" rel="stylesheet" type="text/css">
<H1 ALIGN=CENTER>Boost Pool Interfaces</H1>
<title>Boost Pool Interfaces</title>
</head>
<P>
<H2>Introduction</H2>
<body>
<img src="../../../boost.png" width="276" height="86" alt="C++ Boost">
<P>
There 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.
<h1 align="center">Boost Pool Interfaces</h1>
<P>
<H2>Terminology and Tradeoffs</H2>
<h2>Introduction</h2>
<P>
<H3>Object Usage vs. Singleton Usage</H3>
<p>There 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.</p>
<P>
<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.
<h2>Terminology and Tradeoffs</h2>
<P>
<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>.
<h3>Object Usage vs. Singleton Usage</h3>
<P>
<H3>Out-of-Memory Conditions: Exceptions vs. Null Return</H3>
<p><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.</p>
<P>
Some 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.
<p><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>.</p>
<P>
<H2>The Interfaces</H2>
<h3>Out-of-Memory Conditions: Exceptions vs. Null Return</h3>
<P>
<H3>pool</H3>
<p>Some 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.</p>
<P>
The <A HREF="interfaces/pool.html">pool interface</A> is a simple Object Usage interface with Null Return.
<h2>The Interfaces</h2>
<P>
Example:
<PRE CLASS="code">void func()
<h3>pool</h3>
<p>The <a href="interfaces/pool.html">pool interface</a> is a simple Object
Usage interface with Null Return.</p>
<p>Example:</p>
<pre class="code">
void func()
{
boost::pool&lt;&gt; p(sizeof(int));
for (int i = 0; i < 10000; ++i)
for (int i = 0; i &lt; 10000; ++i)
{
int * const t = p.malloc();
... // Do something with t; don't take the time to free() it
}
} // on function exit, p is destroyed, and all malloc()'ed ints are implicitly freed</PRE>
} // on function exit, p is destroyed, and all malloc()'ed ints are implicitly freed
</pre>
<P>
<H3>object_pool</H3>
<h3>object_pool</h3>
<P>
The <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.
<p>The <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.</p>
<P>
Example:
<PRE CLASS="code">struct X { ... }; // has destructor with side-effects
<p>Example:</p>
<pre class="code">
struct X { ... }; // has destructor with side-effects
void func()
{
boost::object_pool&lt;X&gt; p;
for (int i = 0; i < 10000; ++i)
for (int i = 0; i &lt; 10000; ++i)
{
X * const t = p.malloc();
... // Do something with t; don't take the time to free() it
}
} // on function exit, p is destroyed, and all destructors for the X objects are called</PRE>
} // on function exit, p is destroyed, and all destructors for the X objects are called
</pre>
<P>
<H3>singleton_pool</H3>
<h3>singleton_pool</h3>
<P>
The <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.
<p>The <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.</p>
<P>
Example:
<PRE CLASS="code">struct MyPoolTag { };
<p>Example:</p>
<pre class="code">
struct MyPoolTag { };
typedef boost::singleton_pool&lt;MyPoolTag, sizeof(int)&gt; my_pool;
void func()
{
for (int i = 0; i < 10000; ++i)
for (int i = 0; i &lt; 10000; ++i)
{
int * const t = my_pool::malloc();
... // Do something with t; don't take the time to free() it
}
// Explicitly free all malloc()'ed int's
my_pool::purge_memory();
}</PRE>
}
</pre>
<P>
<H3>pool_alloc</H3>
<h3>pool_alloc</h3>
<P>
The <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.).
<p>The <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.).</p>
<P>
Example:
<PRE CLASS="code">void func()
<p>Example:</p>
<pre class="code">
void func()
{
std::vector&lt;int, boost::pool_allocator&lt;int&gt; &gt; v;
for (int i = 0; i < 10000; ++i)
for (int i = 0; i &lt; 10000; ++i)
v.push_back(13);
} // Exiting the function does NOT free the system memory allocated by the pool allocator
// You must call
// boost::singleton_pool&lt;boost::pool_allocator_tag, sizeof(int)&gt;::release_memory()
// in order to force that</PRE>
// in order to force that
</pre>
<P>
<H2>Future Directions</H2>
<h2>Future Directions</h2>
<P>
Another 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.
<p>Another 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.</p>
<hr>
<P>
<HR>
<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
"http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01 Transitional"
height="31" width="88"></a></p>
<P>
Copyright &copy; 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)
<p>Revised
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05 December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38516" --></p>
<P>
This file can be redistributed and/or modified under the terms found in <A HREF="copyright.html">copyright.html</A>
<p><i>Copyright &copy; 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)</i></p>
<P>
This 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.
</BODY>
</HTML>
<p><i>Distributed under the Boost Software License, Version 1.0. (See
accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
copy at <a href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
</body>
</html>