Update of /cvsroot/boost/boost/libs/pool/doc
In directory sc8-pr-cvs3.sourceforge.net:/tmp/cvs-serv1962/libs/pool/doc
Modified Files:
concepts.html index.html interfaces.html pool.css
Log Message:
Fixed license & copyright issues and converted to HTML 4.01
Index: concepts.html
===================================================================
RCS file: /cvsroot/boost/boost/libs/pool/doc/concepts.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- concepts.html 5 Oct 2004 15:45:42 -0000 1.4
+++ concepts.html 5 Dec 2006 12:01:29 -0000 1.5
@@ -1,176 +1,407 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
-<HTML>
-<HEAD>
-<TITLE>Pool Concepts</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>Pool Concepts</H1>
+ <title>Pool Concepts</title>
+</head>
-<P>
-<BLOCKQUOTE>
-"Dynamic memory allocation has been a fundamental part of most computer
systems since roughly 1960..."<SUP><A HREF="#ref1">1</A></SUP>
-</BLOCKQUOTE>
+<body>
+ <img src="../../../boost.png" width="276" height="86" alt="C++ Boost">
-<p>
-Everyone uses dynamic memory allocation. If you have ever called <SPAN
CLASS="code">malloc</SPAN> or <SPAN CLASS="code">new</SPAN>, then you have used
dynamic memory allocation. Most programmers have a tendency to treat the heap
as a "magic bag": we ask it for memory, and it magically creates some
for us. Sometimes we run into problems because the heap is <EM>not</EM> magic.
+ <h1 align="center">Pool Concepts</h1>
-<p>
-The heap is limited. Even on large systems (i.e., not embedded) with huge
amounts of virtual memory available, there is a limit. Everyone is aware of
the physical limit, but there is a more subtle, "virtual" limit, that
limit at which your program (or the entire system) slows down due to the use of
virtual memory. This virtual limit is much closer to your program than the
physical limit, especially if you are running on a multitasking system.
Therefore, when running on a large system, it is considered "nice" to
make your program use as few resources as necessary, and release them as soon
as possible. When using an embedded system, programmers usually have no memory
to waste.
+ <blockquote>
+ "Dynamic memory allocation has been a fundamental part of most computer
+ systems since roughly 1960..."<sup><a href="#ref1">1</a></sup>
+ </blockquote>
-<P>
-The heap is complicated. It has to satisfy any type of memory request, for
any size, and do it <EM>fast</EM>. The common approaches to memory management
have to do with splitting the memory up into portions, and keeping them ordered
by size in some sort of a tree or list structure. Add in other factors, such
as locality and estimating lifetime, and heaps quickly become very complicated.
So complicated, in fact, that there is no known "perfect" answer to
the problem of how to do dynamic memory allocation. The diagrams below
illustrate how most common memory managers work: for each chunk of memory, it
uses part of that memory to maintain its internal tree or list structure. Even
when a chunk is <SPAN CLASS="code">malloc</SPAN>'ed out to a program, the
memory manager must "save" some information in it — usually
just its size. Then, when the block is <SPAN CLASS="code">free</SPAN>'d, the
memory manager can easily tell how large it is.
+ <p>Everyone uses dynamic memory allocation. If you have ever called
+ <span class="code">malloc</span> or <span class="code">new</span>, then you
+ have used dynamic memory allocation. Most programmers have a tendency to
+ treat the heap as a "magic bag": we ask it for memory, and it magically
+ creates some for us. Sometimes we run into problems because the heap is
+ <em>not</em> magic.</p>
-<TABLE CELLSPACING="0" BORDER="3" RULES="none" STYLE="float: left; clear:
both;">
-<CAPTION><EM>Memory block, not allocated</EM></CAPTION>
-<TR><TD STYLE="background-color: red; text-align: center;">Memory not
belonging to process</TD></TR>
-<TR><TD STYLE="padding: 1em 0em; background-color: silver; text-align:
center;">Memory used internally by memory allocator algorithm (usually 8-12
bytes)</TD></TR>
-<TR><TD STYLE="padding: 2em 0em; background-color: gray; text-align:
center">Unused memory</TD></TR>
-<TR><TD STYLE="background-color: red; text-align: center;">Memory not
belonging to process</TD></TR>
-</TABLE>
+ <p>The heap is limited. Even on large systems (i.e., not embedded) with
+ huge amounts of virtual memory available, there is a limit. Everyone is
+ aware of the physical limit, but there is a more subtle, "virtual" limit,
+ that limit at which your program (or the entire system) slows down due to
+ the use of virtual memory. This virtual limit is much closer to your
+ program than the physical limit, especially if you are running on a
+ multitasking system. Therefore, when running on a large system, it is
+ considered "nice" to make your program use as few resources as necessary,
+ and release them as soon as possible. When using an embedded system,
+ programmers usually have no memory to waste.</p>
-<TABLE CELLSPACING="0" BORDER="3" RULES="none" STYLE="float: right; clear:
both;">
-<CAPTION><EM>Memory block, allocated (used by program)</EM></CAPTION>
-<TR><TD STYLE="background-color: red; text-align: center;">Memory not
belonging to process</TD></TR>
-<TR><TD STYLE="background-color: silver; text-align: center;">Memory used
internally by memory allocator algorithm (usually 4 bytes)</TD></TR>
-<TR><TD STYLE="padding: 3em 0em; background-color: yellow; text-align:
center">Memory usable by program</TD></TR>
-<TR><TD STYLE="background-color: red; text-align: center;">Memory not
belonging to process</TD></TR>
-</TABLE>
+ <p>The heap is complicated. It has to satisfy any type of memory request,
+ for any size, and do it <em>fast</em>. The common approaches to memory
+ management have to do with splitting the memory up into portions, and
+ keeping them ordered by size in some sort of a tree or list structure. Add
+ in other factors, such as locality and estimating lifetime, and heaps
+ quickly become very complicated. So complicated, in fact, that there is no
+ known "perfect" answer to the problem of how to do dynamic memory
+ allocation. The diagrams below illustrate how most common memory managers
+ work: for each chunk of memory, it uses part of that memory to maintain its
+ internal tree or list structure. Even when a chunk is <span class=
+ "code">malloc</span>'ed out to a program, the memory manager must "save"
+ some information in it — usually just its size. Then, when the block
+ is <span class="code">free</span>'d, the memory manager can easily tell how
+ large it is.</p>
-<P>
-Because of the complication of dynamic memory allocation, it is often
inefficient in terms of time and/or space. Most memory allocation algorithms
store some form of information with each memory block, either the block size or
some relational information, such as its position in the internal tree or list
structure. It is common for such "header fields" to take up one
machine word in a block that is being used by the program. The obvious
problem, then, is when small objects are dynamically allocated. For example,
if <SPAN CLASS="code">int</SPAN>s were dynamically allocated, then
automatically the algorithm will reserve space for the header fields as well,
and we end up with a 50% waste of memory. Of course, this is a worst-case
scenario. However, more modern programs are making use of small objects on the
heap; and that is making this problem more and more apparent. Wilson <EM>et.
al.</EM> state that an average-case memory overhead is about ten to twenty perc
ent<SUP><A HREF="#ref2">2</A></SUP>. This memory overhead will grow higher as
more programs use more smaller objects. It is this memory overhead that brings
programs closer to the virtual limit.
+ <table cellspacing="0" border="3" rules="none" style=
+ "float: left; clear: both;" summary="">
+ <caption>
+ <em>Memory block, not allocated</em>
+ </caption>
-<P>
-In larger systems, the memory overhead is not as big of a problem (compared to
the amount of time it would take to work around it), and thus is often ignored.
However, there are situations where many allocations and/or deallocations of
smaller objects are taking place as part of a time-critical algorithm, and in
these situations, the system-supplied memory allocator is often too slow.
+ <tr>
+ <td style="background-color: red; text-align: center;">Memory not
+ belonging to process</td>
+ </tr>
-<P>
-Simple segregated storage addresses both of these issues. Almost all memory
overhead is done away with, and all allocations can take place in a small
amount of (amortized) constant time. However, this is done at the loss of
generality; simple segregated storage only can allocate memory chunks of a
single size.
+ <tr>
+ <td style=
+ "padding: 1em 0em; background-color: silver; text-align: center;">
+ Memory used internally by memory allocator algorithm (usually 8-12
+ bytes)</td>
+ </tr>
-<P>
-<HR>
+ <tr>
+ <td style=
+ "padding: 2em 0em; background-color: gray; text-align: center">Unused
+ memory</td>
+ </tr>
-<P>
-<H1 ALIGN=CENTER>Simple Segregated Storage</H1>
+ <tr>
+ <td style="background-color: red; text-align: center;">Memory not
+ belonging to process</td>
+ </tr>
+ </table>
-<P>
-Simple Segregated Storage is the basic idea behind the Boost Pool library.
Simple Segregated Storage is the simplest, and probably the fastest, memory
allocation/deallocation algorithm. It begins by <EM>partitioning</EM> a memory
<EM>block</EM> into fixed-size <EM>chunks</EM>. Where the block comes from is
not important until implementation time. A <EM>Pool</EM> is some object that
uses Simple Segregated Storage in this fashion. To illustrate:
+ <table cellspacing="0" border="3" rules="none" style=
+ "float: right; clear: both;" summary="">
+ <caption>
+ <em>Memory block, allocated (used by program)</em>
+ </caption>
-<TABLE CELLSPACING="0" BORDER="3" RULES="none" ALIGN=CENTER STYLE="clear:
both;">
-<CAPTION><EM>Memory block, split into chunks</EM></CAPTION>
-<TR><TD STYLE="background-color: red; text-align: center;">Memory not
belonging to process</TD></TR>
-<TR><TD STYLE="padding: 1em 0em; background-color: gray; text-align:
center;">Chunk 0</TD></TR>
-<TR><TD STYLE="padding: 1em 0em; background-color: gray; text-align:
center;">Chunk 1</TD></TR>
-<TR><TD STYLE="padding: 1em 0em; background-color: gray; text-align:
center;">Chunk 2</TD></TR>
-<TR><TD STYLE="padding: 1em 0em; background-color: gray; text-align:
center;">Chunk 3</TD></TR>
-<TR><TD STYLE="background-color: red; text-align: center;">Memory not
belonging to process</TD></TR>
-</TABLE>
+ <tr>
+ <td style="background-color: red; text-align: center;">Memory not
+ belonging to process</td>
+ </tr>
-<P>
-Each of the chunks in any given block are <STRONG>always</STRONG> the same
size. This is the fundamental restriction of Simple Segregated Storage: you
cannot ask for chunks of different sizes. For example, you cannot ask a Pool
of integers for a character, or a Pool of characters for an integer (assuming
that characters and integers are different sizes).
+ <tr>
+ <td style="background-color: silver; text-align: center;">Memory used
+ internally by memory allocator algorithm (usually 4 bytes)</td>
+ </tr>
-<P>
-Simple Segregated Storage works by interleaving a <EM>free list</EM> within
the unused chunks. For example:
+ <tr>
+ <td style=
+ "padding: 3em 0em; background-color: yellow; text-align: center">Memory
+ usable by program</td>
+ </tr>
-<TABLE CELLSPACING="0" BORDER="3" RULES="none" STYLE="float: left; clear:
both;">
-<CAPTION><EM>Memory block, with no chunks allocated</EM></CAPTION>
-<TR><TD STYLE="background-color: red; text-align: center;">Memory not
belonging to process</TD></TR>
-<TR><TD STYLE="padding: 1em 0em; background-color: gray; text-align:
center;">Chunk 0; points to Chunk 1</TD></TR>
-<TR><TD STYLE="padding: 1em 0em; background-color: gray; text-align:
center;">Chunk 1; points to Chunk 2</TD></TR>
-<TR><TD STYLE="padding: 1em 0em; background-color: gray; text-align:
center;">Chunk 2; points to Chunk 3</TD></TR>
-<TR><TD STYLE="padding: 1em 0em; background-color: gray; text-align:
center;">Chunk 3; end-of-list</TD></TR>
-<TR><TD STYLE="background-color: red; text-align: center;">Memory not
belonging to process</TD></TR>
-</TABLE>
+ <tr>
+ <td style="background-color: red; text-align: center;">Memory not
+ belonging to process</td>
+ </tr>
+ </table>
-<TABLE CELLSPACING="0" BORDER="3" RULES="none" STYLE="float: right; clear:
both;">
-<CAPTION><EM>Memory block, with two chunks allocated</EM></CAPTION>
-<TR><TD STYLE="background-color: red; text-align: center;">Memory not
belonging to process</TD></TR>
-<TR><TD STYLE="padding: 1em 0em; background-color: gray; text-align:
center;">Chunk 0; points to Chunk 2</TD></TR>
-<TR><TD STYLE="padding: 1em 0em; background-color: silver; text-align:
center;">Chunk 1 (in use by process)</TD></TR>
-<TR><TD STYLE="padding: 1em 0em; background-color: gray; text-align:
center;">Chunk 2; end-of-list</TD></TR>
-<TR><TD STYLE="padding: 1em 0em; background-color: silver; text-align:
center;">Chunk 3 (in use by process)</TD></TR>
-<TR><TD STYLE="background-color: red; text-align: center;">Memory not
belonging to process</TD></TR>
-</TABLE>
+ <p>Because of the complication of dynamic memory allocation, it is often
+ inefficient in terms of time and/or space. Most memory allocation
+ algorithms store some form of information with each memory block, either
+ the block size or some relational information, such as its position in the
+ internal tree or list structure. It is common for such "header fields" to
+ take up one machine word in a block that is being used by the program. The
+ obvious problem, then, is when small objects are dynamically allocated. For
+ example, if <span class="code">int</span>s were dynamically allocated, then
+ automatically the algorithm will reserve space for the header fields as
+ well, and we end up with a 50% waste of memory. Of course, this is a
+ worst-case scenario. However, more modern programs are making use of small
+ objects on the heap; and that is making this problem more and more
+ apparent. Wilson <em>et. al.</em> state that an average-case memory
+ overhead is about ten to twenty percent<sup><a href="#ref2">2</a></sup>.
+ This memory overhead will grow higher as more programs use more smaller
+ objects. It is this memory overhead that brings programs closer to the
+ virtual limit.</p>
-<P>
-By interleaving the free list inside the chunks, each Simple Segregated
Storage only has the overhead of a single pointer (the pointer to the first
element in the list). It has <EM>no</EM> memory overhead for chunks that are
in use by the process.
+ <p>In larger systems, the memory overhead is not as big of a problem
+ (compared to the amount of time it would take to work around it), and thus
+ is often ignored. However, there are situations where many allocations
+ and/or deallocations of smaller objects are taking place as part of a
+ time-critical algorithm, and in these situations, the system-supplied
+ memory allocator is often too slow.</p>
-<P>
-Simple Segregated Storage is also extremely fast. In the simplest case,
memory allocation is merely removing the first chunk from the free list, a O(1)
operation. In the case where the free list is empty, another block may have to
be acquired and partitioned, which would result in an amortized O(1) time.
Memory deallocation may be as simple as adding that chunk to the front of the
free list, a O(1) operation. However, more complicated uses of Simple
Segregated Storage may require a sorted free list, which makes deallocation
O(N).
+ <p>Simple segregated storage addresses both of these issues. Almost all
+ memory overhead is done away with, and all allocations can take place in a
+ small amount of (amortized) constant time. However, this is done at the
+ loss of generality; simple segregated storage only can allocate memory
+ chunks of a single size.</p>
+ <hr>
-<P>
-Simple Segregated Storage gives faster execution and less memory overhead than
a system-supplied allocator, but at the loss of generality. A good place to
use a Pool is in situations where many (noncontiguous) small objects may be
allocated on the heap, or if allocation and deallocation of the same-sized
objects happens repeatedly.
+ <h1 align="center">Simple Segregated Storage</h1>
-<P>
-<HR>
+ <p>Simple Segregated Storage is the basic idea behind the Boost Pool
+ library. Simple Segregated Storage is the simplest, and probably the
+ fastest, memory allocation/deallocation algorithm. It begins by
+ <em>partitioning</em> a memory <em>block</em> into fixed-size
+ <em>chunks</em>. Where the block comes from is not important until
+ implementation time. A <em>Pool</em> is some object that uses Simple
+ Segregated Storage in this fashion. To illustrate:</p>
-<P>
-<H2>References</H2>
+ <table cellspacing="0" border="3" rules="none" align="center" style=
+ "clear: both;" summary="">
+ <caption>
+ <em>Memory block, split into chunks</em>
+ </caption>
-<P>
-<OL>
-<LI><A NAME="ref1">Doug Lea, <EM>A Memory Allocator</EM>.</A> Available on
the web at <A
HREF="http://gee.cs.oswego.edu/dl/html/malloc.html";>http://gee.cs.oswego.edu/dl/html/malloc.html</A></LI>
-<LI><A NAME="ref2">Paul R. Wilson, Mark S. Johnstone, Michael Neely, and David
Boles, "Dynamic Storage Allocation: A Survey and Critical Review" in
<EM>International Workshop on Memory Management</EM>, September 1995, pg. 28,
36.</A> Available on the web at <A
HREF="ftp://ftp.cs.utexas.edu/pub/garbage/allocsrv.ps";>ftp://ftp.cs.utexas.edu/pub/garbage/allocsrv.ps</A></LI>
-</OL>
+ <tr>
+ <td style="background-color: red; text-align: center;">Memory not
+ belonging to process</td>
+ </tr>
-<P>
-<H2>Other Implementations</H2>
+ <tr>
+ <td style=
+ "padding: 1em 0em; background-color: gray; text-align: center;">Chunk
+ 0</td>
+ </tr>
-<P>
-Pool allocators are found in many programming languages, and in many
variations. The beginnings of many implementations may be found in common
programming literature; some of these are given below. Note that none of these
are complete implementations of a Pool; most of these leave some aspects of a
Pool as a user exercise. However, in each case, even though some aspects are
missing, these examples use the same underlying concept of a Simple Segregated
Storage described in this document.
+ <tr>
+ <td style=
+ "padding: 1em 0em; background-color: gray; text-align: center;">Chunk
+ 1</td>
+ </tr>
-<P>
-<UL>
+ <tr>
+ <td style=
+ "padding: 1em 0em; background-color: gray; text-align: center;">Chunk
+ 2</td>
+ </tr>
-<LI>
-"The C++ Programming Language", 3rd ed., by Bjarne Stroustrup,
Section 19.4.2. Missing aspects:
- <OL>
- <LI>Not portable</LI>
- <LI>Cannot handle allocations of arbitrary numbers of objects (this was left
as an exercise)</LI>
- <LI>Not thread-safe</LI>
- <LI>Suffers from the static initialization problem</LI>
- </OL>
-</LI>
+ <tr>
+ <td style=
+ "padding: 1em 0em; background-color: gray; text-align: center;">Chunk
+ 3</td>
+ </tr>
-<LI>
-"MicroC/OS-II: The Real-Time Kernel", by Jean J. Labrosse, Chapter 7
and Appendix B.04. This is an example of the Simple Segregated Storage scheme
at work in the internals of an actual OS. Missing aspects:
- <OL>
- <LI>Not portable (though this is OK, since it's part of its own OS)</LI>
- <LI>Cannot handle allocations of arbitrary numbers of blocks (which is also
OK, since this feature is not needed)</LI>
- <LI>Requires non-intuitive user code to create and destroy the Pool</LI>
- </OL>
-</LI>
+ <tr>
+ <td style="background-color: red; text-align: center;">Memory not
+ belonging to process</td>
+ </tr>
+ </table>
-<LI>
-"Efficient C++: Performance Programming Techniques", by Dov Bulka
and David Mayhew, Chapters 6 and 7. This is a good example of iteratively
developing a Pool solution; however, their premise (that the system-supplied
allocation mechanism is hopelessly inefficient) is flawed on every system I've
tested on. Run their timings on your system before you accept their
conclusions. Missing aspects:
- <OL>
- <LI>Requires non-intuitive user code to create and destroy the Pool</LI>
- </OL>
-</LI>
+ <p>Each of the chunks in any given block are <strong>always</strong> the
+ same size. This is the fundamental restriction of Simple Segregated
+ Storage: you cannot ask for chunks of different sizes. For example, you
+ cannot ask a Pool of integers for a character, or a Pool of characters for
+ an integer (assuming that characters and integers are different sizes).</p>
-<LI>
-"Advanced C++: Programming Styles and Idioms", by James O. Coplien,
Section 3.6. This has examples of both static and dynamic pooling. Missing
aspects:
- <OL>
- <LI>Not thread-safe</LI>
- <LI>The static pooling example is not portable</LI>
- </OL>
-</LI>
+ <p>Simple Segregated Storage works by interleaving a <em>free list</em>
+ within the unused chunks. For example:</p>
-</UL>
+ <table cellspacing="0" border="3" rules="none" style=
+ "float: left; clear: both;" summary="">
+ <caption>
+ <em>Memory block, with no chunks allocated</em>
+ </caption>
-<P>
-<HR>
+ <tr>
+ <td style="background-color: red; text-align: center;">Memory not
+ belonging to process</td>
+ </tr>
-<P>
-Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)
+ <tr>
+ <td style=
+ "padding: 1em 0em; background-color: gray; text-align: center;">Chunk
+ 0; points to Chunk 1</td>
+ </tr>
-<P>
-This file can be redistributed and/or modified under the terms found in <A
HREF="copyright.html">copyright.html</A>
+ <tr>
+ <td style=
+ "padding: 1em 0em; background-color: gray; text-align: center;">Chunk
+ 1; points to Chunk 2</td>
+ </tr>
-<P>
-This software and its documentation is provided "as is" without
express or implied warranty, and with no claim as to its suitability for any
purpose.
+ <tr>
+ <td style=
+ "padding: 1em 0em; background-color: gray; text-align: center;">Chunk
+ 2; points to Chunk 3</td>
+ </tr>
-</BODY>
-</HTML>
+ <tr>
+ <td style=
+ "padding: 1em 0em; background-color: gray; text-align: center;">Chunk
+ 3; end-of-list</td>
+ </tr>
+
+ <tr>
+ <td style="background-color: red; text-align: center;">Memory not
+ belonging to process</td>
+ </tr>
+ </table>
+
+ <table cellspacing="0" border="3" rules="none" style=
+ "float: right; clear: both;" summary="">
+ <caption>
+ <em>Memory block, with two chunks allocated</em>
+ </caption>
+
+ <tr>
+ <td style="background-color: red; text-align: center;">Memory not
+ belonging to process</td>
+ </tr>
+
+ <tr>
+ <td style=
+ "padding: 1em 0em; background-color: gray; text-align: center;">Chunk
+ 0; points to Chunk 2</td>
+ </tr>
+
+ <tr>
+ <td style=
+ "padding: 1em 0em; background-color: silver; text-align: center;">Chunk
+ 1 (in use by process)</td>
+ </tr>
+
+ <tr>
+ <td style=
+ "padding: 1em 0em; background-color: gray; text-align: center;">Chunk
+ 2; end-of-list</td>
+ </tr>
+
+ <tr>
+ <td style=
+ "padding: 1em 0em; background-color: silver; text-align: center;">Chunk
+ 3 (in use by process)</td>
+ </tr>
+
+ <tr>
+ <td style="background-color: red; text-align: center;">Memory not
+ belonging to process</td>
+ </tr>
+ </table>
+
+ <p>By interleaving the free list inside the chunks, each Simple Segregated
+ Storage only has the overhead of a single pointer (the pointer to the first
+ element in the list). It has <em>no</em> memory overhead for chunks that
+ are in use by the process.</p>
+
+ <p>Simple Segregated Storage is also extremely fast. In the simplest case,
+ memory allocation is merely removing the first chunk from the free list, a
+ O(1) operation. In the case where the free list is empty, another block may
+ have to be acquired and partitioned, which would result in an amortized
+ O(1) time. Memory deallocation may be as simple as adding that chunk to the
+ front of the free list, a O(1) operation. However, more complicated uses of
+ Simple Segregated Storage may require a sorted free list, which makes
+ deallocation O(N).</p>
+
+ <p>Simple Segregated Storage gives faster execution and less memory
+ overhead than a system-supplied allocator, but at the loss of generality. A
+ good place to use a Pool is in situations where many (noncontiguous) small
+ objects may be allocated on the heap, or if allocation and deallocation of
+ the same-sized objects happens repeatedly.<br clear="all"></p>
+ <hr>
+
+ <h2>References</h2>
+
+ <ol>
+ <li><a name="ref1" id="ref1">Doug Lea, <em>A Memory Allocator</em>.</a>
+ Available on the web at <a href=
+
"http://gee.cs.oswego.edu/dl/html/malloc.html";>http://gee.cs.oswego.edu/dl/html/malloc.html</a></li>
+
+ <li><a name="ref2" id="ref2">Paul R. Wilson, Mark S. Johnstone, Michael
+ Neely, and David Boles, "Dynamic Storage Allocation: A Survey and
+ Critical Review" in <em>International Workshop on Memory Management</em>,
+ September 1995, pg. 28, 36.</a> Available on the web at <a href=
+
"ftp://ftp.cs.utexas.edu/pub/garbage/allocsrv.ps";>ftp://ftp.cs.utexas.edu/pub/garbage/allocsrv.ps</a></li>
+ </ol>
+
+ <h2>Other Implementations</h2>
+
+ <p>Pool allocators are found in many programming languages, and in many
+ variations. The beginnings of many implementations may be found in common
+ programming literature; some of these are given below. Note that none of
+ these are complete implementations of a Pool; most of these leave some
+ aspects of a Pool as a user exercise. However, in each case, even though
+ some aspects are missing, these examples use the same underlying concept of
+ a Simple Segregated Storage described in this document.</p>
+
+ <ul>
+ <li>"The C++ Programming Language", 3rd ed., by Bjarne Stroustrup,
+ Section 19.4.2. Missing aspects:
+
+ <ol>
+ <li>Not portable</li>
+
+ <li>Cannot handle allocations of arbitrary numbers of objects (this
+ was left as an exercise)</li>
+
+ <li>Not thread-safe</li>
+
+ <li>Suffers from the static initialization problem</li>
+ </ol>
+ </li>
+
+ <li>"MicroC/OS-II: The Real-Time Kernel", by Jean J. Labrosse, Chapter 7
+ and Appendix B.04. This is an example of the Simple Segregated Storage
+ scheme at work in the internals of an actual OS. Missing aspects:
+
+ <ol>
+ <li>Not portable (though this is OK, since it's part of its own
+ OS)</li>
+
+ <li>Cannot handle allocations of arbitrary numbers of blocks (which
+ is also OK, since this feature is not needed)</li>
+
+ <li>Requires non-intuitive user code to create and destroy the
+ Pool</li>
+ </ol>
+ </li>
+
+ <li>"Efficient C++: Performance Programming Techniques", by Dov Bulka and
+ David Mayhew, Chapters 6 and 7. This is a good example of iteratively
+ developing a Pool solution; however, their premise (that the
+ system-supplied allocation mechanism is hopelessly inefficient) is flawed
+ on every system I've tested on. Run their timings on your system before
+ you accept their conclusions. Missing aspects:
+
+ <ol>
+ <li>Requires non-intuitive user code to create and destroy the
+ Pool</li>
+ </ol>
+ </li>
+
+ <li>"Advanced C++: Programming Styles and Idioms", by James O. Coplien,
+ Section 3.6. This has examples of both static and dynamic pooling.
+ Missing aspects:
+
+ <ol>
+ <li>Not thread-safe</li>
+
+ <li>The static pooling example is not portable</li>
+ </ol>
+ </li>
+ </ul>
+ <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>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><i>Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT
+ com)</i></p>
+
+ <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>
Index: index.html
===================================================================
RCS file: /cvsroot/boost/boost/libs/pool/doc/index.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- index.html 5 Oct 2004 15:45:42 -0000 1.5
+++ index.html 5 Dec 2006 12:01:29 -0000 1.6
@@ -1,154 +1,231 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
-<HTML>
-<HEAD>
-<TITLE>Boost Pool Library</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 Library</H1>
+ <title>Boost Pool Library</title>
+</head>
-<P>
-<H2>Introduction</H2>
+<body>
+ <img src="../../../boost.png" width="276" height="86" alt="C++ Boost">
-<P>
-<H3>What is Pool?</H3>
+ <h1 align="center">Boost Pool Library</h1>
-<P>
-Pool allocation is a memory allocation scheme that is very fast, but limited
in its usage. For more information on pool allocation (also called
"simple segregated storage"), see <A HREF="concepts.html">the
concepts document</A>.
+ <h2>Introduction</h2>
-<P>
-<H3>Why should I use Pool?</H3>
+ <h3>What is Pool?</h3>
-<P>
-Using Pools gives you more control over how memory is used in your program.
For example, you could have a situation where you want to allocate a bunch of
small objects at one point, and then reach a point in your program where none
of them are needed any more. Using pool interfaces, you can choose to run
their destructors or just drop them off into oblivion; the pool interface will
guarantee that there are no system memory leaks.
+ <p>Pool allocation is a memory allocation scheme that is very fast, but
+ limited in its usage. For more information on pool allocation (also called
+ "simple segregated storage"), see <a href="concepts.html">the
concepts
+ document</a>.</p>
-<P>
-<H3>When should I use Pool?</H3>
+ <h3>Why should I use Pool?</h3>
-<P>
-Pools are generally used when there is a lot of allocation and deallocation of
small objects. Another common usage is the situation above, where many objects
may be dropped out of memory.
+ <p>Using Pools gives you more control over how memory is used in your
+ program. For example, you could have a situation where you want to allocate
+ a bunch of small objects at one point, and then reach a point in your
+ program where none of them are needed any more. Using pool interfaces, you
+ can choose to run their destructors or just drop them off into oblivion; the
+ pool interface will guarantee that there are no system memory leaks.</p>
-<P>
-In general, use Pools when you need a more efficient way to do unusual memory
control.
+ <h3>When should I use Pool?</h3>
-<P>
-<H3>How do I use Pool?</H3>
+ <p>Pools are generally used when there is a lot of allocation and
+ deallocation of small objects. Another common usage is the situation above,
+ where many objects may be dropped out of memory.</p>
-<P>
-See the <A HREF="interfaces.html">pool interfaces document</A>, which covers
the different Pool interfaces supplied by this library.
+ <p>In general, use Pools when you need a more efficient way to do unusual
+ memory control.</p>
-<P>
-<H2>Library Structure and Dependencies</H2>
+ <h3>How do I use Pool?</h3>
-<P>
-Forward declarations of all the exposed symbols for this library are in the
header <SPAN CLASS="code"><boost/pool/poolfwd.hpp></SPAN>.
+ <p>See the <a href="interfaces.html">pool interfaces document</a>, which
+ covers the different Pool interfaces supplied by this library.</p>
-<P>
-The library may use macros, which will be prefixed with <SPAN
CLASS="code">BOOST_POOL_</SPAN>. The exception to this rule are the include
file guards, which (for file <EM>xxx</EM>.hpp) is <SPAN
CLASS="code">BOOST_<EM>xxx</EM>_HPP</SPAN>.
+ <h2>Library Structure and Dependencies</h2>
-<P>
-All exposed symbols defined by the library will be in namespace <SPAN
CLASS="code">boost</SPAN>. All symbols used only by the implementation will be
in namespace <SPAN CLASS="code">boost::details::pool</SPAN>.
+ <p>Forward declarations of all the exposed symbols for this library are in
+ the header <span class="code"><boost/pool/poolfwd.hpp></span>.</p>
-<P>
-Every header used only by the implementation is in the subdirectory <SPAN
CLASS="code">detail/</SPAN>.
+ <p>The library may use macros, which will be prefixed with <span class=
+ "code">BOOST_POOL_</span>. The exception to this rule are the include file
+ guards, which (for file <em>xxx</em>.hpp) is <span class=
+ "code">BOOST_<em>xxx</em>_HPP</span>.</p>
-<P>
-Any header in the library may include any other header in the library or any
system-supplied header at its discretion.
+ <p>All exposed symbols defined by the library will be in namespace
+ <span class="code">boost</span>. All symbols used only by the implementation
+ will be in namespace <span class=
+ "code">boost::details::pool</span>.</p>
-<P>
-<H2>Installation</H2>
+ <p>Every header used only by the implementation is in the subdirectory
+ <span class="code">detail/</span>.</p>
-<P>
-The Boost Pool library is a header file library. That means there is no .lib,
.dll, or .so to build; just add the Boost directory to your compiler's include
file path, and you should be good to go!
+ <p>Any header in the library may include any other header in the library or
+ any system-supplied header at its discretion.</p>
-<P>
-<H2>Building the Test Programs</H2>
+ <h2>Installation</h2>
-<P>
-The subdirectory "build" contains subdirectories for several
different platforms. These subdirectories contain all necessary work-around
code for that platform, as well as makefiles or IDE project files as
appropriate.
+ <p>The Boost Pool library is a header file library. That means there is no
+ .lib, .dll, or .so to build; just add the Boost directory to your compiler's
+ include file path, and you should be good to go!</p>
-<P>
-Read the "readme.txt" in the proper subdirectory, if it exists.
+ <h2>Building the Test Programs</h2>
-<P>
-The standard makefile targets are "all", "clean" (which
deletes any intermediate files), and "veryclean" (which deletes any
intermediate files and executables). All intermediate and executable files are
built in the same directory as the makefile/project file. If there is a
project file supplied instead of a makefile, "clean" and
"veryclean" shell scripts/batch files will be provided.
+ <p>The subdirectory "build" contains subdirectories for several
different
+ platforms. These subdirectories contain all necessary work-around code for
+ that platform, as well as makefiles or IDE project files as appropriate.</p>
-<P>
-Project files and makefiles for additional platforms may be sent to Stephen
Cleary at scleary AT jerviswebb DOT com.
+ <p>Read the "readme.txt" in the proper subdirectory, if it
exists.</p>
-<P>
-<H2>Documentation Map</H2>
+ <p>The standard makefile targets are "all", "clean"
(which deletes any
+ intermediate files), and "veryclean" (which deletes any
intermediate files
+ and executables). All intermediate and executable files are built in the
+ same directory as the makefile/project file. If there is a project file
+ supplied instead of a makefile, "clean" and "veryclean"
shell scripts/batch
+ files will be provided.</p>
-<UL>
-<LI>Overview of Pooling
- <UL>
- <LI><A HREF="concepts.html">concepts.html</A> - The basic ideas behind
pooling.</LI>
- <LI><A HREF="implementation/alignment.html">implementation/alignment.html</A>
- How we guarantee alignment portably.</LI>
- <LI><A HREF="interfaces.html">interfaces.html</A> - What interfaces are
provided and when to use each one.</LI>
- </UL>
-</LI>
-<LI>Pool Exposed Interfaces
- <UL>
- <LI><A
HREF="interfaces/simple_segregated_storage.html">interfaces/simple_segregated_storage.html</A>
- Not for the faint of heart; embedded programmers only.</LI>
- <LI><A HREF="interfaces/pool.html">interfaces/pool.html</A> - The basic pool
interface.</LI>
- <LI><A
HREF="interfaces/singleton_pool.html">interfaces/singleton_pool.html</A> - The
basic pool interface as a thread-safe singleton.</LI>
- <LI><A HREF="interfaces/object_pool.html">interfaces/object_pool.html</A> - A
type-oriented (instead of size-oriented) pool interface.</LI>
- <LI><A HREF="interfaces/pool_alloc.html">interfaces/pool_alloc.html</A> - A
Standard Allocator pool interface based on singleton_pool.</LI>
- <LI><A
HREF="interfaces/user_allocator.html">interfaces/user_allocator.html</A> - OK,
not a pool interface, but it describes how the user can control how Pools
allocate system memory.</LI>
- </UL>
-</LI>
-<LI>Pool Implementation Details and Extensions
- <UL>
- <LI>Interface Implementations and Extensions
- <UL>
- <LI><A
HREF="implementation/simple_segregated_storage.html">implementation/simple_segregated_storage.html</A></LI>
- <LI><A HREF="implementation/pool.html">implementation/pool.html</A></LI>
- <LI><A
HREF="implementation/singleton_pool.html">implementation/singleton_pool.html</A></LI>
- <LI><A
HREF="implementation/object_pool.html">implementation/object_pool.html</A></LI>
- <LI><A
HREF="implementation/pool_alloc.html">implementation/pool_alloc.html</A></LI>
- </UL>
- </LI>
- <LI>Components Used Only by the Implementation
- <UL>
- <LI><A
HREF="implementation/ct_gcd_lcm.html">implementation/ct_gcd_lcm.html</A> -
Compile-time GCD and LCM.</LI>
- <LI><A HREF="implementation/for.html">implementation/for.html</A> -
Description of an m4 component.</LI>
- <LI><A HREF="implementation/gcd_lcm.html">implementation/gcd_lcm.html</A> -
Run-time GCD and LCM.</LI>
- <LI><A HREF="implementation/guard.html">implementation/guard.html</A> - Auto
lock/unlock for mutex.</LI>
- <LI><A HREF="implementation/mutex.html">implementation/mutex.html</A> -
Platform-dependent mutex type.</LI>
- <LI><A
HREF="implementation/pool_construct.html">implementation/pool_construct.html</A>
- The system for supporting more constructor arguments in object_pool.</LI>
- <LI><A
HREF="implementation/singleton.html">implementation/singleton.html</A> -
Singleton that avoids static initialization problem.</LI>
- </UL>
- </LI>
- </UL>
-</LI>
-</UL>
+ <p>Project files and makefiles for additional platforms may be sent to
+ Stephen Cleary at scleary AT jerviswebb DOT com.</p>
-<P>
-<H2>Future Directions</H2>
+ <h2>Documentation Map</h2>
-<P>
-Another pool interface will be written: a base class for per-class pool
allocation.
+ <ul>
+ <li>Overview of Pooling
-<P>
-<H2>Acknowledgements</H2>
+ <ul>
+ <li><a href="concepts.html">concepts.html</a> - The basic ideas behind
+ pooling.</li>
-<P>
-Many, many thanks to the Boost peers, notably Jeff Garland, Beman Dawes, Ed
Brey, Gary Powell, Peter Dimov, and Jens Maurer for providing helpful
suggestions!
+ <li><a href=
+ "implementation/alignment.html">implementation/alignment.html</a> -
+ How we guarantee alignment portably.</li>
-<P>
-<HR>
+ <li><a href="interfaces.html">interfaces.html</a> - What interfaces
+ are provided and when to use each one.</li>
+ </ul>
+ </li>
-<P>
-Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)
+ <li>Pool Exposed Interfaces
-<P>
-This file can be redistributed and/or modified under the terms found in <A
HREF="copyright.html">copyright.html</A>
+ <ul>
+ <li><a href=
+ "interfaces/simple_segregated_storage.html">
+ interfaces/simple_segregated_storage.html</a>
+ - Not for the faint of heart; embedded programmers only.</li>
-<P>
-This software and its documentation is provided "as is" without
express or implied warranty, and with no claim as to its suitability for any
purpose.
+ <li><a href="interfaces/pool.html">interfaces/pool.html</a> - The
+ basic pool interface.</li>
-</BODY>
-</HTML>
\ No newline at end of file
+ <li><a href=
+ "interfaces/singleton_pool.html">interfaces/singleton_pool.html</a> -
+ The basic pool interface as a thread-safe singleton.</li>
+
+ <li><a href=
+ "interfaces/object_pool.html">interfaces/object_pool.html</a> - A
+ type-oriented (instead of size-oriented) pool interface.</li>
+
+ <li><a href=
+ "interfaces/pool_alloc.html">interfaces/pool_alloc.html</a> - A
+ Standard Allocator pool interface based on singleton_pool.</li>
+
+ <li><a href=
+ "interfaces/user_allocator.html">interfaces/user_allocator.html</a> -
+ OK, not a pool interface, but it describes how the user can control
+ how Pools allocate system memory.</li>
+ </ul>
+ </li>
+
+ <li>Pool Implementation Details and Extensions
+
+ <ul>
+ <li>Interface Implementations and Extensions
+
+ <ul>
+ <li><a href=
+ "implementation/simple_segregated_storage.html">
+ implementation/simple_segregated_storage.html</a></li>
+
+ <li><a href=
+ "implementation/pool.html">implementation/pool.html</a></li>
+
+ <li><a href=
+ "implementation/singleton_pool.html">
+ implementation/singleton_pool.html</a></li>
+
+ <li><a href=
+
"implementation/object_pool.html">implementation/object_pool.html</a></li>
+
+ <li><a href=
+
"implementation/pool_alloc.html">implementation/pool_alloc.html</a></li>
+ </ul>
+ </li>
+
+ <li>Components Used Only by the Implementation
+
+ <ul>
+ <li><a href=
+ "implementation/ct_gcd_lcm.html">implementation/ct_gcd_lcm.html</a>
+ - Compile-time GCD and LCM.</li>
+
+ <li><a href="implementation/for.html">implementation/for.html</a>
+ - Description of an m4 component.</li>
+
+ <li><a href=
+ "implementation/gcd_lcm.html">implementation/gcd_lcm.html</a> -
+ Run-time GCD and LCM.</li>
+
+ <li><a href=
+ "implementation/guard.html">implementation/guard.html</a> - Auto
+ lock/unlock for mutex.</li>
+
+ <li><a href=
+ "implementation/mutex.html">implementation/mutex.html</a> -
+ Platform-dependent mutex type.</li>
+
+ <li><a href=
+ "implementation/pool_construct.html">
+ implementation/pool_construct.html</a>
+ - The system for supporting more constructor arguments in
+ object_pool.</li>
+
+ <li><a href=
+ "implementation/singleton.html">implementation/singleton.html</a>
+ - Singleton that avoids static initialization problem.</li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ </ul>
+
+ <h2>Future Directions</h2>
+
+ <p>Another pool interface will be written: a base class for per-class pool
+ allocation.</p>
+
+ <h2>Acknowledgements</h2>
+
+ <p>Many, many thanks to the Boost peers, notably Jeff Garland, Beman Dawes,
+ Ed Brey, Gary Powell, Peter Dimov, and Jens Maurer for providing helpful
+ suggestions!</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>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><i>Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT
com)</i></p>
+
+ <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>
Index: interfaces.html
===================================================================
RCS file: /cvsroot/boost/boost/libs/pool/doc/interfaces.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- interfaces.html 5 Oct 2004 15:45:42 -0000 1.3
+++ interfaces.html 5 Dec 2006 12:01:29 -0000 1.4
@@ -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<> p(sizeof(int));
- for (int i = 0; i < 10000; ++i)
+ for (int i = 0; i < 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<X> p;
- for (int i = 0; i < 10000; ++i)
+ for (int i = 0; i < 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<MyPoolTag, sizeof(int)> my_pool;
void func()
{
- for (int i = 0; i < 10000; ++i)
+ for (int i = 0; i < 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<int, boost::pool_allocator<int> > v;
- for (int i = 0; i < 10000; ++i)
+ for (int i = 0; i < 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<boost::pool_allocator_tag,
sizeof(int)>::release_memory()
- // in order to force that</PRE>
-
-<P>
-<H2>Future Directions</H2>
+ // in order to force that
+</pre>
-<P>
-Another pool interface will be written: a base class for per-class pool
allocation. This "pool_base" interface will be Singleton Usage with
Exceptions, and built on the singleton_pool interface.
+ <h2>Future Directions</h2>
-<P>
-<HR>
+ <p>Another pool interface will be written: a base class for per-class pool
+ allocation. This "pool_base" interface will be Singleton Usage
with
+ Exceptions, and built on the singleton_pool interface.</p>
+ <hr>
-<P>
-Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)
+ <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>
-This file can be redistributed and/or modified under the terms found in <A
HREF="copyright.html">copyright.html</A>
+ <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 software and its documentation is provided "as is" without
express or implied warranty, and with no claim as to its suitability for any
purpose.
+ <p><i>Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT
com)</i></p>
-</BODY>
-</HTML>
\ No newline at end of file
+ <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>
Index: pool.css
===================================================================
RCS file: /cvsroot/boost/boost/libs/pool/doc/pool.css,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- pool.css 14 Sep 2003 01:00:34 -0000 1.2
+++ pool.css 5 Dec 2006 12:01:29 -0000 1.3
@@ -1,11 +1,9 @@
/*
Copyright (C) 2000 Stephen Cleary
- This file can be redistributed and/or modified under the terms found
- in "copyright.html"
- This software and its documentation is provided "as is" without express or
- implied warranty, and with no claim as to its suitability for any purpose.
+ Distributed under the Boost Software License, Version 1.0. (See accompany-
+ ing file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
*/
*.code { font-family: monospace; }
-*.m4 { white-space: pre; font-family: monospace; font-size: 75% }
+*.m4 { white-space: pre; font-family: monospace; font-size: 75% }
\ No newline at end of file
-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys - and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
_______________________________________________
Boost-cvs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/boost-cvs
