boost/pool
2
0
Fork 0
mirror of https://github.com/boostorg/pool.git synced 2026-02-25 16:42:23 +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

507
doc/concepts.html
View File

@@ -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>
&quot;Dynamic memory allocation has been a fundamental part of most computer systems since roughly 1960...&quot;<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 &quot;magic bag&quot;: 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, &quot;virtual&quot; 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 &quot;nice&quot; 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 &quot;perfect&quot; 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 &quot;save&quot; some information in it &mdash; 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 &mdash; 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 &quot;header fields&quot; 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.
<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, &quot;Dynamic Storage Allocation: A Survey and Critical Review&quot; 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>
&quot;The C++ Programming Language&quot;, 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>
&quot;MicroC/OS-II: The Real-Time Kernel&quot;, 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>
&quot;Efficient C++: Performance Programming Techniques&quot;, 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>
&quot;Advanced C++: Programming Styles and Idioms&quot;, 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 &copy; 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 &quot;as is&quot; 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 &copy; 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>

1154
doc/implementation/alignment.html
View File

File diff suppressed because it is too large Load Diff

180
doc/implementation/ct_gcd_lcm.html
View File

@@ -1,24 +1,28 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<TITLE>ct_gcd_lcm - Compile-Time GCD and LCM</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>ct_gcd_lcm - Compile-Time GCD and LCM</H1>
<title>ct_gcd_lcm - Compile-Time GCD and LCM</title>
</head>
<P>
<H2>Introduction</H2>
<body>
<img src="../../../../boost.png" width="276" height="86" alt="C++ Boost">
<P>
detail/ct_gcd_lcm.hpp provides two compile-time algorithms: greatest common divisor and least common multiple.
<h1 align="center">ct_gcd_lcm - Compile-Time GCD and LCM</h1>
<P>
<H2>Synopsis</H2>
<PRE CLASS="code">namespace details {
<h2>Introduction</h2>
<p>detail/ct_gcd_lcm.hpp provides two compile-time algorithms: greatest
common divisor and least common multiple.</p>
<h2>Synopsis</h2>
<pre class="code">
namespace details {
namespace pool {
template &lt;unsigned A, unsigned B&gt;
@@ -33,62 +37,120 @@ struct ct_lcm
};
} // namespace pool
} // namespace details</PRE>
} // namespace details
</pre>
<P>
<H2>Semantics</H2>
<h2>Semantics</h2>
<TABLE ALIGN=CENTER BORDER>
<CAPTION><EM>Symbol Table</EM></CAPTION>
<TR><TH>Symbol<TH>Meaning</TR>
<TR><TD CLASS="code">A, B<TD>compile-time unsigned integer constants<A HREF="#5.19/1"><SUP>[5.19/1]</SUP></A></TR>
</TABLE>
<table align="center" border summary="">
<caption>
<em>Symbol Table</em>
</caption>
<TABLE ALIGN=CENTER BORDER>
<CAPTION><EM>Semantics</EM></CAPTION>
<TR><TH>Expression<TH>Result Type<TH>Value<TH>Precondition
<TR><TD CLASS="code">ct_gcd&lt;A, B&gt;::value<TD>compile-time unsigned integer constant<TD>The greatest common divisor of <SPAN CLASS="code">A</SPAN> and <SPAN CLASS="code">B</SPAN><TD CLASS="code">A != 0 &amp;&amp; B != 0
<TR><TD CLASS="code">ct_lcm&lt;A, B&gt;::value<TD>compile-time unsigned integer constant<TD>The least common multiple of <SPAN CLASS="code">A</SPAN> and <SPAN CLASS="code">B</SPAN><TD CLASS="code">A != 0 &amp;&amp; B != 0
</TABLE>
<tr>
<th>Symbol</th>
<P>
<H2>Notes</H2>
<th>Meaning</th>
</tr>
<P>
Since these are compile-time algorithms, violation of the preconditions will result in a compile-time error.
<tr>
<td class="code">A, B</td>
<P>
<H2>Dependencies</H2>
<td>compile-time unsigned integer constants<a href=
"#s519p1"><sup>[5.19/1]</sup></a></td>
</tr>
</table><br>
<UL>
<LI>&lt;boost/static_assert.hpp&gt; (see <A HREF="../../../static_assert/static_assert.htm">Boost.Static_Assert</A>), to ensure preconditions are met.</LI>
<LI>&lt;boost/type_traits/ice.hpp&gt; (see <A HREF="../../../../more/int_const_guidelines.htm">Coding Guidelines for Integral Constant Expressions</A>), to help with portability.</LI>
</UL>
<table align="center" border summary="">
<caption>
<em>Semantics</em>
</caption>
<P>
<H2>Selected Quotations from the Standard</H2>
<tr>
<th>Expression</th>
<P>
<A NAME="5.19/1">
<STRONG>5.19/1: Expressions: Constant Expressions:</STRONG> &quot;. . . An <EM>integral constant expression</EM> can involve only literals (2.13), enumerators, <SPAN CLASS="code">const</SPAN> variables or static data members of integral or enumeration types initialized with constant expressions (8.5), non-type template parameters of integral or enumeration types, and <SPAN CLASS="code">sizeof</SPAN> expressions. Floating literals (2.13.3) can appear only if they are cast to integral or enumeration types. Only type conversions to integral or enumeration types can be used. In particular, except in <SPAN CLASS="code">sizeof</SPAN> expressions, functions, class objects, pointers, or references shall not be used, and assignment, increment, decrement, function-call, or comma operators shall not be used.&quot;</A>
<th>Result Type</th>
<P>
<H2>Future Directions</H2>
<th>Value</th>
<P>
This header may be replaced by a Boost compile-time algorithms library.
<th>Precondition</th>
</tr>
<P>
<HR>
<tr>
<td class="code">ct_gcd&lt;A, B&gt;::value</td>
<P>
Copyright &copy; 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)
<td>compile-time unsigned integer constant</td>
<P>
This file can be redistributed and/or modified under the terms found in <A HREF="../copyright.html">copyright.html</A>
<td>The greatest common divisor of <span class="code">A</span> and
<span class="code">B</span></td>
<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.
<td class="code">A != 0 &amp;&amp; B != 0</td>
</tr>
</BODY>
</HTML>
<tr>
<td class="code">ct_lcm&lt;A, B&gt;::value</td>
<td>compile-time unsigned integer constant</td>
<td>The least common multiple of <span class="code">A</span> and
<span class="code">B</span></td>
<td class="code">A != 0 &amp;&amp; B != 0</td>
</tr>
</table>
<h2>Notes</h2>
<p>Since these are compile-time algorithms, violation of the preconditions
will result in a compile-time error.</p>
<h2>Dependencies</h2>
<ul>
<li>&lt;boost/static_assert.hpp&gt; (see <a href=
"../../../static_assert/static_assert.htm">Boost.Static_Assert</a>), to
ensure preconditions are met.</li>
<li>&lt;boost/type_traits/ice.hpp&gt; (see <a href=
"../../../../more/int_const_guidelines.htm">Coding Guidelines for
Integral Constant Expressions</a>), to help with portability.</li>
</ul>
<h2>Selected Quotations from the Standard</h2>
<p><a name="s519p1" id="s519p1"></a><strong>5.19/1: Expressions: Constant
Expressions:</strong> ". . . An <em>integral constant expression</em> can
involve only literals (2.13), enumerators, <span class="code">const</span>
variables or static data members of integral or enumeration types
initialized with constant expressions (8.5), non-type template parameters
of integral or enumeration types, and <span class="code">sizeof</span>
expressions. Floating literals (2.13.3) can appear only if they are cast to
integral or enumeration types. Only type conversions to integral or
enumeration types can be used. In particular, except in <span class=
"code">sizeof</span> expressions, functions, class objects, pointers, or
references shall not be used, and assignment, increment, decrement,
function-call, or comma operators shall not be used."</p>
<h2>Future Directions</h2>
<p>This header may be replaced by a Boost compile-time algorithms
library.</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 &copy; 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>

220
doc/implementation/for.html
View File

@@ -1,75 +1,179 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<TITLE>for - m4 FOR Macro</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>for - m4 FOR Macro</H1>
<title>for - m4 FOR Macro</title>
</head>
<P>
<H2>Introduction</H2>
<body>
<img src="../../../../boost.png" width="276" height="86" alt="C++ Boost">
<P>
detail/for.m4 provides <SPAN CLASS="code">BOOST_M4_FOR</SPAN>, an <STRONG>m4</STRONG> macro that provides the equivalent of a <SPAN CLASS="code">#for</SPAN> preprocessor instruction.
<h1 align="center">for - m4 FOR Macro</h1>
<P>
<H2>Usage</H2>
<h2>Introduction</h2>
<P>
This macro must be used by an <STRONG>m4</STRONG> file. This file assumes that the option <SPAN CLASS="code">-P</SPAN> is used, to force an <SPAN CLASS="code">m4_</SPAN> prefix on all builtin symbols.
<p>detail/for.m4 provides <span class="code">BOOST_M4_FOR</span>, an
<strong>m4</strong> macro that provides the equivalent of a <span class=
"code">#for</span> preprocessor instruction.</p>
<P>
<H2>Arguments</H2>
<h2>Usage</h2>
<OL>
<LI>The name of a variable to hold the current value.</LI>
<LI>The starting value of the variable.</LI>
<LI>The ending value of the variable.</LI>
<LI>The text to repeat. This text may contain references to the variable, which will be replaced with the variable's current value.</LI>
<LI>The delimeter text (optional).</LI>
</OL>
<p>This macro must be used by an <strong>m4</strong> file. This file
assumes that the option <span class="code">-P</span> is used, to force an
<span class="code">m4_</span> prefix on all builtin symbols.</p>
<P>
If called with the wrong number of arguments (less than 4 or more than 5), <SPAN CLASS="code">BOOST_M4_FOR</SPAN> will exit with an error. If the starting value (<SPAN CLASS="code">$2</SPAN>) is greater than or equal to the ending value (<SPAN CLASS="code">$3</SPAN>), <SPAN CLASS="code">BOOST_M4_FOR</SPAN> will do nothing. Otherwise, it will repeat the text (<SPAN CLASS="code">$4</SPAN>), binding the variable (<SPAN CLASS="code">$1</SPAN>) to the values in the range [starting value (<SPAN CLASS="code">$2</SPAN>), ending value (<SPAN CLASS="code">$3</SPAN>)), and repeat the delimeter text (<SPAN CLASS="code">$5</SPAN>) in-between each occurrence of the repeat text (<SPAN CLASS="code">$4</SPAN>).
<h2>Arguments</h2>
<P>
<H2>Examples</H2>
<ol>
<li>The name of a variable to hold the current value.</li>
<P>
Note of the quotation marks (<SPAN CLASS="m4">&quot;</SPAN>) used in the table below are in the input or output; they are shown to delimit whitespace. All code within a pair of quotation marks is intended to be on one line.
<li>The starting value of the variable.</li>
<P>
<TABLE BORDER ALIGN="center">
<TR><TH>Input<TH>Output</TR>
<TR><TD CLASS="m4">&quot;BOOST_M4_FOR(i, 1, 3)&quot;<TD>Boost m4 script: BOOST_M4_FOR: Wrong number of arguments (3)</TR>
<TR><TD CLASS="m4">&quot;BOOST_M4_FOR(i, 1, 3, i, ` ', 13)&quot;<TD>Boost m4 script: BOOST_M4_FOR: Wrong number of arguments (6)</TR>
<TR><TD CLASS="m4">&quot;BOOST_M4_FOR(i, 7, 0, i )&quot;<TD>(nothing)</TR>
<TR><TD CLASS="m4">&quot;BOOST_M4_FOR(i, 0, 0, i )&quot;<TD>(nothing)</TR>
<TR><TD CLASS="m4">&quot;BOOST_M4_FOR(i, 0, 7, i )&quot;<TD CLASS="m4">&quot;0 1 2 3 4 5 6 &quot;</TR>
<TR><TD CLASS="m4">&quot;BOOST_M4_FOR(i, -13, -10, i )&quot;<TD CLASS="m4">&quot;-13 -12 -11 &quot;</TR>
<TR><TD CLASS="m4">&quot;BOOST_M4_FOR(i, 0, 8, BOOST_M4_FOR(j, 0, 4, (i, j) )&quot;<BR>&quot;)&quot;<TD CLASS="m4">&quot;(0, 0) (0, 1) (0, 2) (0, 3) &quot;<BR>&quot;(1, 0) (1, 1) (1, 2) (1, 3) &quot;<BR>&quot;(2, 0) (2, 1) (2, 2) (2, 3) &quot;<BR>&quot;(3, 0) (3, 1) (3, 2) (3, 3) &quot;<BR>&quot;(4, 0) (4, 1) (4, 2) (4, 3) &quot;<BR>&quot;(5, 0) (5, 1) (5, 2) (5, 3) &quot;<BR>&quot;(6, 0) (6, 1) (6, 2) (6, 3) &quot;<BR>&quot;(7, 0) (7, 1) (7, 2) (7, 3) &quot;<BR>&quot;&quot;</TR>
<TR><TD CLASS="m4">&quot;BOOST_M4_FOR(i, 7, 0, i, |)&quot;<TD>(nothing)</TR>
<TR><TD CLASS="m4">&quot;BOOST_M4_FOR(i, 0, 0, i, |)&quot;<TD>(nothing)</TR>
<TR><TD CLASS="m4">&quot;BOOST_M4_FOR(i, 0, 7, i, |)&quot;<TD CLASS="m4">&quot;0|1|2|3|4|5|6&quot;</TR>
<TR><TD CLASS="m4">&quot;BOOST_M4_FOR(i, -13, -10, i, `, ')&quot;<TD CLASS="m4">&quot;-13, -12, -11&quot;</TR>
<TR><TD CLASS="m4">&quot;BOOST_M4_FOR(i, 0, 8, `[BOOST_M4_FOR(j, 0, 4, (i, j), `, ')]', `,&quot;<BR>&quot;')&quot;<TD CLASS="m4">&quot;[(0, 0), (0, 1), (0, 2), (0, 3)],&quot;<BR>&quot;[(1, 0), (1, 1), (1, 2), (1, 3)],&quot;<BR>&quot;[(2, 0), (2, 1), (2, 2), (2, 3)],&quot;<BR>&quot;[(3, 0), (3, 1), (3, 2), (3, 3)],&quot;<BR>&quot;[(4, 0), (4, 1), (4, 2), (4, 3)],&quot;<BR>&quot;[(5, 0), (5, 1), (5, 2), (5, 3)],&quot;<BR>&quot;[(6, 0), (6, 1), (6, 2), (6, 3)],&quot;<BR>&quot;[(7, 0), (7, 1), (7, 2), (7, 3)]&quot;</TR>
</TABLE>
<li>The ending value of the variable.</li>
<P>
<HR>
<li>The text to repeat. This text may contain references to the variable,
which will be replaced with the variable's current value.</li>
<P>
Copyright &copy; 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)
<li>The delimeter text (optional).</li>
</ol>
<P>
This file can be redistributed and/or modified under the terms found in <A HREF="../copyright.html">copyright.html</A>
<p>If called with the wrong number of arguments (less than 4 or more than
5), <span class="code">BOOST_M4_FOR</span> will exit with an error. If the
starting value (<span class="code">$2</span>) is greater than or equal to
the ending value (<span class="code">$3</span>), <span class=
"code">BOOST_M4_FOR</span> will do nothing. Otherwise, it will repeat the
text (<span class="code">$4</span>), binding the variable (<span class=
"code">$1</span>) to the values in the range [starting value (<span class=
"code">$2</span>), ending value (<span class="code">$3</span>)), and repeat
the delimeter text (<span class="code">$5</span>) in-between each
occurrence of the repeat text (<span class="code">$4</span>).</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.
<h2>Examples</h2>
</BODY>
</HTML>
<p>Note of the quotation marks (<span class="m4">"</span>) used in the
table below are in the input or output; they are shown to delimit
whitespace. All code within a pair of quotation marks is intended to be on
one line.</p>
<table border align="center" summary="">
<tr>
<th>Input</th>
<th>Output</th>
</tr>
<tr>
<td class="m4">"BOOST_M4_FOR(i, 1, 3)"</td>
<td>Boost m4 script: BOOST_M4_FOR: Wrong number of arguments (3)</td>
</tr>
<tr>
<td class="m4">"BOOST_M4_FOR(i, 1, 3, i, ` ', 13)"</td>
<td>Boost m4 script: BOOST_M4_FOR: Wrong number of arguments (6)</td>
</tr>
<tr>
<td class="m4">"BOOST_M4_FOR(i, 7, 0, i )"</td>
<td>(nothing)</td>
</tr>
<tr>
<td class="m4">"BOOST_M4_FOR(i, 0, 0, i )"</td>
<td>(nothing)</td>
</tr>
<tr>
<td class="m4">"BOOST_M4_FOR(i, 0, 7, i )"</td>
<td class="m4">"0 1 2 3 4 5 6 "</td>
</tr>
<tr>
<td class="m4">"BOOST_M4_FOR(i, -13, -10, i )"</td>
<td class="m4">"-13 -12 -11 "</td>
</tr>
<tr>
<td class="m4">"BOOST_M4_FOR(i, 0, 8, BOOST_M4_FOR(j, 0, 4, (i, j)
)"<br>
")"</td>
<td class="m4">"(0, 0) (0, 1) (0, 2) (0, 3) "<br>
"(1, 0) (1, 1) (1, 2) (1, 3) "<br>
"(2, 0) (2, 1) (2, 2) (2, 3) "<br>
"(3, 0) (3, 1) (3, 2) (3, 3) "<br>
"(4, 0) (4, 1) (4, 2) (4, 3) "<br>
"(5, 0) (5, 1) (5, 2) (5, 3) "<br>
"(6, 0) (6, 1) (6, 2) (6, 3) "<br>
"(7, 0) (7, 1) (7, 2) (7, 3) "<br>
""</td>
</tr>
<tr>
<td class="m4">"BOOST_M4_FOR(i, 7, 0, i, |)"</td>
<td>(nothing)</td>
</tr>
<tr>
<td class="m4">"BOOST_M4_FOR(i, 0, 0, i, |)"</td>
<td>(nothing)</td>
</tr>
<tr>
<td class="m4">"BOOST_M4_FOR(i, 0, 7, i, |)"</td>
<td class="m4">"0|1|2|3|4|5|6"</td>
</tr>
<tr>
<td class="m4">"BOOST_M4_FOR(i, -13, -10, i, `, ')"</td>
<td class="m4">"-13, -12, -11"</td>
</tr>
<tr>
<td class="m4">"BOOST_M4_FOR(i, 0, 8, `[BOOST_M4_FOR(j, 0, 4, (i, j),
`, ')]', `,"<br>
"')"</td>
<td class="m4">"[(0, 0), (0, 1), (0, 2), (0, 3)],"<br>
"[(1, 0), (1, 1), (1, 2), (1, 3)],"<br>
"[(2, 0), (2, 1), (2, 2), (2, 3)],"<br>
"[(3, 0), (3, 1), (3, 2), (3, 3)],"<br>
"[(4, 0), (4, 1), (4, 2), (4, 3)],"<br>
"[(5, 0), (5, 1), (5, 2), (5, 3)],"<br>
"[(6, 0), (6, 1), (6, 2), (6, 3)],"<br>
"[(7, 0), (7, 1), (7, 2), (7, 3)]"</td>
</tr>
</table>
<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 &copy; 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>

156
doc/implementation/gcd_lcm.html
View File

@@ -1,24 +1,28 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<TITLE>gcd_lcm - GCD and LCM</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>gcd_lcm - GCD and LCM</H1>
<title>gcd_lcm - GCD and LCM</title>
</head>
<P>
<H2>Introduction</H2>
<body>
<img src="../../../../boost.png" width="276" height="86" alt="C++ Boost">
<P>
detail/gcd_lcm.hpp provides two generic integer algorithms: greatest common divisor and least common multiple.
<h1 align="center">gcd_lcm - GCD and LCM</h1>
<P>
<H2>Synopsis</H2>
<PRE CLASS="code">namespace details {
<h2>Introduction</h2>
<p>detail/gcd_lcm.hpp provides two generic integer algorithms: greatest
common divisor and least common multiple.</p>
<h2>Synopsis</h2>
<pre class="code">
namespace details {
namespace pool {
template &lt;typename Integer&gt;
@@ -28,54 +32,100 @@ template &lt;typename Integer&gt;
Integer lcm(Integer A, Integer B);
} // namespace pool
} // namespace details</PRE>
} // namespace details
</pre>
<P>
<H2>Semantics</H2>
<h2>Semantics</h2>
<TABLE ALIGN=CENTER BORDER>
<CAPTION><EM>Symbol Table</EM></CAPTION>
<TR><TH>Symbol<TH>Meaning</TR>
<TR><TD CLASS="code">Integer<TD>An integral type</TR>
<TR><TD CLASS="code">A, B<TD>Values of type <SPAN CLASS="code">Integer</SPAN></TR>
</TABLE>
<table align="center" border summary="">
<caption>
<em>Symbol Table</em>
</caption>
<TABLE ALIGN=CENTER BORDER>
<CAPTION><EM>Semantics</EM></CAPTION>
<TR><TH>Expression<TH>Result Type<TH>Precondition<TH>Notes
<TR><TD CLASS="code">gcd(A, B)<TD>Integer<TD CLASS="code">A &gt; 0 &amp;&amp; B &gt; 0<TD>Returns the greatest common divisor of <SPAN CLASS="code">A</SPAN> and <SPAN CLASS="code">B</SPAN>
<TR><TD CLASS="code">lcm(A, B)<TD>Integer<TD CLASS="code">A &gt; 0 &amp;&amp; B &gt; 0<TD>Returns the least common multiple of <SPAN CLASS="code">A</SPAN> and <SPAN CLASS="code">B</SPAN>
</TABLE>
<tr>
<th>Symbol</th>
<P>
<H2>Implementation Notes</H2>
<th>Meaning</th>
</tr>
<P>
For faster results, ensure <SPAN CLASS="code">A &gt; B</SPAN>
<tr>
<td class="code">Integer</td>
<P>
<H2>Dependencies</H2>
<td>An integral type</td>
</tr>
<P>
None.
<tr>
<td class="code">A, B</td>
<P>
<H2>Future Directions</H2>
<td>Values of type <span class="code">Integer</span></td>
</tr>
</table><br>
<P>
This header may be replaced by a Boost algorithms library.
<table align="center" border summary="">
<caption>
<em>Semantics</em>
</caption>
<P>
<HR>
<tr>
<th>Expression</th>
<P>
Copyright &copy; 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)
<th>Result Type</th>
<P>
This file can be redistributed and/or modified under the terms found in <A HREF="../copyright.html">copyright.html</A>
<th>Precondition</th>
<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.
<th>Notes</th>
</tr>
</BODY>
</HTML>
<tr>
<td class="code">gcd(A, B)</td>
<td>Integer</td>
<td class="code">A &gt; 0 &amp;&amp; B &gt; 0</td>
<td>Returns the greatest common divisor of <span class="code">A</span>
and <span class="code">B</span></td>
</tr>
<tr>
<td class="code">lcm(A, B)</td>
<td>Integer</td>
<td class="code">A &gt; 0 &amp;&amp; B &gt; 0</td>
<td>Returns the least common multiple of <span class="code">A</span>
and <span class="code">B</span></td>
</tr>
</table>
<h2>Implementation Notes</h2>
<p>For faster results, ensure <span class="code">A &gt; B</span></p>
<h2>Dependencies</h2>
<p>None.</p>
<h2>Future Directions</h2>
<p>This header may be replaced by a Boost algorithms library.</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 &copy; 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>

202
doc/implementation/guard.html
View File

@@ -1,25 +1,31 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<TITLE>guard - Auto-lock/unlock-er</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>guard - Auto-lock/unlock-er</H1>
<title>guard - Auto-lock/unlock-er</title>
</head>
<P>
<H2>Introduction</H2>
<body>
<img src="../../../../boost.png" width="276" height="86" alt="C++ Boost">
<P>
detail/guard.hpp provides a type <SPAN CLASS="code">guard&lt;Mutex&gt;</SPAN> that allows scoped access to the <SPAN CLASS="code">Mutex</SPAN>'s locking and unlocking operations. It is used to ensure that a <SPAN CLASS="code">Mutex</SPAN> is unlocked, even if an exception is thrown.
<h1 align="center">guard - Auto-lock/unlock-er</h1>
<P>
<H2>Synopsis</H2>
<h2>Introduction</h2>
<PRE CLASS="code">namespace details {
<p>detail/guard.hpp provides a type <span class=
"code">guard&lt;Mutex&gt;</span> that allows scoped access to the
<span class="code">Mutex</span>'s locking and unlocking operations. It is
used to ensure that a <span class="code">Mutex</span> is unlocked, even if
an exception is thrown.</p>
<h2>Synopsis</h2>
<pre class="code">
namespace details {
namespace pool {
template &lt;typename Mutex&gt;
@@ -35,77 +41,139 @@ class guard
};
} // namespace pool
} // namespace details</PRE>
} // namespace details
</pre>
<P>
<H2>Semantics</H2>
<h2>Semantics</h2>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Symbol Table</EM></CAPTION>
<TR><TH>Symbol<TH>Meaning
<TR><TD CLASS="code">T<TD><SPAN CLASS="code">guard&lt;Mutex&gt;</SPAN>
<TR><TD CLASS="code">m<TD>value of type <SPAN CLASS="code">Mutex &amp;</SPAN>
<TR><TD CLASS="code">g<TD>value of type <SPAN CLASS="code">guard&lt;Mutex&gt;</SPAN>
</TABLE>
<table border align="center" summary="">
<caption>
<em>Symbol Table</em>
</caption>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Requirements on <SPAN CLASS="code">Mutex</SPAN></EM></CAPTION>
<TR><TH>Expression<TH>Return Type<TH>Assertion/Note/Pre/Post-Condition
<TR><TD CLASS="code">m.lock()<TD>not used<TD>Locks the mutex referred to by <SPAN CLASS="code">m</SPAN>
<TR><TD CLASS="code">m.unlock()<TD>not used<TD>Unlocks the mutex referred to by <SPAN CLASS="code">m</SPAN>
</TABLE>
<tr>
<th>Symbol</th>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Requirements satisfied by <SPAN CLASS="code">guard</SPAN></EM></CAPTION>
<TR><TH>Expression<TH>Assertion/Note/Pre/Post-Condition
<TR><TD CLASS="code">T(m)<TD>Locks the mutex referred to by <SPAN CLASS="code">m</SPAN>; binds <SPAN CLASS="code">T(m)</SPAN> to <SPAN CLASS="code">m</SPAN>
<TR><TD CLASS="code">(&amp;g)->~T()<TD>Unlocks the mutex that <SPAN CLASS="code">g</SPAN> is bound to
</TABLE>
<th>Meaning</th>
</tr>
<P>
<H2>Example</H2>
<tr>
<td class="code">T</td>
<P>
Given a (platform-specific) <SPAN CLASS="code">mutex</SPAN> class, we can wrap code as follows:
<PRE CLASS="code">extern mutex global_lock;
<td><span class="code">guard&lt;Mutex&gt;</span></td>
</tr>
<tr>
<td class="code">m</td>
<td>value of type <span class="code">Mutex &amp;</span></td>
</tr>
<tr>
<td class="code">g</td>
<td>value of type <span class="code">guard&lt;Mutex&gt;</span></td>
</tr>
</table><br>
<table border align="center" summary="">
<caption>
<em>Requirements on <span class="code">Mutex</span></em>
</caption>
<tr>
<th>Expression</th>
<th>Return Type</th>
<th>Assertion/Note/Pre/Post-Condition</th>
</tr>
<tr>
<td class="code">m.lock()</td>
<td>not used</td>
<td>Locks the mutex referred to by <span class="code">m</span></td>
</tr>
<tr>
<td class="code">m.unlock()</td>
<td>not used</td>
<td>Unlocks the mutex referred to by <span class="code">m</span></td>
</tr>
</table><br>
<table border align="center" summary="">
<caption>
<em>Requirements satisfied by <span class="code">guard</span></em>
</caption>
<tr>
<th>Expression</th>
<th>Assertion/Note/Pre/Post-Condition</th>
</tr>
<tr>
<td class="code">T(m)</td>
<td>Locks the mutex referred to by <span class="code">m</span>; binds
<span class="code">T(m)</span> to <span class="code">m</span></td>
</tr>
<tr>
<td class="code">(&amp;g)-&gt;~T()</td>
<td>Unlocks the mutex that <span class="code">g</span> is bound to</td>
</tr>
</table>
<h2>Example</h2>
<p>Given a (platform-specific) <span class="code">mutex</span> class, we
can wrap code as follows:</p>
<pre class="code">
extern mutex global_lock;
static void f()
{
boost::details::pool::guard&lt;mutex&gt; g(global_lock);
// g's constructor locks &quot;global_lock&quot;
// g's constructor locks "global_lock"
... // do anything:
// throw exceptions
// return
// or just fall through
} // g's destructor unlocks &quot;global_lock&quot;</PRE>
} // g's destructor unlocks "global_lock"
</pre>
<P>
<H2>Dependencies</H2>
<h2>Dependencies</h2>
<P>
None.
<p>None.</p>
<P>
<H2>Future Directions</H2>
<h2>Future Directions</h2>
<P>
This header will eventually be replaced by a Boost multithreading library.
<p>This header will eventually be replaced by a Boost multithreading
library.</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>

167
doc/implementation/mutex.html
View File

@@ -1,31 +1,38 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<TITLE>mutex - Mutex</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>mutex - Mutex</H1>
<title>mutex - Mutex</title>
</head>
<P>
<H2>Introduction</H2>
<body>
<img src="../../../../boost.png" width="276" height="86" alt="C++ Boost">
<P>
detail/mutex.hpp provides several mutex types that provide a consistent interface for OS-supplied mutex types. These are all thread-level mutexes; interprocess mutexes are not supported.
<h1 align="center">mutex - Mutex</h1>
<P>
<H2>Configuration</H2>
<h2>Introduction</h2>
<P>
This header file will try to guess what kind of system it is on. It will auto-configure itself for Win32 or POSIX+pthread systems. To stub out all mutex code, bypassing the auto-configuration, <SPAN CLASS="code">#define BOOST_NO_MT</SPAN> before any inclusion of this header. To prevent ODR violations, this should be defined in <STRONG>every</STRONG> translation unit in your project, including any library files.
<p>detail/mutex.hpp provides several mutex types that provide a consistent
interface for OS-supplied mutex types. These are all thread-level mutexes;
interprocess mutexes are not supported.</p>
<P>
<H2>Synopsis</H2>
<h2>Configuration</h2>
<PRE CLASS="code">namespace details {
<p>This header file will try to guess what kind of system it is on. It will
auto-configure itself for Win32 or POSIX+pthread systems. To stub out all
mutex code, bypassing the auto-configuration, <span class="code">#define
BOOST_NO_MT</span> before any inclusion of this header. To prevent ODR
violations, this should be defined in <strong>every</strong> translation
unit in your project, including any library files.</p>
<h2>Synopsis</h2>
<pre class="code">
namespace details {
namespace pool {
// Only present if on a Win32 system
@@ -77,53 +84,99 @@ class null_mutex
typedef ... default_mutex;
} // namespace pool
} // namespace details</PRE>
} // namespace details
</pre>
<P>
<H2>Semantics</H2>
<h2>Semantics</h2>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Symbol Table</EM></CAPTION>
<TR><TH>Symbol<TH>Meaning
<TR><TD CLASS="code">Mutex<TD>Any type defined in this header
<TR><TD CLASS="code">t<TD>value of type <SPAN CLASS="code">Mutex</SPAN>
</TABLE>
<table border align="center" summary="">
<caption>
<em>Symbol Table</em>
</caption>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Requirements satisfied by <SPAN CLASS="code">mutex</SPAN></EM></CAPTION>
<TR><TH>Expression<TH>Return Type<TH>Assertion/Note/Pre/Post-Condition
<TR><TD CLASS="code">m.lock()<TD>not used<TD>Locks the mutex
<TR><TD CLASS="code">m.unlock()<TD>not used<TD>Unlocks the mutex
</TABLE>
<tr>
<th>Symbol</th>
<P>
Each mutex is always either owned or unowned. If owned, then it is owned by a particular thread. To &quot;lock&quot; a mutex means to wait until the mutex is unowned, and then make it owned by the current thread. To &quot;unlock&quot; a mutex means to release ownership from the current thread (note that the current thread <STRONG>must</STRONG> own the mutex to release that ownership!). As a special case, the <SPAN CLASS="code">null_mutex</SPAN> never waits.
<th>Meaning</th>
</tr>
<P>
<H2>Dependencies</H2>
<tr>
<td class="code">Mutex</td>
<P>
May include the system headers <SPAN CLASS="code">&lt;windows.h&gt;</SPAN>, <SPAN CLASS="code">&lt;unistd.h&gt;</SPAN>, and/or <SPAN CLASS="code">&lt;pthread.h&gt;</SPAN>.
<td>Any type defined in this header</td>
</tr>
<P>
<H2>Future Directions</H2>
<tr>
<td class="code">t</td>
<P>
This header will eventually be replaced by a Boost multithreading library.
<td>value of type <span class="code">Mutex</span></td>
</tr>
</table><br>
<P>
<HR>
<table border align="center" summary="">
<caption>
<em>Requirements satisfied by <span class="code">mutex</span></em>
</caption>
<P>
Copyright &copy; 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)
<tr>
<th>Expression</th>
<P>
This file can be redistributed and/or modified under the terms found in <A HREF="../copyright.html">copyright.html</A>
<th>Return Type</th>
<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.
<th>Assertion/Note/Pre/Post-Condition</th>
</tr>
</BODY>
</HTML>
<tr>
<td class="code">m.lock()</td>
<td>not used</td>
<td>Locks the mutex</td>
</tr>
<tr>
<td class="code">m.unlock()</td>
<td>not used</td>
<td>Unlocks the mutex</td>
</tr>
</table>
<p>Each mutex is always either owned or unowned. If owned, then it is owned
by a particular thread. To "lock" a mutex means to wait until the mutex is
unowned, and then make it owned by the current thread. To "unlock" a mutex
means to release ownership from the current thread (note that the current
thread <strong>must</strong> own the mutex to release that ownership!). As
a special case, the <span class="code">null_mutex</span> never waits.</p>
<h2>Dependencies</h2>
<p>May include the system headers <span class=
"code">&lt;windows.h&gt;</span>, <span class=
"code">&lt;unistd.h&gt;</span>, and/or <span class=
"code">&lt;pthread.h&gt;</span>.</p>
<h2>Future Directions</h2>
<p>This header will eventually be replaced by a Boost multithreading
library.</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 &copy; 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>

111
doc/implementation/object_pool.html
View File

@@ -1,70 +1,85 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<TITLE>Object Pool Implementation</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>Object Pool Implementation</H1>
<title>Object Pool Implementation</title>
</head>
<P>
<H2>Dependencies</H2>
<body>
<img src="../../../../boost.png" width="276" height="86" alt="C++ Boost">
<P>
Includes the Boost header <SPAN CLASS="code">&quot;pool.hpp&quot;</SPAN> (see <A HREF="pool.html">pool.html</A>).
<h1 align="center">Object Pool Implementation</h1>
<P>
<H2>Extensions to Public Interface</H2>
<h2>Dependencies</h2>
<P>
Whenever an object of type <SPAN CLASS="code">ObjectPool</SPAN> needs memory from the system, it will request it from its <SPAN CLASS="code">UserAllocator</SPAN> template parameter. The amount requested is determined using a doubling algorithm; that is, each time more system memory is allocated, the amount of system memory requested is doubled. Users may control the doubling algorithm by using the following extensions.
<p>Includes the Boost header <span class="code">"pool.hpp"</span> (see
<a href="pool.html">pool.html</a>).</p>
<P>
<H3>Additional constructor parameter</H3>
<h2>Extensions to Public Interface</h2>
<P>
Users may pass an additional constructor parameter to <SPAN CLASS="code">ObjectPool</SPAN>. This parameter is of type <SPAN CLASS="code">size_type</SPAN>, and is the number of chunks to request from the system the first time that object needs to allocate system memory. The default is 32. This parameter may not be 0.
<p>Whenever an object of type <span class="code">ObjectPool</span> needs
memory from the system, it will request it from its <span class=
"code">UserAllocator</span> template parameter. The amount requested is
determined using a doubling algorithm; that is, each time more system
memory is allocated, the amount of system memory requested is doubled.
Users may control the doubling algorithm by using the following
extensions.</p>
<P>
<H3><SPAN CLASS="code">next_size</SPAN> accessor functions</H3>
<h3>Additional constructor parameter</h3>
<P>
The pair of functions <SPAN CLASS="code">size_type get_next_size() const;</SPAN> and <SPAN CLASS="code">void set_next_size(size_type);</SPAN> allow users to explicitly read and write the <SPAN CLASS="code">next_size</SPAN> value. This value is the number of chunks to request from the system the next time that object needs to allocate system memory. This value should never be set to 0.
<p>Users may pass an additional constructor parameter to <span class=
"code">ObjectPool</span>. This parameter is of type <span class=
"code">size_type</span>, and is the number of chunks to request from the
system the first time that object needs to allocate system memory. The
default is 32. This parameter may not be 0.</p>
<P>
<H2>Protected Interface</H2>
<h3><span class="code">next_size</span> accessor functions</h3>
<P>
<H3>Synopsis</H3>
<p>The pair of functions <span class="code">size_type get_next_size()
const;</span> and <span class="code">void set_next_size(size_type);</span>
allow users to explicitly read and write the <span class=
"code">next_size</span> value. This value is the number of chunks to
request from the system the next time that object needs to allocate system
memory. This value should never be set to 0.</p>
<PRE CLASS="code">template &lt;typename ElementType, typename UserAllocator = default_user_allocator_new_delete&gt;
<h2>Protected Interface</h2>
<h3>Synopsis</h3>
<pre class="code">
template &lt;typename ElementType, typename UserAllocator = default_user_allocator_new_delete&gt;
class object_pool: protected pool&lt;UserAllocator&gt;
{
... // public interface
};</PRE>
};
</pre>
<P>
<H3>Protected Derivation</H3>
<h3>Protected Derivation</h3>ObjectPool derives from a simple segregated
storage via protected derivation; this exposes all the <a href=
"pool.html">Pool implementation details</a> to all classes derived from
ObjectPool as well.
ObjectPool derives from a simple segregated storage via protected derivation; this exposes all the <A HREF="pool.html">Pool implementation details</A> to all classes derived from ObjectPool as well.
<h2><a href="../interfaces/object_pool.html">Interface Description</a></h2>
<hr>
<P>
<H2><A HREF="../interfaces/object_pool.html">Interface Description</A></H2>
<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>
<HR>
<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>
Copyright &copy; 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)
<p><i>Copyright &copy; 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT
com)</i></p>
<P>
This file can be redistributed and/or modified under the terms found in <A HREF="../copyright.html">copyright.html</A>
<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>

307
doc/implementation/pool.html
View File

@@ -1,28 +1,39 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<TITLE>Pool Implementation</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 Implementation</H1>
<title>Pool Implementation</title>
</head>
<P>
<H2>Dependencies</H2>
<body>
<img src="../../../../boost.png" width="276" height="86" alt="C++ Boost">
<P>
Includes the system headers <SPAN CLASS="code">&lt;functional&gt;</SPAN>, <SPAN CLASS="code">&lt;new&gt;</SPAN>, <SPAN CLASS="code">&lt;cstddef&gt;</SPAN>, <SPAN CLASS="code">&lt;cstdlib&gt;</SPAN>, and <SPAN CLASS="code">&lt;exception&gt;</SPAN>.
<h1 align="center">Pool Implementation</h1>
<P>
Includes the Boost headers <SPAN CLASS="code">&quot;detail/ct_gcd_lcm.hpp&quot;</SPAN> (see <A HREF="ct_gcd_lcm.html">ct_gcd_lcm.html</A>), <SPAN CLASS="code">&quot;detail/gcd_lcm.hpp&quot;</SPAN> (see <A HREF="gcd_lcm.html">gcd_lcm.html</A>), and <SPAN CLASS="code">&quot;simple_segregated_storage.hpp&quot;</SPAN> (see <A HREF="simple_segregated_storage.html">simple_segregated_storage.html</A>).
<h2>Dependencies</h2>
<P>
<H2>Synopsis</H2>
<p>Includes the system headers <span class=
"code">&lt;functional&gt;</span>, <span class="code">&lt;new&gt;</span>,
<span class="code">&lt;cstddef&gt;</span>, <span class=
"code">&lt;cstdlib&gt;</span>, and <span class=
"code">&lt;exception&gt;</span>.</p>
<PRE CLASS="code">namespace details {
<p>Includes the Boost headers <span class=
"code">"detail/ct_gcd_lcm.hpp"</span> (see <a href=
"ct_gcd_lcm.html">ct_gcd_lcm.html</a>), <span class=
"code">"detail/gcd_lcm.hpp"</span> (see <a href=
"gcd_lcm.html">gcd_lcm.html</a>), and <span class=
"code">"simple_segregated_storage.hpp"</span> (see <a href=
"simple_segregated_storage.html">simple_segregated_storage.html</a>).</p>
<h2>Synopsis</h2>
<pre class="code">
namespace details {
template &lt;typename SizeType&gt;
class PODptr
@@ -37,17 +48,17 @@ class PODptr
bool valid() const;
void invalidate();
char * & begin();
char * &amp; begin();
char * begin() const;
char * end() const;
size_type total_size() const;
size_type element_size() const;
size_type & next_size() const;
char * & next_ptr() const;
size_type &amp; next_size() const;
char * &amp; next_ptr() const;
PODptr next() const;
void next(const PODptr & arg) const;
void next(const PODptr &amp; arg) const;
};
} // namespace details
@@ -60,8 +71,8 @@ class pool: protected simple_segregated_storage&lt;typename UserAllocator::size_
protected:
details::PODptr&lt;size_type&gt; list;
simple_segregated_storage&lt;size_type&gt; & store();
const simple_segregated_storage&lt;size_type&gt; & store() const;
simple_segregated_storage&lt;size_type&gt; &amp; store();
const simple_segregated_storage&lt;size_type&gt; &amp; store() const;
const size_type requested_size;
size_type next_size;
@@ -74,143 +85,201 @@ class pool: protected simple_segregated_storage&lt;typename UserAllocator::size_
pool(size_type requested_size, size_type next_size);
size_type get_next_size() const;
void set_next_size(size_type);
};</PRE>
};
</pre>
<P>
<H2>Extensions to Public Interface</H2>
<h2>Extensions to Public Interface</h2>
<P>
Whenever an object of type <SPAN CLASS="code">pool</SPAN> needs memory from the system, it will request it from its <SPAN CLASS="code">UserAllocator</SPAN> template parameter. The amount requested is determined using a doubling algorithm; that is, each time more system memory is allocated, the amount of system memory requested is doubled. Users may control the doubling algorithm by using the following extensions.
<p>Whenever an object of type <span class="code">pool</span> needs memory
from the system, it will request it from its <span class=
"code">UserAllocator</span> template parameter. The amount requested is
determined using a doubling algorithm; that is, each time more system
memory is allocated, the amount of system memory requested is doubled.
Users may control the doubling algorithm by using the following
extensions.</p>
<P>
<H3>Additional constructor parameter</H3>
<h3>Additional constructor parameter</h3>
<P>
Users may pass an additional constructor parameter to <SPAN CLASS="code">pool</SPAN>. This parameter is of type <SPAN CLASS="code">size_type</SPAN>, and is the number of chunks to request from the system the first time that object needs to allocate system memory. The default is 32. This parameter may not be 0.
<p>Users may pass an additional constructor parameter to <span class=
"code">pool</span>. This parameter is of type <span class=
"code">size_type</span>, and is the number of chunks to request from the
system the first time that object needs to allocate system memory. The
default is 32. This parameter may not be 0.</p>
<P>
<H3><SPAN CLASS="code">next_size</SPAN> accessor functions</H3>
<h3><span class="code">next_size</span> accessor functions</h3>
<P>
The pair of functions <SPAN CLASS="code">size_type get_next_size() const;</SPAN> and <SPAN CLASS="code">void set_next_size(size_type);</SPAN> allow users to explicitly read and write the <SPAN CLASS="code">next_size</SPAN> value. This value is the number of chunks to request from the system the next time that object needs to allocate system memory. This value should never be set to 0.
<p>The pair of functions <span class="code">size_type get_next_size()
const;</span> and <span class="code">void set_next_size(size_type);</span>
allow users to explicitly read and write the <span class=
"code">next_size</span> value. This value is the number of chunks to
request from the system the next time that object needs to allocate system
memory. This value should never be set to 0.</p>
<P>
<H2>Class <SPAN CLASS="code">PODptr</SPAN></H2>
<h2>Class <span class="code">PODptr</span></h2>
<P>
<SPAN CLASS="code">PODptr</SPAN> is a class that pretends to be a &quot;pointer&quot; to different class types that don't really exist. It provides member functions to access the &quot;data&quot; of the &quot;object&quot; it points to. Since these &quot;class&quot; types are of differing sizes, and contain some information at the end of their memory (for alignment reasons), <SPAN CLASS="code">PODptr</SPAN> must contain the size of this &quot;class&quot; as well as the pointer to this &quot;object&quot;.
<p><span class="code">PODptr</span> is a class that pretends to be a
"pointer" to different class types that don't really exist. It provides
member functions to access the "data" of the "object" it points to. Since
these "class" types are of differing sizes, and contain some information at
the end of their memory (for alignment reasons), <span class=
"code">PODptr</span> must contain the size of this "class" as well as the
pointer to this "object".</p>
<P>
A <SPAN CLASS="code">PODptr</SPAN> holds the location and size of a memory block allocated from the system. Each memory block is split logically into three sections:
<OL>
<LI>Chunk area. This section may be different sizes. <SPAN CLASS="code">PODptr</SPAN> does not care what the size of the chunks is, but it does care (and keep track of) the total size of the chunk area.</LI>
<LI>Next pointer. This section is always the same size for a given <SPAN CLASS="code">SizeType</SPAN>. It holds a pointer to the location of the next memory block in the memory block list, or 0 if there is no such block.</LI>
<LI>Next size. This section is always the same size for a given <SPAN CLASS="code">SizeType</SPAN>. It holds the size of the next memory block in the memory block list.</LI>
</OL>
<p>A <span class="code">PODptr</span> holds the location and size of a
memory block allocated from the system. Each memory block is split
logically into three sections:</p>
<P>
The <SPAN CLASS="code">PODptr</SPAN> class just provides cleaner ways of dealing with raw memory blocks.
<ol>
<li>Chunk area. This section may be different sizes. <span class=
"code">PODptr</span> does not care what the size of the chunks is, but it
does care (and keep track of) the total size of the chunk area.</li>
<P>
<H3>Validity</H3>
<li>Next pointer. This section is always the same size for a given
<span class="code">SizeType</span>. It holds a pointer to the location of
the next memory block in the memory block list, or 0 if there is no such
block.</li>
<P>
A <SPAN CLASS="code">PODptr</SPAN> object is either <EM>valid</EM> or <EM>invalid</EM>. An invalid <SPAN CLASS="code">PODptr</SPAN> is analogous to a null pointer.
<li>Next size. This section is always the same size for a given
<span class="code">SizeType</span>. It holds the size of the next memory
block in the memory block list.</li>
</ol>
<P>
The default constructor for <SPAN CLASS="code">PODptr</SPAN> will result in an invalid object. Calling the member function <SPAN CLASS="code">invalidate</SPAN> will result in that object becoming invalid. The member function <SPAN CLASS="code">valid</SPAN> can be used to test for validity.
<p>The <span class="code">PODptr</span> class just provides cleaner ways of
dealing with raw memory blocks.</p>
<P>
<H3>Getting <SPAN CLASS="code">PODptr</SPAN> objects</H3>
<h3>Validity</h3>
<P>
A <SPAN CLASS="code">PODptr</SPAN> may be created to point to a memory block by passing the address and size of that memory block into the constructor. A <SPAN CLASS="code">PODptr</SPAN> constructed in this way is valid.
<p>A <span class="code">PODptr</span> object is either <em>valid</em> or
<em>invalid</em>. An invalid <span class="code">PODptr</span> is analogous
to a null pointer.</p>
<P>
A <SPAN CLASS="code">PODptr</SPAN> may also be created by a call to the member function <SPAN CLASS="code">next</SPAN>, which returns a <SPAN CLASS="code">PODptr</SPAN> which points to the next memory block in the memory block list, or an invalid <SPAN CLASS="code">PODptr</SPAN> if there is no such block.
<p>The default constructor for <span class="code">PODptr</span> will result
in an invalid object. Calling the member function <span class=
"code">invalidate</span> will result in that object becoming invalid. The
member function <span class="code">valid</span> can be used to test for
validity.</p>
<P>
<H3>Accessing the &quot;pointer&quot; data</H3>
<h3>Getting <span class="code">PODptr</span> objects</h3>
<P>
Each <SPAN CLASS="code">PODptr</SPAN> keeps the address and size of its memory block. The address may be read or written by the member functions <SPAN CLASS="code">begin</SPAN>. The size of the memory block may only be read, and is done so by the member function <SPAN CLASS="code">total_size</SPAN>.
<p>A <span class="code">PODptr</span> may be created to point to a memory
block by passing the address and size of that memory block into the
constructor. A <span class="code">PODptr</span> constructed in this way is
valid.</p>
<P>
<H3>Accessing the sections of the memory block</H3>
<p>A <span class="code">PODptr</span> may also be created by a call to the
member function <span class="code">next</span>, which returns a
<span class="code">PODptr</span> which points to the next memory block in
the memory block list, or an invalid <span class="code">PODptr</span> if
there is no such block.</p>
<P>
The chunk area may be accessed by the member functions <SPAN CLASS="code">begin</SPAN> and <SPAN CLASS="code">end</SPAN>, in conjunction with <SPAN CLASS="code">element_size</SPAN>. The value returned by <SPAN CLASS="code">end</SPAN> is always the value returned by <SPAN CLASS="code">begin</SPAN> plus <SPAN CLASS="code">element_size</SPAN>. Only <SPAN CLASS="code">begin</SPAN> is writeable. <SPAN CLASS="code">end</SPAN> is a past-the-end value; using pointers beginning at <SPAN CLASS="code">begin</SPAN> and ending before <SPAN CLASS="code">end</SPAN> allows one to iterate through the chunks in a memory block.
<h3>Accessing the "pointer" data</h3>
<P>
The next pointer area may be accessed by the member function <SPAN CLASS="code">next_ptr</SPAN>. The next size area may be accessed by the member function <SPAN CLASS="code">next_size</SPAN>. Both of these are writeable. They may both be read or set at the same time through the member function <SPAN CLASS="code">next</SPAN>.
<p>Each <span class="code">PODptr</span> keeps the address and size of its
memory block. The address may be read or written by the member functions
<span class="code">begin</span>. The size of the memory block may only be
read, and is done so by the member function <span class=
"code">total_size</span>.</p>
<P>
<H2>Protected Interface</H2>
<h3>Accessing the sections of the memory block</h3>
<P>
<H3>Protected Derivation</H3>
<p>The chunk area may be accessed by the member functions <span class=
"code">begin</span> and <span class="code">end</span>, in conjunction with
<span class="code">element_size</span>. The value returned by <span class=
"code">end</span> is always the value returned by <span class=
"code">begin</span> plus <span class="code">element_size</span>. Only
<span class="code">begin</span> is writeable. <span class="code">end</span>
is a past-the-end value; using pointers beginning at <span class=
"code">begin</span> and ending before <span class="code">end</span> allows
one to iterate through the chunks in a memory block.</p>
Pool derives from a simple segregated storage via protected derivation; this exposes all the <A HREF="simple_segregated_storage.html">simple segregated storage implementation details</A> to all classes derived from Pool as well.
<p>The next pointer area may be accessed by the member function
<span class="code">next_ptr</span>. The next size area may be accessed by
the member function <span class="code">next_size</span>. Both of these are
writeable. They may both be read or set at the same time through the member
function <span class="code">next</span>.</p>
<P>
<H3 CLASS="code">details::PODptr&lt;size_type&gt; list;</H3>
<h2>Protected Interface</h2>
<P>
This is the list of memory blocks that have been allocated by this Pool object. It is <STRONG>not</STRONG> the same as the list of free memory chunks (exposed by simple segregated storage as <SPAN CLASS="code">first</SPAN>).
<h3>Protected Derivation</h3>Pool derives from a simple segregated storage
via protected derivation; this exposes all the <a href=
"simple_segregated_storage.html">simple segregated storage implementation
details</a> to all classes derived from Pool as well.
<P>
<H3><SPAN CLASS="code">store</SPAN> functions</H3>
<h3 class="code">details::PODptr&lt;size_type&gt; list;</h3>
<P>
These are convenience functions, used to return the base simple segregated storage object.
<p>This is the list of memory blocks that have been allocated by this Pool
object. It is <strong>not</strong> the same as the list of free memory
chunks (exposed by simple segregated storage as <span class=
"code">first</span>).</p>
<P>
<H3 CLASS="code">const size_type requested_size;</H3>
<h3><span class="code">store</span> functions</h3>
<P>
The first argument passed into the constructor. Represents the number of bytes in each chunk requested by the user. The actual size of the chunks may be different; see <SPAN CLASS="code">alloc_size</SPAN>, below.
<p>These are convenience functions, used to return the base simple
segregated storage object.</p>
<P>
<H3 CLASS="code">size_type next_size</H3>
<h3 class="code">const size_type requested_size;</h3>
<P>
The number of chunks to request from the <SPAN CLASS="code">UserAllocator</SPAN> the next time we need to allocate system memory. See the extensions descriptions, above.
<p>The first argument passed into the constructor. Represents the number of
bytes in each chunk requested by the user. The actual size of the chunks
may be different; see <span class="code">alloc_size</span>, below.</p>
<P>
<H3 CLASS="code">details::PODptr&lt;size_type&gt; find_POD(void * chunk) const;</H3>
<h3 class="code">size_type next_size</h3>
<P>
Searches through the memory block list, looking for the block that <SPAN CLASS="code">chunk</SPAN> was allocated from or may be allocated from in the future. Returns that block if found, or an invalid value if <SPAN CLASS="code">chunk</SPAN> has been allocated from another Pool or may be allocated from another Pool in the future. Results for other values of <SPAN CLASS="code">chunk</SPAN> may be wrong.
<p>The number of chunks to request from the <span class=
"code">UserAllocator</span> the next time we need to allocate system
memory. See the extensions descriptions, above.</p>
<P>
<H3 CLASS="code">static bool is_from(void * chunk, char * i, size_type sizeof_i);</H3>
<h3 class="code">details::PODptr&lt;size_type&gt; find_POD(void * chunk)
const;</h3>
<P>
Tests <SPAN CLASS="code">chunk</SPAN> to see if it has been allocated from the memory chunk at <SPAN CLASS="code">i</SPAN> with an element size of <SPAN CLASS="code">sizeof_i</SPAN>. Note that <SPAN CLASS="code">sizeof_i</SPAN> is the size of the chunk area of that block, not the total size of that block.
<p>Searches through the memory block list, looking for the block that
<span class="code">chunk</span> was allocated from or may be allocated from
in the future. Returns that block if found, or an invalid value if
<span class="code">chunk</span> has been allocated from another Pool or may
be allocated from another Pool in the future. Results for other values of
<span class="code">chunk</span> may be wrong.</p>
<P>
Returns <SPAN CLASS="code">true</SPAN> if <SPAN CLASS="code">chunk</SPAN> has been allocated from that memory block or may be allocated from that block in the future. Returns <SPAN CLASS="code">false</SPAN> if <SPAN CLASS="code">chunk</SPAN> has been allocated from another block or may be allocated from another block in the future. Results for other values of <SPAN CLASS="code">chunk</SPAN> may be wrong.
<h3 class="code">static bool is_from(void * chunk, char * i, size_type
sizeof_i);</h3>
<P>
<H3 CLASS="code">size_type alloc_size() const;</H3>
<p>Tests <span class="code">chunk</span> to see if it has been allocated
from the memory chunk at <span class="code">i</span> with an element size
of <span class="code">sizeof_i</span>. Note that <span class=
"code">sizeof_i</span> is the size of the chunk area of that block, not the
total size of that block.</p>
<P>
Returns the calculated size of the memory chunks that will be allocated by this Pool. For <A HREF="alignment.html">alignment reasons</A>, this is defined to be <SPAN CLASS="code">lcm(requested_size, sizeof(void *), sizeof(size_type))</SPAN>.
<p>Returns <span class="code">true</span> if <span class=
"code">chunk</span> has been allocated from that memory block or may be
allocated from that block in the future. Returns <span class=
"code">false</span> if <span class="code">chunk</span> has been allocated
from another block or may be allocated from another block in the future.
Results for other values of <span class="code">chunk</span> may be
wrong.</p>
<P>
<H2><A HREF="../interfaces/pool.html">Interface Description</A></H2>
<h3 class="code">size_type alloc_size() const;</h3>
<P>
<HR>
<p>Returns the calculated size of the memory chunks that will be allocated
by this Pool. For <a href="alignment.html">alignment reasons</a>, this is
defined to be <span class="code">lcm(requested_size, sizeof(void *),
sizeof(size_type))</span>.</p>
<P>
Copyright &copy; 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)
<h2><a href="../interfaces/pool.html">Interface Description</a></h2>
<hr>
<P>
This file can be redistributed and/or modified under the terms found in <A HREF="../copyright.html">copyright.html</A>
<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 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.
<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>
</BODY>
</HTML>
<p><i>Copyright &copy; 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>

142
doc/implementation/pool_alloc.html
View File

@@ -1,28 +1,35 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<TITLE>pool_alloc - Boost Pool Standard Allocators Implementation</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_alloc - Boost Pool Standard Allocators Implementation</H1>
<title>pool_alloc - Boost Pool Standard Allocators Implementation</title>
</head>
<P>
<H2>Dependencies</H2>
<body>
<img src="../../../../boost.png" width="276" height="86" alt="C++ Boost">
<P>
Includes the system headers <SPAN CLASS="code">&lt;new&gt;</SPAN> and <SPAN CLASS="code">&lt;limits&gt;</SPAN>.
<h1 align="center">pool_alloc - Boost Pool Standard Allocators
Implementation</h1>
<P>
Includes the Boost headers <SPAN CLASS="code">&quot;singleton_pool.hpp&quot;</SPAN> (see <A HREF="singleton_pool.html">singleton_pool.html</A>) and <SPAN CLASS="code">&quot;detail/mutex.hpp&quot;</SPAN> (see <A HREF="mutex.html">mutex.html</A>).
<h2>Dependencies</h2>
<P>
<H2>Synopsis</H2>
<p>Includes the system headers <span class="code">&lt;new&gt;</span> and
<span class="code">&lt;limits&gt;</span>.</p>
<PRE CLASS="code">template &lt;typename T,
<p>Includes the Boost headers <span class=
"code">"singleton_pool.hpp"</span> (see <a href=
"singleton_pool.html">singleton_pool.html</a>) and <span class=
"code">"detail/mutex.hpp"</span> (see <a href=
"mutex.html">mutex.html</a>).</p>
<h2>Synopsis</h2>
<pre class="code">
template &lt;typename T,
typename UserAllocator = default_user_allocator_new_delete,
typename Mutex = details::pool::default_mutex,
unsigned NextSize = 32&gt;
@@ -60,68 +67,77 @@ class fast_pool_allocator
{
typedef fast_pool_allocator&lt;U, UserAllocator, Mutex, NextSize&gt; other;
};
};</PRE>
};
</pre>
<P>
<H2>Extensions to Public Interface</H2>
<h2>Extensions to Public Interface</h2>
<P>
<H3>Additional template parameters</H3>
<h3>Additional template parameters</h3>
<P>
<H4 CLASS="code">Mutex</H4>
<h4 class="code">Mutex</h4>
<P>
This parameter allows the user to determine the type of synchronization to be used on the underlying singleton pool. See the extensions to the public interface of <A HREF="singleton_pool.html">singleton pool</A> for more information.
<p>This parameter allows the user to determine the type of synchronization
to be used on the underlying singleton pool. See the extensions to the
public interface of <a href="singleton_pool.html">singleton pool</a> for
more information.</p>
<P>
<H4 CLASS="code">NextSize</H4>
<h4 class="code">NextSize</h4>
<P>
The value of this parameter is passed to the underlying Pool when it is created. See the extensions to the public interface of <A HREF="pool.html">pool</A> for more information.
<p>The value of this parameter is passed to the underlying Pool when it is
created. See the extensions to the public interface of <a href=
"pool.html">pool</a> for more information.</p>
<P>
<H3>Modification of <SPAN CLASS="code">rebind</SPAN></H3>
<h3>Modification of <span class="code">rebind</span></h3>
<P>
The struct <SPAN CLASS="code">rebind</SPAN> has been redefined to preserve the values of the additional template parameters.
<p>The struct <span class="code">rebind</span> has been redefined to
preserve the values of the additional template parameters.</p>
<P>
<H3>Additional members</H3>
<h3>Additional members</h3>
<P>
The typedef <SPAN CLASS="code">mutex</SPAN> and the static const value <SPAN CLASS="code">next_size</SPAN> publish the values of the template parameters <SPAN CLASS="code">Mutex</SPAN> and <SPAN CLASS="code">NextSize</SPAN>, respectively.
<p>The typedef <span class="code">mutex</span> and the static const value
<span class="code">next_size</span> publish the values of the template
parameters <span class="code">Mutex</span> and <span class=
"code">NextSize</span>, respectively.</p>
<P>
<H2>Notes</H2>
<h2>Notes</h2>
<P>
A number of common STL libraries contain bugs in their using of allocators. Specifically, they pass null pointers to the <SPAN CLASS="code">deallocate</SPAN> function, which is explicitly forbidden by the Standard [20.1.5 Table 32]. PoolAlloc will work around these libraries if it detects them; currently, workarounds are in place for:
<UL>
<LI>Borland C++ (Builder and command-line compiler) with default (RogueWave) library, ver. 5 and earlier</LI>
<LI>STLport (with any compiler), ver. 4.0 and earlier</LI>
</UL>
<p>A number of common STL libraries contain bugs in their using of
allocators. Specifically, they pass null pointers to the <span class=
"code">deallocate</span> function, which is explicitly forbidden by the
Standard [20.1.5 Table 32]. PoolAlloc will work around these libraries if
it detects them; currently, workarounds are in place for:</p>
<P>
<H2>Future Directions</H2>
<ul>
<li>Borland C++ (Builder and command-line compiler) with default
(RogueWave) library, ver. 5 and earlier</li>
<P>
When the Boost multithreading library is completed, the <SPAN CLASS="code">Mutex</SPAN> parameter will be replaced by something from that library providing the same flexibility and will move from an implementation detail into the interface specification.
<li>STLport (with any compiler), ver. 4.0 and earlier</li>
</ul>
<P>
<H2><A HREF="../interfaces/pool_alloc.html">Interface Description</A></H2>
<h2>Future Directions</h2>
<P>
<HR>
<p>When the Boost multithreading library is completed, the <span class=
"code">Mutex</span> parameter will be replaced by something from that
library providing the same flexibility and will move from an implementation
detail into the interface specification.</p>
<P>
Copyright &copy; 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)
<h2><a href="../interfaces/pool_alloc.html">Interface Description</a></h2>
<hr>
<P>
This file can be redistributed and/or modified under the terms found in <A HREF="../copyright.html">copyright.html</A>
<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 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.
<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>
</BODY>
</HTML>
<p><i>Copyright &copy; 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>

107
doc/implementation/pool_construct.html
View File

@@ -1,62 +1,83 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<TITLE>Object Pool Constructors Generator</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>Object Pool Constructors Generator</H1>
<title>Object Pool Constructors Generator</title>
</head>
<P>
<H2>Description</H2>
<body>
<img src="../../../../boost.png" width="276" height="86" alt="C++ Boost">
<P>
The template class <SPAN CLASS="code">object_pool</SPAN> (see <A HREF="object_pool.html">object_pool.html</A>) contains a number of functions <SPAN CLASS="code">construct(..)</SPAN>, which both allocate and construct an object in a single operation.
<h1 align="center">Object Pool Constructors Generator</h1>
<P>
Since the number and type of arguments to this function is totally arbitrary, a simple system has been set up to automatically generate template <SPAN CLASS="code">construct</SPAN> functions. This system is based on the macro preprocessor <STRONG>m4</STRONG>, which is standard on UNIX systems and also available for Win32 systems.
<h2>Description</h2>
<P>
detail/pool_construct.m4, when run with <STRONG>m4</STRONG>, will create the file detail/pool_construct.inc, which only defines the <SPAN CLASS="code">construct</SPAN> functions for the proper number of arguments. The number of arguments may be passed into the file as an m4 macro, <SPAN CLASS="code">NumberOfArguments</SPAN>; if not provided, it will default to <SPAN CLASS="code">3</SPAN>.
<p>The template class <span class="code">object_pool</span> (see <a href=
"object_pool.html">object_pool.html</a>) contains a number of functions
<span class="code">construct(..)</span>, which both allocate and construct
an object in a single operation.</p>
<P>
For each different number of arguments (<SPAN CLASS="code">1</SPAN> to <SPAN CLASS="code">NumberOfArguments</SPAN>), a template function is generated. There are the same number of template parameters as there are arguments, and each argument's type is a reference to that (possibly cv-qualified) template argument. Each possible permutation of the cv-qualifications is also generated.
<p>Since the number and type of arguments to this function is totally
arbitrary, a simple system has been set up to automatically generate
template <span class="code">construct</span> functions. This system is
based on the macro preprocessor <strong>m4</strong>, which is standard on
UNIX systems and also available for Win32 systems.</p>
<P>
Because each permutation is generated for each possible number of arguments, the included file size grows exponentially in terms of the number of constructor arguments, not linearly. For the sake of rational compile times, only use as many arguments as you need.
<p>detail/pool_construct.m4, when run with <strong>m4</strong>, will create
the file detail/pool_construct.inc, which only defines the <span class=
"code">construct</span> functions for the proper number of arguments. The
number of arguments may be passed into the file as an m4 macro,
<span class="code">NumberOfArguments</span>; if not provided, it will
default to <span class="code">3</span>.</p>
<P>
detail/pool_construct.bat and detail/pool_construct.sh are also provided to call <STRONG>m4</STRONG>, defining <SPAN CLASS="code">NumberOfArguments</SPAN> to be their command-line parameter. See these files for more details.
<p>For each different number of arguments (<span class="code">1</span> to
<span class="code">NumberOfArguments</span>), a template function is
generated. There are the same number of template parameters as there are
arguments, and each argument's type is a reference to that (possibly
cv-qualified) template argument. Each possible permutation of the
cv-qualifications is also generated.</p>
<P>
<H2>Dependencies</H2>
<p>Because each permutation is generated for each possible number of
arguments, the included file size grows exponentially in terms of the
number of constructor arguments, not linearly. For the sake of rational
compile times, only use as many arguments as you need.</p>
<P>
Dependent on for.m4 (see <A HREF="for.html">for.html</A>).
<p>detail/pool_construct.bat and detail/pool_construct.sh are also provided
to call <strong>m4</strong>, defining <span class=
"code">NumberOfArguments</span> to be their command-line parameter. See
these files for more details.</p>
<P>
<H2>Future Directions</H2>
<h2>Dependencies</h2>
<P>
This system may be complemented by or replaced by a Python (or some other language) script.
<p>Dependent on for.m4 (see <a href="for.html">for.html</a>).</p>
<P>
<H2><A HREF="../interfaces/object_pool.html">Interface Description</A></H2>
<h2>Future Directions</h2>
<P>
<HR>
<p>This system may be complemented by or replaced by a Python (or some
other language) script.</p>
<P>
Copyright &copy; 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)
<h2><a href="../interfaces/object_pool.html">Interface Description</a></h2>
<hr>
<P>
This file can be redistributed and/or modified under the terms found in <A HREF="../copyright.html">copyright.html</A>
<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 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.
<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>
</BODY>
</HTML>
<p><i>Copyright &copy; 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>

118
doc/implementation/simple_segregated_storage.html
View File

@@ -1,76 +1,96 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<TITLE>Simple Segregated Storage Implementation</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>Simple Segregated Storage Implementation</H1>
<title>Simple Segregated Storage Implementation</title>
</head>
<P>
<H2>Dependencies</H2>
<body>
<img src="../../../../boost.png" width="276" height="86" alt="C++ Boost">
<P>
Includes the system headers <SPAN CLASS="code">&lt;cstddef&gt;</SPAN> and <SPAN CLASS="code">&lt;functional&gt;</SPAN>.
<h1 align="center">Simple Segregated Storage Implementation</h1>
<P>
<H2>Protected Interface</H2>
<h2>Dependencies</h2>
<P>
<H3>Synopsis</H3>
<p>Includes the system headers <span class="code">&lt;cstddef&gt;</span>
and <span class="code">&lt;functional&gt;</span>.</p>
<PRE CLASS="code">template &lt;typename SizeType = std::size_t&gt;
<h2>Protected Interface</h2>
<h3>Synopsis</h3>
<pre class="code">
template &lt;typename SizeType = std::size_t&gt;
class simple_segregated_storage
{
... // Public interface
protected:
void * first;
static void * & nextof(void * const ptr);
static void * &amp; nextof(void * const ptr);
void * find_prev(void * ptr);
};</PRE>
};
</pre>
<P>
<H3 CLASS="code">void * first;</H3>
<h3 class="code">void * first;</h3>
<P>
This data member is the free list. It points to the first chunk in the free list, or is equal to 0 if the free list is empty.
<p>This data member is the free list. It points to the first chunk in the
free list, or is equal to 0 if the free list is empty.</p>
<P>
<H3 CLASS="code">static void * & nextof(void * const ptr);</H3>
<h3 class="code">static void * &amp; nextof(void * const ptr);</h3>
<P>
This is a convenience function. It helps clean up code dealing with the free list by making it more readable. The return value is just <SPAN CLASS="code">*ptr</SPAN> cast to the appropriate type. <SPAN CLASS="code">ptr</SPAN> must not be 0.
<p>This is a convenience function. It helps clean up code dealing with the
free list by making it more readable. The return value is just <span class=
"code">*ptr</span> cast to the appropriate type. <span class=
"code">ptr</span> must not be 0.</p>
<P>
As an example, let us assume that we want to truncate the free list after the first chunk. That is, we want to set <SPAN CLASS="code">*first</SPAN> to 0; this will result in a free list with only one entry. The normal way to do this is to first cast <SPAN CLASS="code">first</SPAN> to a pointer to a pointer to void, and then dereference and assign (<SPAN CLASS="code">*static_cast&lt;void **&gt;(first) = 0;</SPAN>). This can be done more easily through the use of this convenience function (<SPAN CLASS="code">nextof(first) = 0;</SPAN>).
<p>As an example, let us assume that we want to truncate the free list
after the first chunk. That is, we want to set <span class=
"code">*first</span> to 0; this will result in a free list with only one
entry. The normal way to do this is to first cast <span class=
"code">first</span> to a pointer to a pointer to void, and then dereference
and assign (<span class="code">*static_cast&lt;void **&gt;(first) =
0;</span>). This can be done more easily through the use of this
convenience function (<span class="code">nextof(first) = 0;</span>).</p>
<P>
<H3 CLASS="code">void * find_prev(void * ptr);</H3>
<h3 class="code">void * find_prev(void * ptr);</h3>
<P>
Traverses the free list referred to by <SPAN CLASS="code">first</SPAN>, and returns the pointer previous to where <SPAN CLASS="code">ptr</SPAN> would go if it was in the free list. Returns 0 if <SPAN CLASS="code">ptr</SPAN> would go at the beginning of the free list (i.e., before <SPAN CLASS="code">first</SPAN>).
<p>Traverses the free list referred to by <span class="code">first</span>,
and returns the pointer previous to where <span class="code">ptr</span>
would go if it was in the free list. Returns 0 if <span class=
"code">ptr</span> would go at the beginning of the free list (i.e., before
<span class="code">first</span>).</p>
<P>
Note that this function finds the location previous to where <SPAN CLASS="code">ptr</SPAN> <STRONG>would</STRONG> go <STRONG>if it was</STRONG> in the free list. It does <STRONG>not</STRONG> find the entry in the free list before <SPAN CLASS="code">ptr</SPAN> (unless <SPAN CLASS="code">ptr</SPAN> is already in the free list). Specifically, <SPAN CLASS="code">find_prev(0)</SPAN> will return 0, <STRONG>not</STRONG> the last entry in the free list.
<p>Note that this function finds the location previous to where
<span class="code">ptr</span> <strong>would</strong> go <strong>if it
was</strong> in the free list. It does <strong>not</strong> find the entry
in the free list before <span class="code">ptr</span> (unless <span class=
"code">ptr</span> is already in the free list). Specifically, <span class=
"code">find_prev(0)</span> will return 0, <strong>not</strong> the last
entry in the free list.</p>
<P>
<H2><A HREF="../interfaces/simple_segregated_storage.html">Interface Description</A></H2>
<h2><a href="../interfaces/simple_segregated_storage.html">Interface
Description</a></h2>
<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>

153
doc/implementation/singleton.html
View File

@@ -1,25 +1,29 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<TITLE>singleton - Singleton</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>singleton - Singleton</H1>
<title>singleton - Singleton</title>
</head>
<P>
<H2>Introduction</H2>
<body>
<img src="../../../../boost.png" width="276" height="86" alt="C++ Boost">
<P>
detail/singleton.hpp provides a way to access a Singleton of a class type. This is <STRONG>not</STRONG> a general Singleton solution! It is restricted in that the class type must have a default constructor.
<h1 align="center">singleton - Singleton</h1>
<P>
<H2>Synopsis</H2>
<h2>Introduction</h2>
<PRE CLASS="code">namespace details {
<p>detail/singleton.hpp provides a way to access a Singleton of a class
type. This is <strong>not</strong> a general Singleton solution! It is
restricted in that the class type must have a default constructor.</p>
<h2>Synopsis</h2>
<pre class="code">
namespace details {
namespace pool {
template &lt;typename T&gt;
@@ -31,64 +35,97 @@ class singleton_default
public:
typedef T object_type;
static object_type & instance();
static object_type &amp; instance();
};
} // namespace pool
} // namespace details</PRE>
} // namespace details
</pre>
<P>
<H2>Semantics</H2>
<h2>Semantics</h2>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Symbol Table</EM></CAPTION>
<TR><TH>Symbol<TH>Meaning
<TR><TD CLASS="code">T<TD>Any class with a non-throwing default constructor and non-throwing destructor
</TABLE>
<table border align="center" summary="">
<caption>
<em>Symbol Table</em>
</caption>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Requirements satisfied by <SPAN CLASS="code">singleton_default&lt;T&gt;</SPAN></EM></CAPTION>
<TR><TH>Expression<TH>Return Type<TH>Assertion/Note/Pre/Post-Condition
<TR><TD CLASS="code">singleton_default&lt;T&gt;::instance()<TD CLASS="code">T &amp;<TD>Returns a reference to the singleton instance
</TABLE>
<tr>
<th>Symbol</th>
<P>
<H2>Guarantees</H2>
<th>Meaning</th>
</tr>
<P>
The singleton instance is guaranteed to be constructed before <SPAN CLASS="code">main()</SPAN> begins, and destructed after <SPAN CLASS="code">main()</SPAN> ends. Furthermore, it is guaranteed to be constructed before the first call to <SPAN CLASS="code">singleton_default&lt;T&gt;::instance()</SPAN> is complete (even if called before <SPAN CLASS="code">main()</SPAN> begins). Thus, if there are not multiple threads running except within <SPAN CLASS="code">main()</SPAN>, and if all access to the singleton is restricted by mutexes, then this guarantee allows a thread-safe singleton.
<tr>
<td class="code">T</td>
<P>
<H2>Details</H2>
<td>Any class with a non-throwing default constructor and non-throwing
destructor</td>
</tr>
</table><br>
<P>
For details on how we provide the guarantees above, see the comments in the header file.
<table border align="center" summary="">
<caption>
<em>Requirements satisfied by <span class=
"code">singleton_default&lt;T&gt;</span></em>
</caption>
<P>
<H2>Dependencies</H2>
<tr>
<th>Expression</th>
<P>
None.
<th>Return Type</th>
<P>
<H2>Future Directions</H2>
<th>Assertion/Note/Pre/Post-Condition</th>
</tr>
<P>
This header may be replaced by a Boost singleton library.
<tr>
<td class="code">singleton_default&lt;T&gt;::instance()</td>
<P>
<HR>
<td class="code">T &amp;</td>
<P>
Copyright &copy; 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)
<td>Returns a reference to the singleton instance</td>
</tr>
</table>
<P>
This file can be redistributed and/or modified under the terms found in <A HREF="../copyright.html">copyright.html</A>
<h2>Guarantees</h2>
<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.
<p>The singleton instance is guaranteed to be constructed before
<span class="code">main()</span> begins, and destructed after <span class=
"code">main()</span> ends. Furthermore, it is guaranteed to be constructed
before the first call to <span class=
"code">singleton_default&lt;T&gt;::instance()</span> is complete (even if
called before <span class="code">main()</span> begins). Thus, if there are
not multiple threads running except within <span class=
"code">main()</span>, and if all access to the singleton is restricted by
mutexes, then this guarantee allows a thread-safe singleton.</p>
</BODY>
</HTML>
<h2>Details</h2>
<p>For details on how we provide the guarantees above, see the comments in
the header file.</p>
<h2>Dependencies</h2>
<p>None.</p>
<h2>Future Directions</h2>
<p>This header may be replaced by a Boost singleton library.</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 &copy; 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>

116
doc/implementation/singleton_pool.html
View File

@@ -1,25 +1,33 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<TITLE>Singleton Pool Implementation</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>Singleton Pool Implementation</H1>
<title>Singleton Pool Implementation</title>
</head>
<P>
<H2>Dependencies</H2>
<body>
<img src="../../../../boost.png" width="276" height="86" alt="C++ Boost">
<P>
Includes the Boost headers <SPAN CLASS="code">&quot;pool.hpp&quot;</SPAN> (see <A HREF="pool.html">pool.html</A>), <SPAN CLASS="code">&quot;detail/singleton.hpp&quot;</SPAN> (see <A HREF="singleton.html">singleton.html</A>), <SPAN CLASS="code">&quot;detail/mutex.hpp&quot;</SPAN> (see <A HREF="mutex.html">mutex.html</A>), and <SPAN CLASS="code">&quot;detail/guard.hpp&quot;</SPAN> (see <A HREF="guard.html">guard.html</A>).
<h1 align="center">Singleton Pool Implementation</h1>
<P>
<H2>Synopsis</H2>
<h2>Dependencies</h2>
<PRE CLASS="code">template &lt;typename Tag,
<p>Includes the Boost headers <span class="code">"pool.hpp"</span> (see
<a href="pool.html">pool.html</a>), <span class=
"code">"detail/singleton.hpp"</span> (see <a href=
"singleton.html">singleton.html</a>), <span class=
"code">"detail/mutex.hpp"</span> (see <a href="mutex.html">mutex.html</a>),
and <span class="code">"detail/guard.hpp"</span> (see <a href=
"guard.html">guard.html</a>).</p>
<h2>Synopsis</h2>
<pre class="code">
template &lt;typename Tag,
unsigned RequestedSize,
typename UserAllocator = default_user_allocator_new_delete,
typename Mutex = details::pool::default_mutex,
@@ -31,52 +39,60 @@ class singleton_pool
public: // extensions to public interface
typedef Mutex mutex;
static const unsigned next_size = NextSize;
};</PRE>
};
</pre>
<P>
<H2>Extensions to Public Interface</H2>
<h2>Extensions to Public Interface</h2>
<P>
<H3>Additional template parameters</H3>
<h3>Additional template parameters</h3>
<P>
<H4 CLASS="code">Mutex</H4>
<h4 class="code">Mutex</h4>
<P>
This class is the type of <A HREF="mutex.html">mutex</A> to use to protect simultaneous access to the underlying Pool. It is exposed so that users may declare some singleton pools normally (i.e., with synchronization), but some singleton pools without synchronization (by specifying <SPAN CLASS="code">details::pool::null_mutex</SPAN>) for efficiency reasons.
<p>This class is the type of <a href="mutex.html">mutex</a> to use to
protect simultaneous access to the underlying Pool. It is exposed so that
users may declare some singleton pools normally (i.e., with
synchronization), but some singleton pools without synchronization (by
specifying <span class="code">details::pool::null_mutex</span>) for
efficiency reasons.</p>
<P>
<H4 CLASS="code">NextSize</H4>
<h4 class="code">NextSize</h4>
<P>
The value of this parameter is passed to the underlying Pool when it is created. See the extensions to the public interface of <A HREF="pool.html">pool</A> for more information.
<p>The value of this parameter is passed to the underlying Pool when it is
created. See the extensions to the public interface of <a href=
"pool.html">pool</a> for more information.</p>
<P>
<H3>Additional members</H3>
<h3>Additional members</h3>
<P>
The typedef <SPAN CLASS="code">mutex</SPAN> and the static const value <SPAN CLASS="code">next_size</SPAN> publish the values of the template parameters <SPAN CLASS="code">Mutex</SPAN> and <SPAN CLASS="code">NextSize</SPAN>, respectively.
<p>The typedef <span class="code">mutex</span> and the static const value
<span class="code">next_size</span> publish the values of the template
parameters <span class="code">Mutex</span> and <span class=
"code">NextSize</span>, respectively.</p>
<P>
<H2>Future Directions</H2>
<h2>Future Directions</h2>
<P>
When the Boost multithreading library is completed, the <SPAN CLASS="code">Mutex</SPAN> parameter will be replaced by something from that library providing the same flexibility and will move from an implementation detail into the interface specification.
<p>When the Boost multithreading library is completed, the <span class=
"code">Mutex</span> parameter will be replaced by something from that
library providing the same flexibility and will move from an implementation
detail into the interface specification.</p>
<P>
<H2><A HREF="../interfaces/singleton_pool.html">Interface Description</A></H2>
<h2><a href="../interfaces/singleton_pool.html">Interface
Description</a></h2>
<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>

313
doc/index.html
View File

@@ -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 &quot;simple segregated storage&quot;), 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
&quot;simple segregated storage&quot;), 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">&lt;boost/pool/poolfwd.hpp&gt;</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">&lt;boost/pool/poolfwd.hpp&gt;</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 &quot;build&quot; 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 &quot;readme.txt&quot; in the proper subdirectory, if it exists.
<h2>Building the Test Programs</h2>
<P>
The standard makefile targets are &quot;all&quot;, &quot;clean&quot; (which deletes any intermediate files), and &quot;veryclean&quot; (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, &quot;clean&quot; and &quot;veryclean&quot; shell scripts/batch files will be provided.
<p>The subdirectory &quot;build&quot; 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 &quot;readme.txt&quot; in the proper subdirectory, if it exists.</p>
<P>
<H2>Documentation Map</H2>
<p>The standard makefile targets are &quot;all&quot;, &quot;clean&quot; (which deletes any
intermediate files), and &quot;veryclean&quot; (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, &quot;clean&quot; and &quot;veryclean&quot; 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 &copy; 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 &quot;as is&quot; 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>
<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 &copy; 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>

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>

323
doc/interfaces/object_pool.html
View File

@@ -1,25 +1,30 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<TITLE>object_pool - Boost Object Pool Allocator</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>object_pool - Boost Object Pool Allocator</H1>
<title>object_pool - Boost Object Pool Allocator</title>
</head>
<P>
<H2>Introduction</H2>
<body>
<img src="../../../../boost.png" width="276" height="86" alt="C++ Boost">
<P>
object_pool.hpp provides a template type that can be used for fast and efficient memory allocation. It also provides automatic destruction of non-deallocated objects. For information on other pool-based interfaces, see <A HREF="../interfaces.html">the other pool interfaces</A>.
<h1 align="center">object_pool - Boost Object Pool Allocator</h1>
<P>
<H2>Synopsis</H2>
<h2>Introduction</h2>
<PRE CLASS="code">template &lt;typename ElementType, typename UserAllocator = default_user_allocator_new_delete&gt;
<p>object_pool.hpp provides a template type that can be used for fast and
efficient memory allocation. It also provides automatic destruction of
non-deallocated objects. For information on other pool-based interfaces, see <a href="../interfaces.html">
the other pool interfaces</a>.</p>
<h2>Synopsis</h2>
<pre class="code">
template &lt;typename ElementType, typename UserAllocator = default_user_allocator_new_delete&gt;
class object_pool
{
private:
@@ -42,87 +47,241 @@ class object_pool
element_type * construct();
// other construct() functions
void destroy(element_type * p);
};</PRE>
};
</pre>
<P>
<H2>Template Parameters</H2>
<h2>Template Parameters</h2>
<P>
<H3>ElementType</H3>
<h3>ElementType</h3>
<P>
The template parameter is the type of object to allocate/deallocate. It must have a non-throwing destructor.
<p>The template parameter is the type of object to allocate/deallocate. It
must have a non-throwing destructor.</p>
<P>
<H3>UserAllocator</H3>
<h3>UserAllocator</h3>
<P>
Defines the method that the underlying Pool will use to allocate memory from the system. See <A HREF="user_allocator.html">User Allocators</A> for details.
<p>Defines the method that the underlying Pool will use to allocate memory
from the system. See <a href="user_allocator.html">User Allocators</a> for
details.</p>
<P>
<H2>Semantics</H2>
<h2>Semantics</h2>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Symbol Table</EM></CAPTION>
<TR><TH>Symbol<TH>Meaning
<TR><TD CLASS="code">ObjectPool<TD><SPAN CLASS="code">object_pool&lt;ElementType, UserAllocator&gt;</SPAN>
<TR><TD CLASS="code">t<TD>value of type <SPAN CLASS="code">ObjectPool</SPAN>
<TR><TD CLASS="code">u<TD>value of type <SPAN CLASS="code">const ObjectPool</SPAN>
<TR><TD CLASS="code">p<TD>value of type <SPAN CLASS="code">ElementType *</SPAN>
</TABLE>
<table border align="center" summary="">
<caption>
<em>Symbol Table</em>
</caption>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Typedefs</EM></CAPTION>
<TR><TH>Expression<TH>Type
<TR><TD CLASS="code">ObjectPool::element_type<TD CLASS="code">ElementType
<TR><TD CLASS="code">ObjectPool::user_allocator<TD CLASS="code">UserAllocator
<TR><TD CLASS="code">ObjectPool::size_type<TD CLASS="code">pool&lt;UserAllocator&gt;::size_type
<TR><TD CLASS="code">ObjectPool::difference_type<TD CLASS="code">pool&lt;UserAllocator&gt;::difference_type
</TABLE>
<tr>
<th>Symbol</th>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Constructors, Destructors, and Testing</EM></CAPTION>
<TR><TH>Expression<TH>Return Type<TH>Notes
<TR><TD CLASS="code">ObjectPool()<TD>not used<TD>Constructs a new empty <SPAN CLASS="code">ObjectPool</SPAN>
<TR><TD CLASS="code">(&amp;t)->~ObjectPool()<TD>not used<TD>Destructs the <SPAN CLASS="code">ObjectPool</SPAN>; <SPAN CLASS="code">~ElementType()</SPAN> is called for each allocated ElementType that has not been deallocated. O(N).
<TR><TD CLASS="code">u.is_from(p)<TD CLASS="code">bool<TD>Returns <SPAN CLASS="code">true</SPAN> if <SPAN CLASS="code">p</SPAN> was allocated from <SPAN CLASS="code">u</SPAN> or may be returned as the result of a future allocation from <SPAN CLASS="code">u</SPAN>. Returns <SPAN CLASS="code">false</SPAN> if <SPAN CLASS="code">p</SPAN> was allocated from some other pool or may be returned as the result of a future allocation from some other pool. Otherwise, the return value is meaningless; note that this function may <STRONG>not</STRONG> be used to reliably test random pointer values.
</TABLE>
<th>Meaning</th>
</tr>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Allocation and Deallocation</EM></CAPTION>
<TR><TH>Expression<TH>Return Type<TH>Pre-Condition<TH>Semantic Equivalence<TH>Notes
<TR><TD CLASS="code">t.malloc()<TD CLASS="code">ElementType *<TD><TD><TD>Allocates memory that can hold an object of type <SPAN CLASS="code">ElementType</SPAN>. If out of memory, returns <SPAN CLASS="code">0</SPAN>. Amortized O(1).
<TR><TD CLASS="code">t.free(p)<TD>not used<TD><SPAN CLASS="code">p</SPAN> must have been previously allocated from <SPAN CLASS="code">t</SPAN><TD><TD>Deallocates a chunk of memory. Note that <SPAN CLASS="code">p</SPAN> may not be <SPAN CLASS="code">0</SPAN>. Note that the destructor for <SPAN CLASS="code">p</SPAN> is not called. O(N).
<TR><TD CLASS="code">t.construct(???)<TD CLASS="code">ElementType *<TD><SPAN CLASS="code">ElementType</SPAN> must have a constructor matching <SPAN CLASS="code">???</SPAN>; the number of parameters given must not exceed what is supported through <A HREF="../implementation/pool_construct.html">pool_construct</A><TD><TD>Allocates and initializes an object of type <SPAN CLASS="code">ElementType</SPAN>. If out of memory, returns <SPAN CLASS="code">0</SPAN>. Amortized O(1).
<TR><TD CLASS="code">t.destroy(p)<TD>not used<TD><SPAN CLASS="code">p</SPAN> must have been previously allocated from <SPAN CLASS="code">t</SPAN><TD CLASS="code">p->~ElementType(); t.free(p);<TD>
</TABLE>
<tr>
<td class="code">ObjectPool</td>
<P>
<H2>Symbols</H2>
<td><span class="code">object_pool&lt;ElementType, UserAllocator&gt;</span></td>
</tr>
<P>
<UL>
<LI>boost::object_pool</LI>
</UL>
<tr>
<td class="code">t</td>
<P>
<H2><A HREF="../implementation/object_pool.html">Implementation Details</A></H2>
<td>value of type <span class="code">ObjectPool</span></td>
</tr>
<P>
<HR>
<tr>
<td class="code">u</td>
<P>
Copyright &copy; 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)
<td>value of type <span class="code">const ObjectPool</span></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 class="code">p</td>
<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.
<td>value of type <span class="code">ElementType *</span></td>
</tr>
</table><br>
</BODY>
</HTML>
<table border align="center" summary="">
<caption>
<em>Typedefs</em>
</caption>
<tr>
<th>Expression</th>
<th>Type</th>
</tr>
<tr>
<td class="code">ObjectPool::element_type</td>
<td class="code">ElementType</td>
</tr>
<tr>
<td class="code">ObjectPool::user_allocator</td>
<td class="code">UserAllocator</td>
</tr>
<tr>
<td class="code">ObjectPool::size_type</td>
<td class="code">pool&lt;UserAllocator&gt;::size_type</td>
</tr>
<tr>
<td class="code">ObjectPool::difference_type</td>
<td class="code">pool&lt;UserAllocator&gt;::difference_type</td>
</tr>
</table><br>
<table border align="center" summary="">
<caption>
<em>Constructors, Destructors, and Testing</em>
</caption>
<tr>
<th>Expression</th>
<th>Return Type</th>
<th>Notes</th>
</tr>
<tr>
<td class="code">ObjectPool()</td>
<td>not used</td>
<td>Constructs a new empty <span class="code">ObjectPool</span></td>
</tr>
<tr>
<td class="code">(&amp;t)-&gt;~ObjectPool()</td>
<td>not used</td>
<td>Destructs the <span class="code">ObjectPool</span>; <span class=
"code">~ElementType()</span> is called for each allocated ElementType
that has not been deallocated. O(N).</td>
</tr>
<tr>
<td class="code">u.is_from(p)</td>
<td class="code">bool</td>
<td>Returns <span class="code">true</span> if <span class=
"code">p</span> was allocated from <span class="code">u</span> or may be
returned as the result of a future allocation from <span class=
"code">u</span>. Returns <span class="code">false</span> if
<span class="code">p</span> was allocated from some other pool or may be
returned as the result of a future allocation from some other pool.
Otherwise, the return value is meaningless; note that this function may
<strong>not</strong> be used to reliably test random pointer values.</td>
</tr>
</table><br>
<table border align="center" summary="">
<caption>
<em>Allocation and Deallocation</em>
</caption>
<tr>
<th>Expression</th>
<th>Return Type</th>
<th>Pre-Condition</th>
<th>Semantic Equivalence</th>
<th>Notes</th>
</tr>
<tr>
<td class="code">t.malloc()</td>
<td class="code">ElementType *</td>
<td></td>
<td></td>
<td>Allocates memory that can hold an object of type <span class=
"code">ElementType</span>. If out of memory, returns <span class=
"code">0</span>. Amortized O(1).</td>
</tr>
<tr>
<td class="code">t.free(p)</td>
<td>not used</td>
<td><span class="code">p</span> must have been previously allocated from <span class="code">
t</span></td>
<td></td>
<td>Deallocates a chunk of memory. Note that <span class=
"code">p</span> may not be <span class="code">0</span>. Note that the
destructor for <span class="code">p</span> is not called. O(N).</td>
</tr>
<tr>
<td class="code">t.construct(???)</td>
<td class="code">ElementType *</td>
<td><span class="code">ElementType</span> must have a constructor
matching <span class="code">???</span>; the number of parameters given
must not exceed what is supported through <a href=
"../implementation/pool_construct.html">pool_construct</a></td>
<td></td>
<td>Allocates and initializes an object of type <span class=
"code">ElementType</span>. If out of memory, returns <span class=
"code">0</span>. Amortized O(1).</td>
</tr>
<tr>
<td class="code">t.destroy(p)</td>
<td>not used</td>
<td><span class="code">p</span> must have been previously allocated from <span class="code">
t</span></td>
<td class="code">p-&gt;~ElementType(); t.free(p);</td>
<td></td>
</tr>
</table>
<h2>Symbols</h2>
<ul>
<li>boost::object_pool</li>
</ul>
<h2><a href="../implementation/object_pool.html">Implementation Details</a></h2>
<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 &copy; 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>

416
doc/interfaces/pool.html
View File

@@ -1,29 +1,38 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<TITLE>Pool</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</H1>
<title>Pool</title>
</head>
<P>
<H2>Introduction</H2>
<body>
<img src="../../../../boost.png" width="276" height="86" alt="C++ Boost">
<P>
<SPAN CLASS="code">pool</SPAN> is a fast memory allocator, and guarantees proper alignment of all allocated chunks.
<h1 align="center">Pool</h1>
<P>
pool.hpp provides two <A HREF="user_allocator.html">UserAllocator</A> classes and a template class <SPAN CLASS="code">pool</SPAN>, which extends and generalizes the framework provided by the <A HREF="simple_segregated_storage.html">simple segregated storage</A> solution. For information on other pool-based interfaces, see <A HREF="../interfaces.html">the other pool interfaces</A>.
<h2>Introduction</h2>
<P>
<H2>Synopsis</H2>
<p><span class="code">pool</span> is a fast memory allocator, and
guarantees proper alignment of all allocated chunks.</p>
<PRE CLASS="code">struct default_user_allocator_new_delete; // see <A HREF="user_allocator.html">User Allocators</A>
struct default_user_allocator_malloc_free; // see <A HREF="user_allocator.html">User Allocators</A>
<p>pool.hpp provides two <a href="user_allocator.html">UserAllocator</a>
classes and a template class <span class="code">pool</span>, which extends
and generalizes the framework provided by the <a href=
"simple_segregated_storage.html">simple segregated storage</a> solution.
For information on other pool-based interfaces, see <a href=
"../interfaces.html">the other pool interfaces</a>.</p>
<h2>Synopsis</h2>
<pre class="code">
struct default_user_allocator_new_delete; // see <a href=
"user_allocator.html">User Allocators</a>
struct default_user_allocator_malloc_free; // see <a href=
"user_allocator.html">User Allocators</a>
template &lt;typename UserAllocator = default_user_allocator_new_delete&gt;
class pool
@@ -54,90 +63,317 @@ class pool
void ordered_free(void * chunk);
void free(void * chunks, size_type n);
void ordered_free(void * chunks, size_type n);
};</PRE>
};
</pre>
<P>
<H2>Template Parameters</H2>
<h2>Template Parameters</h2>
<P>
<H3>UserAllocator</H3>
<h3>UserAllocator</h3>
<P>
Defines the method that the Pool will use to allocate memory from the system. See <A HREF="user_allocator.html">User Allocators</A> for details.
<p>Defines the method that the Pool will use to allocate memory from the
system. See <a href="user_allocator.html">User Allocators</a> for
details.</p>
<P>
<H2>Semantics</H2>
<h2>Semantics</h2>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Symbol Table</EM></CAPTION>
<TR><TH>Symbol<TH>Meaning
<TR><TD CLASS="code">Pool<TD CLASS="code">pool&lt;UserAllocator&gt;
<TR><TD CLASS="code">t<TD>value of type <SPAN CLASS="code">Pool</SPAN>
<TR><TD CLASS="code">u<TD>value of type <SPAN CLASS="code">const Pool</SPAN>
<TR><TD CLASS="code">chunk<TD>value of type <SPAN CLASS="code">void *</SPAN>
<TR><TD CLASS="code">n<TD>value of type <SPAN CLASS="code">size_type</SPAN>
<TR><TD CLASS="code">RequestedSize<TD>value of type <SPAN CLASS="code">Pool::size_type</SPAN>; must be greater than 0
</TABLE>
<table border align="center" summary="">
<caption>
<em>Symbol Table</em>
</caption>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Typedefs</EM></CAPTION>
<TR><TH>Expression<TH>Type
<TR><TD CLASS="code">Pool::user_allocator<TD CLASS="code">UserAllocator
<TR><TD CLASS="code">Pool::size_type<TD CLASS="code">UserAllocator::size_type
<TR><TD CLASS="code">Pool::difference_type<TD CLASS="code">UserAllocator::difference_type
</TABLE>
<tr>
<th>Symbol</th>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Constructors, Destructors, and Testing</EM></CAPTION>
<TR><TH>Expression<TH>Return Type<TH>Notes
<TR><TD CLASS="code">Pool(RequestedSize)<TD>not used<TD>Constructs a new empty <SPAN CLASS="code">Pool</SPAN> that can be used to allocate chunks of size <SPAN CLASS="code">RequestedSize</SPAN>
<TR><TD CLASS="code">(&amp;t)->~Pool()<TD>not used<TD>Destructs the <SPAN CLASS="code">Pool</SPAN>, freeing its list of memory blocks
<TR><TD CLASS="code">u.is_from(chunk)<TD CLASS="code">bool<TD>Returns <SPAN CLASS="code">true</SPAN> if <SPAN CLASS="code">chunk</SPAN> was allocated from <SPAN CLASS="code">u</SPAN> or may be returned as the result of a future allocation from <SPAN CLASS="code">u</SPAN>. Returns <SPAN CLASS="code">false</SPAN> if <SPAN CLASS="code">chunk</SPAN> was allocated from some other pool or may be returned as the result of a future allocation from some other pool. Otherwise, the return value is meaningless; note that this function may <STRONG>not</STRONG> be used to reliably test random pointer values.
<TR><TD CLASS="code">u.get_requested_size()<TD CLASS="code">size_type<TD>Returns the value passed into the constructor. This value will not change during the lifetime of a <SPAN CLASS="code">Pool</SPAN> object.
</TABLE>
<th>Meaning</th>
</tr>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Allocation and Deallocation</EM></CAPTION>
<TR><TH>Expression<TH>Return Type<TH>Pre-Condition<TH>Notes
<TR><TD CLASS="code">t.malloc()<TD CLASS="code">void *<TD><TD>Allocates a chunk of memory. Searches in the list of memory blocks for a block that has a free chunk, and returns that free chunk if found. Otherwise, creates a new memory block, adds its free list to <SPAN CLASS="code">t</SPAN>'s free list, and returns a free chunk from that block. If a new memory block cannot be allocated, returns <SPAN CLASS="code">0</SPAN>. Amortized O(1).
<TR><TD CLASS="code">t.ordered_malloc()<TD CLASS="code">void *<TD><TD>Same as above, only merges the free lists, to preserve order. Amortized O(1).
<TR><TD CLASS="code">t.ordered_malloc(n)<TD CLASS="code">void *<TD><TD>Same as above, only allocates enough contiguous chunks to cover <SPAN CLASS="code">n * requested_size</SPAN> bytes. Amortized O(n).
<TR><TD CLASS="code">t.free(chunk)<TD CLASS="code">void<TD><SPAN CLASS="code">chunk</SPAN> must have been previously returned by <SPAN CLASS="code">t.malloc()</SPAN> or <SPAN CLASS="code">t.ordered_malloc()</SPAN>.<TD>Deallocates a chunk of memory. Note that <SPAN CLASS="code">chunk</SPAN> may not be <SPAN CLASS="code">0</SPAN>. O(1).
<TR><TD CLASS="code">t.ordered_free(chunk)<TD CLASS="code">void<TD>Same as above<TD>Same as above, but is order-preserving. Note that <SPAN CLASS="code">chunk</SPAN> may not be <SPAN CLASS="code">0</SPAN>. O(N) with respect to the size of the free list
<TR><TD CLASS="code">t.free(chunk, n)<TD CLASS="code">void<TD><SPAN CLASS="code">chunk</SPAN> must have been previously returned by <SPAN CLASS="code">t.ordered_malloc(n)</SPAN>.<TD>Assumes that <SPAN CLASS="code">chunk</SPAN> actually refers to a block of chunks spanning <SPAN CLASS="code">n * partition_sz</SPAN> bytes; deallocates each chunk in that block. Note that <SPAN CLASS="code">chunk</SPAN> may not be <SPAN CLASS="code">0</SPAN>. O(n).
<TR><TD CLASS="code">t.ordered_free(chunk, n)<TD CLASS="code">void<TD><SPAN CLASS="code">chunk</SPAN> must have been previously returned by <SPAN CLASS="code">t.ordered_malloc(n)</SPAN>.<TD>Assumes that <SPAN CLASS="code">chunk</SPAN> actually refers to a block of chunks spanning <SPAN CLASS="code">n * partition_sz</SPAN> bytes; deallocates each chunk in that block. Note that <SPAN CLASS="code">chunk</SPAN> may not be <SPAN CLASS="code">0</SPAN>. Order-preserving. O(N + n) where N is the size of the free list.
<TR><TD CLASS="code">t.release_memory()<TD CLASS="code">bool<TD><SPAN CLASS="code">t</SPAN> must be ordered.<TD>Frees every memory block that doesn't have any allocated chunks. Returns <SPAN CLASS="code">true</SPAN> if at least one memory block was freed.
<TR><TD CLASS="code">t.purge_memory()<TD CLASS="code">bool<TD><TD>Frees every memory block. This function invalidates any pointers previously returned by allocation functions of <SPAN CLASS="code">t</SPAN>. Returns <SPAN CLASS="code">true</SPAN> if at least one memory block was freed.
</TABLE>
<tr>
<td class="code">Pool</td>
<P>
<H2>Symbols</H2>
<td class="code">pool&lt;UserAllocator&gt;</td>
</tr>
<P>
<UL>
<LI>boost::default_user_allocator_new_delete</LI>
<LI>boost::default_user_allocator_malloc_new</LI>
<LI>boost::pool</LI>
</UL>
<tr>
<td class="code">t</td>
<P>
<H2><A HREF="../implementation/pool.html">Implementation Details</A></H2>
<td>value of type <span class="code">Pool</span></td>
</tr>
<P>
<HR>
<tr>
<td class="code">u</td>
<P>
Copyright &copy; 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)
<td>value of type <span class="code">const Pool</span></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 class="code">chunk</td>
<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.
<td>value of type <span class="code">void *</span></td>
</tr>
</BODY>
</HTML>
<tr>
<td class="code">n</td>
<td>value of type <span class="code">size_type</span></td>
</tr>
<tr>
<td class="code">RequestedSize</td>
<td>value of type <span class="code">Pool::size_type</span>; must be
greater than 0</td>
</tr>
</table><br>
<table border align="center" summary="">
<caption>
<em>Typedefs</em>
</caption>
<tr>
<th>Expression</th>
<th>Type</th>
</tr>
<tr>
<td class="code">Pool::user_allocator</td>
<td class="code">UserAllocator</td>
</tr>
<tr>
<td class="code">Pool::size_type</td>
<td class="code">UserAllocator::size_type</td>
</tr>
<tr>
<td class="code">Pool::difference_type</td>
<td class="code">UserAllocator::difference_type</td>
</tr>
</table><br>
<table border align="center" summary="">
<caption>
<em>Constructors, Destructors, and Testing</em>
</caption>
<tr>
<th>Expression</th>
<th>Return Type</th>
<th>Notes</th>
</tr>
<tr>
<td class="code">Pool(RequestedSize)</td>
<td>not used</td>
<td>Constructs a new empty <span class="code">Pool</span> that can be
used to allocate chunks of size <span class=
"code">RequestedSize</span></td>
</tr>
<tr>
<td class="code">(&amp;t)-&gt;~Pool()</td>
<td>not used</td>
<td>Destructs the <span class="code">Pool</span>, freeing its list of
memory blocks</td>
</tr>
<tr>
<td class="code">u.is_from(chunk)</td>
<td class="code">bool</td>
<td>Returns <span class="code">true</span> if <span class=
"code">chunk</span> was allocated from <span class="code">u</span> or
may be returned as the result of a future allocation from <span class=
"code">u</span>. Returns <span class="code">false</span> if
<span class="code">chunk</span> was allocated from some other pool or
may be returned as the result of a future allocation from some other
pool. Otherwise, the return value is meaningless; note that this
function may <strong>not</strong> be used to reliably test random
pointer values.</td>
</tr>
<tr>
<td class="code">u.get_requested_size()</td>
<td class="code">size_type</td>
<td>Returns the value passed into the constructor. This value will not
change during the lifetime of a <span class="code">Pool</span>
object.</td>
</tr>
</table><br>
<table border align="center" summary="">
<caption>
<em>Allocation and Deallocation</em>
</caption>
<tr>
<th>Expression</th>
<th>Return Type</th>
<th>Pre-Condition</th>
<th>Notes</th>
</tr>
<tr>
<td class="code">t.malloc()</td>
<td class="code">void *</td>
<td></td>
<td>Allocates a chunk of memory. Searches in the list of memory blocks
for a block that has a free chunk, and returns that free chunk if
found. Otherwise, creates a new memory block, adds its free list to
<span class="code">t</span>'s free list, and returns a free chunk from
that block. If a new memory block cannot be allocated, returns
<span class="code">0</span>. Amortized O(1).</td>
</tr>
<tr>
<td class="code">t.ordered_malloc()</td>
<td class="code">void *</td>
<td></td>
<td>Same as above, only merges the free lists, to preserve order.
Amortized O(1).</td>
</tr>
<tr>
<td class="code">t.ordered_malloc(n)</td>
<td class="code">void *</td>
<td></td>
<td>Same as above, only allocates enough contiguous chunks to cover
<span class="code">n * requested_size</span> bytes. Amortized
O(n).</td>
</tr>
<tr>
<td class="code">t.free(chunk)</td>
<td class="code">void</td>
<td><span class="code">chunk</span> must have been previously returned
by <span class="code">t.malloc()</span> or <span class=
"code">t.ordered_malloc()</span>.</td>
<td>Deallocates a chunk of memory. Note that <span class=
"code">chunk</span> may not be <span class="code">0</span>. O(1).</td>
</tr>
<tr>
<td class="code">t.ordered_free(chunk)</td>
<td class="code">void</td>
<td>Same as above</td>
<td>Same as above, but is order-preserving. Note that <span class=
"code">chunk</span> may not be <span class="code">0</span>. O(N) with
respect to the size of the free list</td>
</tr>
<tr>
<td class="code">t.free(chunk, n)</td>
<td class="code">void</td>
<td><span class="code">chunk</span> must have been previously returned
by <span class="code">t.ordered_malloc(n)</span>.</td>
<td>Assumes that <span class="code">chunk</span> actually refers to a
block of chunks spanning <span class="code">n * partition_sz</span>
bytes; deallocates each chunk in that block. Note that <span class=
"code">chunk</span> may not be <span class="code">0</span>. O(n).</td>
</tr>
<tr>
<td class="code">t.ordered_free(chunk, n)</td>
<td class="code">void</td>
<td><span class="code">chunk</span> must have been previously returned
by <span class="code">t.ordered_malloc(n)</span>.</td>
<td>Assumes that <span class="code">chunk</span> actually refers to a
block of chunks spanning <span class="code">n * partition_sz</span>
bytes; deallocates each chunk in that block. Note that <span class=
"code">chunk</span> may not be <span class="code">0</span>.
Order-preserving. O(N + n) where N is the size of the free list.</td>
</tr>
<tr>
<td class="code">t.release_memory()</td>
<td class="code">bool</td>
<td><span class="code">t</span> must be ordered.</td>
<td>Frees every memory block that doesn't have any allocated chunks.
Returns <span class="code">true</span> if at least one memory block was
freed.</td>
</tr>
<tr>
<td class="code">t.purge_memory()</td>
<td class="code">bool</td>
<td></td>
<td>Frees every memory block. This function invalidates any pointers
previously returned by allocation functions of <span class=
"code">t</span>. Returns <span class="code">true</span> if at least one
memory block was freed.</td>
</tr>
</table>
<h2>Symbols</h2>
<ul>
<li>boost::default_user_allocator_new_delete</li>
<li>boost::default_user_allocator_malloc_new</li>
<li>boost::pool</li>
</ul>
<h2><a href="../implementation/pool.html">Implementation Details</a></h2>
<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 &copy; 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>

244
doc/interfaces/pool_alloc.html
View File

@@ -1,25 +1,32 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<TITLE>pool_alloc - Boost Pool Standard Allocators</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_alloc - Boost Pool Standard Allocators</H1>
<title>pool_alloc - Boost Pool Standard Allocators</title>
</head>
<P>
<H2>Introduction</H2>
<body>
<img src="../../../../boost.png" width="276" height="86" alt="C++ Boost">
<P>
pool_alloc.hpp provides two template types that can be used for fast and efficient memory allocation. These types both satisfy the Standard Allocator requirements [20.1.5] and the additional requirements in [20.1.5/4], so they can be used with Standard or user-supplied containers. For information on other pool-based interfaces, see <A HREF="../interfaces.html">the other pool interfaces</A>.
<h1 align="center">pool_alloc - Boost Pool Standard Allocators</h1>
<P>
<H2>Synopsis</H2>
<h2>Introduction</h2>
<PRE CLASS="code">struct pool_allocator_tag { };
<p>pool_alloc.hpp provides two template types that can be used for fast and
efficient memory allocation. These types both satisfy the Standard
Allocator requirements [20.1.5] and the additional requirements in
[20.1.5/4], so they can be used with Standard or user-supplied containers.
For information on other pool-based interfaces, see <a href=
"../interfaces.html">the other pool interfaces</a>.</p>
<h2>Synopsis</h2>
<pre class="code">
struct pool_allocator_tag { };
template &lt;typename T,
typename UserAllocator = default_user_allocator_new_delete&gt;
@@ -106,97 +113,166 @@ class fast_pool_allocator
static pointer allocate();
static void deallocate(pointer ptr);
};</PRE>
};
</pre>
<P>
<H2>Template Parameters</H2>
<h2>Template Parameters</h2>
<P>
<H3>T</H3>
<h3>T</h3>
<P>
The first template parameter is the type of object to allocate/deallocate.
<p>The first template parameter is the type of object to
allocate/deallocate.</p>
<P>
<H3>UserAllocator</H3>
<h3>UserAllocator</h3>
<P>
Defines the method that the underlying Pool will use to allocate memory from the system. See <A HREF="user_allocator.html">User Allocators</A> for details.
<p>Defines the method that the underlying Pool will use to allocate memory
from the system. See <a href="user_allocator.html">User Allocators</a> for
details.</p>
<P>
<H2>Semantics</H2>
<h2>Semantics</h2>
<P>
Both of the pool allocators above satisfy all Standard Allocator requirements, as laid out in the Standard [20.1.5]. They also both satisfy the additional requirements found in [20.1.5/4]; this permits their usage with any Standard-compliant container.
<p>Both of the pool allocators above satisfy all Standard Allocator
requirements, as laid out in the Standard [20.1.5]. They also both satisfy
the additional requirements found in [20.1.5/4]; this permits their usage
with any Standard-compliant container.</p>
<P>
In addition, the <SPAN CLASS="code">fast_pool_allocator</SPAN> also provides an additional allocation and an additional deallocation function:
<p>In addition, the <span class="code">fast_pool_allocator</span> also
provides an additional allocation and an additional deallocation
function:</p>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Symbol Table</EM></CAPTION>
<TR><TH>Symbol<TH>Meaning
<TR><TD CLASS="code">PoolAlloc<TD><SPAN CLASS="code">fast_pool_allocator&lt;T, UserAllocator&gt;</SPAN>
<TR><TD CLASS="code">p<TD>value of type <SPAN CLASS="code">T *</SPAN>
</TABLE>
<table border align="center" summary="">
<caption>
<em>Symbol Table</em>
</caption>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Additional allocation/deallocation functions (<SPAN CLASS="code">fast_pool_allocator</SPAN> only)</EM></CAPTION>
<TR><TH>Expression<TH>Return Type<TH>Semantic Equivalence
<TR><TD CLASS="code">PoolAlloc::allocate()<TD CLASS="code">T *<TD CLASS="code">PoolAlloc::allocate(1)
<TR><TD CLASS="code">PoolAlloc::deallocate(p)<TD>void<TD CLASS="code">PoolAlloc::deallocate(p, 1)
</TABLE>
<tr>
<th>Symbol</th>
<P>
The typedef <SPAN CLASS="code">user_allocator</SPAN> publishes the value of the <SPAN CLASS="code">UserAllocator</SPAN> template parameter.
<th>Meaning</th>
</tr>
<P>
<H2>Notes</H2>
<tr>
<td class="code">PoolAlloc</td>
<P>
If the allocation functions run out of memory, they will throw <SPAN CLASS="code">std::bad_alloc</SPAN>.
<td><span class="code">fast_pool_allocator&lt;T,
UserAllocator&gt;</span></td>
</tr>
<P>
The underlying Pool type used by the allocators is accessible through the <A HREF="singleton_pool.html">Singleton Pool Interface</A>. The identifying tag used for <SPAN CLASS="code">pool_allocator</SPAN> is <SPAN CLASS="code">pool_allocator_tag</SPAN>, and the tag used for <SPAN CLASS="code">fast_pool_allocator</SPAN> is <SPAN CLASS="code">fast_pool_allocator_tag</SPAN>. All template parameters of the allocators (including <A HREF="../implementation/pool_alloc.html">implementation-specific ones</A>) determine the type of the underlying Pool, with the exception of the first parameter <SPAN CLASS="code">T</SPAN>, whose size is used instead.
<tr>
<td class="code">p</td>
<P>
Since the size of <SPAN CLASS="code">T</SPAN> is used to determine the type of the underlying Pool, each allocator for different types of the same size <EM>will share</EM> the same underlying pool. The tag class prevents pools from being shared between <SPAN CLASS="code">pool_allocator</SPAN> and <SPAN CLASS="code">fast_pool_allocator</SPAN>. For example, on a system where sizeof(int) == sizeof(void *), <SPAN CLASS="code">pool_allocator&lt;int&gt;</SPAN> and <SPAN CLASS="code">pool_allocator&lt;void *&gt;</SPAN> will both allocate/deallocate from/to the same pool.
<td>value of type <span class="code">T *</span></td>
</tr>
</table><br>
<P>
If there is only one thread running before <SPAN CLASS="code">main()</SPAN> starts and after <SPAN CLASS="code">main()</SPAN> ends, then both allocators are completely thread-safe.
<table border align="center" summary="">
<caption>
<em>Additional allocation/deallocation functions (<span class=
"code">fast_pool_allocator</span> only)</em>
</caption>
<P>
<H2>The Fast Pool Allocator</H2>
<tr>
<th>Expression</th>
<P>
<SPAN CLASS="code">pool_allocator</SPAN> is a more general-purpose solution, geared towards efficiently servicing requests for any number of contiguous chunks. <SPAN CLASS="code">fast_pool_allocator</SPAN> is also a general-purpose solution, but is geared towards efficiently servicing requests for one chunk at a time; it will work for contiguous chunks, but not as well as <SPAN CLASS="code">pool_allocator</SPAN>. If you are seriously concerned about performance, use <SPAN CLASS="code">fast_pool_allocator</SPAN> when dealing with containers such as <SPAN CLASS="code">std::list</SPAN>, and use <SPAN CLASS="code">pool_allocator</SPAN> when dealing with containers such as <SPAN CLASS="code">std::vector</SPAN>.
<th>Return Type</th>
<P>
<H2>Symbols</H2>
<th>Semantic Equivalence</th>
</tr>
<P>
<UL>
<LI>boost::pool_allocator</LI>
<LI>boost::pool_allocator_tag</LI>
<LI>boost::fast_pool_allocator</LI>
<LI>boost::fast_pool_allocator_tag</LI>
</UL>
<tr>
<td class="code">PoolAlloc::allocate()</td>
<P>
<H2><A HREF="../implementation/pool_alloc.html">Implementation Details</A></H2>
<td class="code">T *</td>
<P>
<HR>
<td class="code">PoolAlloc::allocate(1)</td>
</tr>
<P>
Copyright &copy; 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)
<tr>
<td class="code">PoolAlloc::deallocate(p)</td>
<P>
This file can be redistributed and/or modified under the terms found in <A HREF="../copyright.html">copyright.html</A>
<td>void</td>
<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.
<td class="code">PoolAlloc::deallocate(p, 1)</td>
</tr>
</table>
</BODY>
</HTML>
<p>The typedef <span class="code">user_allocator</span> publishes the value
of the <span class="code">UserAllocator</span> template parameter.</p>
<h2>Notes</h2>
<p>If the allocation functions run out of memory, they will throw
<span class="code">std::bad_alloc</span>.</p>
<p>The underlying Pool type used by the allocators is accessible through
the <a href="singleton_pool.html">Singleton Pool Interface</a>. The
identifying tag used for <span class="code">pool_allocator</span> is
<span class="code">pool_allocator_tag</span>, and the tag used for
<span class="code">fast_pool_allocator</span> is <span class=
"code">fast_pool_allocator_tag</span>. All template parameters of the
allocators (including <a href=
"../implementation/pool_alloc.html">implementation-specific ones</a>)
determine the type of the underlying Pool, with the exception of the first
parameter <span class="code">T</span>, whose size is used instead.</p>
<p>Since the size of <span class="code">T</span> is used to determine the
type of the underlying Pool, each allocator for different types of the same
size <em>will share</em> the same underlying pool. The tag class prevents
pools from being shared between <span class="code">pool_allocator</span>
and <span class="code">fast_pool_allocator</span>. For example, on a system
where sizeof(int) == sizeof(void *), <span class=
"code">pool_allocator&lt;int&gt;</span> and <span class=
"code">pool_allocator&lt;void *&gt;</span> will both allocate/deallocate
from/to the same pool.</p>
<p>If there is only one thread running before <span class=
"code">main()</span> starts and after <span class="code">main()</span>
ends, then both allocators are completely thread-safe.</p>
<h2>The Fast Pool Allocator</h2>
<p><span class="code">pool_allocator</span> is a more general-purpose
solution, geared towards efficiently servicing requests for any number of
contiguous chunks. <span class="code">fast_pool_allocator</span> is also a
general-purpose solution, but is geared towards efficiently servicing
requests for one chunk at a time; it will work for contiguous chunks, but
not as well as <span class="code">pool_allocator</span>. If you are
seriously concerned about performance, use <span class=
"code">fast_pool_allocator</span> when dealing with containers such as
<span class="code">std::list</span>, and use <span class=
"code">pool_allocator</span> when dealing with containers such as
<span class="code">std::vector</span>.</p>
<h2>Symbols</h2>
<ul>
<li>boost::pool_allocator</li>
<li>boost::pool_allocator_tag</li>
<li>boost::fast_pool_allocator</li>
<li>boost::fast_pool_allocator_tag</li>
</ul>
<h2><a href="../implementation/pool_alloc.html">Implementation
Details</a></h2>
<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 &copy; 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>

483
doc/interfaces/simple_segregated_storage.html
View File

@@ -1,25 +1,35 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<TITLE>Simple Segregated Storage</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>Simple Segregated Storage</H1>
<title>Simple Segregated Storage</title>
</head>
<P>
<H2>Introduction</H2>
<body>
<img src="../../../../boost.png" width="276" height="86" alt="C++ Boost">
<P>
simple_segregated_storage.hpp provides a template class <SPAN CLASS="code">simple_segregated_storage</SPAN> that controls access to a <EM>free list</EM> of memory chunks. Please note that this is a <STRONG>very</STRONG> simple class, with preconditions on almost all its functions. It is intended to be the fastest and smallest possible quick memory allocator &mdash; e.g., something to use in embedded systems. This class delegates many difficult preconditions to the user (i.e., alignment issues). For more general usage, see <A HREF="../interfaces.html">the other pool interfaces</A>.
<h1 align="center">Simple Segregated Storage</h1>
<P>
<H2>Synopsis</H2>
<h2>Introduction</h2>
<PRE CLASS="code">template &lt;typename SizeType = std::size_t&gt;
<p>simple_segregated_storage.hpp provides a template class <span class=
"code">simple_segregated_storage</span> that controls access to a <em>free
list</em> of memory chunks. Please note that this is a
<strong>very</strong> simple class, with preconditions on almost all its
functions. It is intended to be the fastest and smallest possible quick
memory allocator &mdash; e.g., something to use in embedded systems. This
class delegates many difficult preconditions to the user (i.e., alignment
issues). For more general usage, see <a href="../interfaces.html">the other
pool interfaces</a>.</p>
<h2>Synopsis</h2>
<pre class="code">
template &lt;typename SizeType = std::size_t&gt;
class simple_segregated_storage
{
private:
@@ -50,101 +60,396 @@ class simple_segregated_storage
size_type partition_sz);
void ordered_free_n(void * chunks, size_type n,
size_type partition_sz);
};</PRE>
};
</pre>
<P>
<H2>Semantics</H2>
<h2>Semantics</h2>
<P>
An object of type <SPAN CLASS="code">simple_segregated_storage&lt;SizeType&gt;</SPAN> is <EM>empty</EM> if its free list is empty. If it is not empty, then it is <EM>ordered</EM> if its free list is ordered. A free list is ordered if repeated calls to <SPAN CLASS="code">malloc()</SPAN> will result in a constantly-increasing sequence of values, as determined by <SPAN CLASS="code">std::less&lt;void *&gt;</SPAN>. A member function is <EM>order-preserving</EM> if the free list maintains its order orientation (that is, an ordered free list is still ordered after the member function call).
<p>An object of type <span class=
"code">simple_segregated_storage&lt;SizeType&gt;</span> is <em>empty</em>
if its free list is empty. If it is not empty, then it is <em>ordered</em>
if its free list is ordered. A free list is ordered if repeated calls to
<span class="code">malloc()</span> will result in a constantly-increasing
sequence of values, as determined by <span class="code">std::less&lt;void
*&gt;</span>. A member function is <em>order-preserving</em> if the free
list maintains its order orientation (that is, an ordered free list is
still ordered after the member function call).</p>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Symbol Table</EM></CAPTION>
<TR><TH>Symbol<TH>Meaning
<TR><TD CLASS="code">Store<TD CLASS="code">simple_segregated_storage&lt;SizeType&gt;
<TR><TD CLASS="code">t<TD>value of type <SPAN CLASS="code">Store</SPAN>
<TR><TD CLASS="code">u<TD>value of type <SPAN CLASS="code">const Store</SPAN>
<TR><TD CLASS="code">block, chunk, end<TD>values of type <SPAN CLASS="code">void *</SPAN>
<TR><TD CLASS="code">partition_sz, sz, n<TD>values of type <SPAN CLASS="code">Store::size_type</SPAN>
</TABLE>
<table border align="center" summary="">
<caption>
<em>Symbol Table</em>
</caption>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Template Parameters</EM></CAPTION>
<TR><TH>Parameter<TH>Default<TH>Requirements
<TR><TD CLASS="code">SizeType<TD CLASS="code">std::size_t<TD>An unsigned integral type
</TABLE>
<tr>
<th>Symbol</th>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Typedefs</EM></CAPTION>
<TR><TH>Symbol<TH>Type
<TR><TD CLASS="code">size_type<TD CLASS="code">SizeType
</TABLE>
<th>Meaning</th>
</tr>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Constructors, Destructors, and State</EM></CAPTION>
<TR><TH>Expression<TH>Return Type<TH>Post-Condition<TH>Notes
<TR><TD CLASS="code">Store()<TD>not used<TD CLASS="code">empty()<TD>Constructs a new <SPAN CLASS="code">Store</SPAN>
<TR><TD CLASS="code">(&amp;t)->~Store()<TD>not used<TD><TD>Destructs the <SPAN CLASS="code">Store</SPAN>
<TR><TD CLASS="code">u.empty()<TD CLASS="code">bool<TD><TD>Returns <SPAN CLASS="code">true</SPAN> if <SPAN CLASS="code">u</SPAN> is empty. Order-preserving.
</TABLE>
<tr>
<td class="code">Store</td>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Segregation</EM></CAPTION>
<TR><TH>Expression<TH>Return Type<TH>Pre-Condition<TH>Post-Condition<TH>Semantic Equivalence<TH>Notes
<td class="code">simple_segregated_storage&lt;SizeType&gt;</td>
</tr>
<TR><TD CLASS="code">Store::segregate(block, sz, partition_sz, end)<TD CLASS="code">void *<TD><SPAN CLASS="code">partition_sz &gt;= sizeof(void *)</SPAN><BR><SPAN CLASS="code">partition_sz = sizeof(void *) * i</SPAN>, for some integer <SPAN CLASS="code">i</SPAN><BR><SPAN CLASS="code">sz &gt;= partition_sz</SPAN><BR><SPAN CLASS="code">block</SPAN> is properly aligned for an array of objects of size <SPAN CLASS="code">partition_sz</SPAN><BR><SPAN CLASS="code">block</SPAN> is properly aligned for an array of <SPAN CLASS="code">void *</SPAN><TD><TD><TD>Interleaves a free list through the memory block specified by <SPAN CLASS="code">block</SPAN> of size <SPAN CLASS="code">sz</SPAN> bytes, partitioning it into as many <SPAN CLASS="code">partition_sz</SPAN>-sized chunks as possible. The last chunk is set to point to <SPAN CLASS="code">end</SPAN>, and a pointer to the first chunck is returned (this is always equal to <SPAN CLASS="code">block</SPAN>). This interleaved free list is ordered. O(sz).
<tr>
<td class="code">t</td>
<TR><TD CLASS="code">Store::segregate(block, sz, partition_sz)<TD CLASS="code">void *<TD>Same as above<TD><TD CLASS="code">Store::segregate(block, sz, partition_sz, 0)<TD>
<td>value of type <span class="code">Store</span></td>
</tr>
<TR><TD CLASS="code">t.add_block(block, sz, partition_sz)<TD CLASS="code">void<TD>Same as above<TD CLASS="code">!t.empty()<TD><TD>Segregates the memory block specified by <SPAN CLASS="code">block</SPAN> of size <SPAN CLASS="code">sz</SPAN> bytes into <SPAN CLASS="code">partition_sz</SPAN>-sized chunks, and adds that free list to its own. If <SPAN CLASS="code">t</SPAN> was empty before this call, then it is ordered after this call. O(sz).
<tr>
<td class="code">u</td>
<TR><TD CLASS="code">t.add_ordered_block(block, sz, partition_sz)<TD CLASS="code">void<TD>Same as above<TD CLASS="code">!t.empty()<TD><TD>Segregates the memory block specified by <SPAN CLASS="code">block</SPAN> of size <SPAN CLASS="code">sz</SPAN> bytes into <SPAN CLASS="code">partition_sz</SPAN>-sized chunks, and merges that free list into its own. Order-preserving. O(sz).
</TABLE>
<td>value of type <span class="code">const Store</span></td>
</tr>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Allocation and Deallocation</EM></CAPTION>
<TR><TH>Expression<TH>Return Type<TH>Pre-Condition<TH>Post-Condition<TH>Semantic Equivalence<TH>Notes
<TR><TD CLASS="code">t.malloc()<TD CLASS="code">void *<TD CLASS="code">!t.empty()<TD><TD><TD>Takes the first available chunk from the free list and returns it. Order-preserving. O(1).
<tr>
<td class="code">block, chunk, end</td>
<TR><TD CLASS="code">t.free(chunk)<TD CLASS="code">void<TD><SPAN CLASS="code">chunk</SPAN> was previously returned from a call to <SPAN CLASS="code">t.malloc()</SPAN><TD CLASS="code">!t.empty()<TD><TD>Places <SPAN CLASS="code">chunk</SPAN> back on the free list. Note that <SPAN CLASS="code">chunk</SPAN> may not be <SPAN CLASS="code">0</SPAN>. O(1).
<td>values of type <span class="code">void *</span></td>
</tr>
<TR><TD CLASS="code">t.ordered_free(chunk)<TD CLASS="code">void<TD>Same as above<TD CLASS="code">!t.empty()<TD><TD>Places <SPAN CLASS="code">chunk</SPAN> back on the free list. Note that <SPAN CLASS="code">chunk</SPAN> may not be <SPAN CLASS="code">0</SPAN>. Order-preserving. O(N) with respect to the size of the free list.
<tr>
<td class="code">partition_sz, sz, n</td>
<TR><TD CLASS="code">t.malloc_n(n, partition_sz)<TD CLASS="code">void *<TD><TD><TD><TD>Attempts to find a contiguous sequence of <SPAN CLASS="code">n</SPAN> <SPAN CLASS="code">partition_sz</SPAN>-sized chunks. If found, removes them all from the free list and returns a pointer to the first. If not found, returns <SPAN CLASS="code">0</SPAN>. It is strongly recommended (but not required) that the free list be ordered, as this algorithm will fail to find a contiguous sequence unless it is contiguous in the free list as well. Order-preserving. O(N) with respect to the size of the free list.
<td>values of type <span class="code">Store::size_type</span></td>
</tr>
</table><br>
<TR><TD CLASS="code">t.free_n(chunk, n, partition_sz)<TD CLASS="code">void<TD><SPAN CLASS="code">chunk</SPAN> was previously returned from a call to <SPAN CLASS="code">t.malloc_n(n, partition_sz)</SPAN><TD CLASS="code">!t.empty()<TD CLASS="code">t.add_block(chunk, n * partition_sz, partition_sz)<TD>Assumes that <SPAN CLASS="code">chunk</SPAN> actually refers to a block of chunks spanning <SPAN CLASS="code">n * partition_sz</SPAN> bytes; segregates and adds in that block. Note that <SPAN CLASS="code">chunk</SPAN> may not be <SPAN CLASS="code">0</SPAN>. O(n).
<table border align="center" summary="">
<caption>
<em>Template Parameters</em>
</caption>
<TR><TD CLASS="code">t.ordered_free_n(chunk, n, partition_sz)<TD CLASS="code">void<TD>same as above<TD>same as above<TD CLASS="code">t.add_ordered_block(chunk, n * partition_sz, partition_sz)<TD>Same as above, except it merges in the free list. Order-preserving. O(N + n) where N is the size of the free list.
</TABLE>
<tr>
<th>Parameter</th>
<P>
<H2>Symbols</H2>
<th>Default</th>
<P>
<UL>
<LI>boost::simple_segregated_storage</LI>
</UL>
<th>Requirements</th>
</tr>
<P>
<H2><A HREF="../implementation/simple_segregated_storage.html">Implementation Details</A></H2>
<tr>
<td class="code">SizeType</td>
<P>
<HR>
<td class="code">std::size_t</td>
<P>
Copyright &copy; 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)
<td>An unsigned integral type</td>
</tr>
</table><br>
<P>
This file can be redistributed and/or modified under the terms found in <A HREF="../copyright.html">copyright.html</A>
<table border align="center" summary="">
<caption>
<em>Typedefs</em>
</caption>
<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.
<tr>
<th>Symbol</th>
</BODY>
</HTML>
<th>Type</th>
</tr>
<tr>
<td class="code">size_type</td>
<td class="code">SizeType</td>
</tr>
</table><br>
<table border align="center" summary="">
<caption>
<em>Constructors, Destructors, and State</em>
</caption>
<tr>
<th>Expression</th>
<th>Return Type</th>
<th>Post-Condition</th>
<th>Notes</th>
</tr>
<tr>
<td class="code">Store()</td>
<td>not used</td>
<td class="code">empty()</td>
<td>Constructs a new <span class="code">Store</span></td>
</tr>
<tr>
<td class="code">(&amp;t)-&gt;~Store()</td>
<td>not used</td>
<td></td>
<td>Destructs the <span class="code">Store</span></td>
</tr>
<tr>
<td class="code">u.empty()</td>
<td class="code">bool</td>
<td></td>
<td>Returns <span class="code">true</span> if <span class=
"code">u</span> is empty. Order-preserving.</td>
</tr>
</table><br>
<table border align="center" summary="">
<caption>
<em>Segregation</em>
</caption>
<tr>
<th>Expression</th>
<th>Return Type</th>
<th>Pre-Condition</th>
<th>Post-Condition</th>
<th>Semantic Equivalence</th>
<th>Notes</th>
</tr>
<tr>
<td class="code">Store::segregate(block, sz, partition_sz, end)</td>
<td class="code">void *</td>
<td><span class="code">partition_sz &gt;= sizeof(void *)</span><br>
<span class="code">partition_sz = sizeof(void *) * i</span>, for some
integer <span class="code">i</span><br>
<span class="code">sz &gt;= partition_sz</span><br>
<span class="code">block</span> is properly aligned for an array of
objects of size <span class="code">partition_sz</span><br>
<span class="code">block</span> is properly aligned for an array of
<span class="code">void *</span></td>
<td></td>
<td></td>
<td>Interleaves a free list through the memory block specified by
<span class="code">block</span> of size <span class="code">sz</span>
bytes, partitioning it into as many <span class=
"code">partition_sz</span>-sized chunks as possible. The last chunk is
set to point to <span class="code">end</span>, and a pointer to the
first chunck is returned (this is always equal to <span class=
"code">block</span>). This interleaved free list is ordered.
O(sz).</td>
</tr>
<tr>
<td class="code">Store::segregate(block, sz, partition_sz)</td>
<td class="code">void *</td>
<td>Same as above</td>
<td></td>
<td class="code">Store::segregate(block, sz, partition_sz, 0)</td>
<td></td>
</tr>
<tr>
<td class="code">t.add_block(block, sz, partition_sz)</td>
<td class="code">void</td>
<td>Same as above</td>
<td class="code">!t.empty()</td>
<td></td>
<td>Segregates the memory block specified by <span class=
"code">block</span> of size <span class="code">sz</span> bytes into
<span class="code">partition_sz</span>-sized chunks, and adds that free
list to its own. If <span class="code">t</span> was empty before this
call, then it is ordered after this call. O(sz).</td>
</tr>
<tr>
<td class="code">t.add_ordered_block(block, sz, partition_sz)</td>
<td class="code">void</td>
<td>Same as above</td>
<td class="code">!t.empty()</td>
<td></td>
<td>Segregates the memory block specified by <span class=
"code">block</span> of size <span class="code">sz</span> bytes into
<span class="code">partition_sz</span>-sized chunks, and merges that
free list into its own. Order-preserving. O(sz).</td>
</tr>
</table><br>
<table border align="center" summary="">
<caption>
<em>Allocation and Deallocation</em>
</caption>
<tr>
<th>Expression</th>
<th>Return Type</th>
<th>Pre-Condition</th>
<th>Post-Condition</th>
<th>Semantic Equivalence</th>
<th>Notes</th>
</tr>
<tr>
<td class="code">t.malloc()</td>
<td class="code">void *</td>
<td class="code">!t.empty()</td>
<td></td>
<td></td>
<td>Takes the first available chunk from the free list and returns it.
Order-preserving. O(1).</td>
</tr>
<tr>
<td class="code">t.free(chunk)</td>
<td class="code">void</td>
<td><span class="code">chunk</span> was previously returned from a call
to <span class="code">t.malloc()</span></td>
<td class="code">!t.empty()</td>
<td></td>
<td>Places <span class="code">chunk</span> back on the free list. Note
that <span class="code">chunk</span> may not be <span class=
"code">0</span>. O(1).</td>
</tr>
<tr>
<td class="code">t.ordered_free(chunk)</td>
<td class="code">void</td>
<td>Same as above</td>
<td class="code">!t.empty()</td>
<td></td>
<td>Places <span class="code">chunk</span> back on the free list. Note
that <span class="code">chunk</span> may not be <span class=
"code">0</span>. Order-preserving. O(N) with respect to the size of the
free list.</td>
</tr>
<tr>
<td class="code">t.malloc_n(n, partition_sz)</td>
<td class="code">void *</td>
<td></td>
<td></td>
<td></td>
<td>Attempts to find a contiguous sequence of <span class=
"code">n</span> <span class="code">partition_sz</span>-sized chunks. If
found, removes them all from the free list and returns a pointer to the
first. If not found, returns <span class="code">0</span>. It is
strongly recommended (but not required) that the free list be ordered,
as this algorithm will fail to find a contiguous sequence unless it is
contiguous in the free list as well. Order-preserving. O(N) with
respect to the size of the free list.</td>
</tr>
<tr>
<td class="code">t.free_n(chunk, n, partition_sz)</td>
<td class="code">void</td>
<td><span class="code">chunk</span> was previously returned from a call
to <span class="code">t.malloc_n(n, partition_sz)</span></td>
<td class="code">!t.empty()</td>
<td class="code">t.add_block(chunk, n * partition_sz,
partition_sz)</td>
<td>Assumes that <span class="code">chunk</span> actually refers to a
block of chunks spanning <span class="code">n * partition_sz</span>
bytes; segregates and adds in that block. Note that <span class=
"code">chunk</span> may not be <span class="code">0</span>. O(n).</td>
</tr>
<tr>
<td class="code">t.ordered_free_n(chunk, n, partition_sz)</td>
<td class="code">void</td>
<td>same as above</td>
<td>same as above</td>
<td class="code">t.add_ordered_block(chunk, n * partition_sz,
partition_sz)</td>
<td>Same as above, except it merges in the free list. Order-preserving.
O(N + n) where N is the size of the free list.</td>
</tr>
</table>
<h2>Symbols</h2>
<ul>
<li>boost::simple_segregated_storage</li>
</ul>
<h2><a href=
"../implementation/simple_segregated_storage.html">Implementation
Details</a></h2>
<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 &copy; 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>

345
doc/interfaces/singleton_pool.html
View File

@@ -1,25 +1,31 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<TITLE>Singleton Pool</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>Singleton Pool</H1>
<title>Singleton Pool</title>
</head>
<P>
<H2>Introduction</H2>
<body>
<img src="../../../../boost.png" width="276" height="86" alt="C++ Boost">
<P>
singleton_pool.hpp provides a template class <SPAN CLASS="code">singleton_pool</SPAN>, which provides access to a <SPAN CLASS="code">pool</SPAN> as a singleton object. For information on other pool-based interfaces, see <A HREF="../interfaces.html">the other pool interfaces</A>.
<h1 align="center">Singleton Pool</h1>
<P>
<H2>Synopsis</H2>
<h2>Introduction</h2>
<PRE CLASS="code">template &lt;typename Tag, unsigned RequestedSize,
<p>singleton_pool.hpp provides a template class <span class=
"code">singleton_pool</span>, which provides access to a <span class=
"code">pool</span> as a singleton object. For information on other
pool-based interfaces, see <a href="../interfaces.html">the other pool
interfaces</a>.</p>
<h2>Synopsis</h2>
<pre class="code">
template &lt;typename Tag, unsigned RequestedSize,
typename UserAllocator = default_user_allocator_new_delete&gt;
struct singleton_pool
{
@@ -50,108 +56,253 @@ struct singleton_pool
static bool release_memory();
static bool purge_memory();
};</PRE>
};
</pre>
<P>
<H2>Notes</H2>
<h2>Notes</h2>
<P>
The underlying pool <SPAN CLASS="code">p</SPAN> referenced by the static functions in <SPAN CLASS="code">singleton_pool</SPAN> is actually declared in a way that it is:
<UL>
<LI>Thread-safe if there is only one thread running before main() begins and after main() ends -- all of the static functions of <SPAN CLASS="code">singleton_pool</SPAN> synchronize their access to <SPAN CLASS="code">p</SPAN>.</LI>
<LI>Guaranteed to be constructed before it is used -- thus, the simple static object in the synopsis above would actually be an incorrect implementation. The actual <A HREF="../implementation/singleton_pool.html">implementation</A> to guarantee this is considerably more complicated.
</UL>
<p>The underlying pool <span class="code">p</span> referenced by the static
functions in <span class="code">singleton_pool</span> is actually declared
in a way that it is:</p>
<P>
Note that a different underlying pool <SPAN CLASS="code">p</SPAN> exists for each different set of template parameters, including <A HREF="../implementation/singleton_pool.html">implementation-specific ones</A>.
<ul>
<li>Thread-safe if there is only one thread running before main() begins
and after main() ends -- all of the static functions of <span class=
"code">singleton_pool</span> synchronize their access to <span class=
"code">p</span>.</li>
<P>
<H2>Template Parameters</H2>
<li>Guaranteed to be constructed before it is used -- thus, the simple
static object in the synopsis above would actually be an incorrect
implementation. The actual <a href=
"../implementation/singleton_pool.html">implementation</a> to guarantee
this is considerably more complicated.</li>
</ul>
<P>
<H3>Tag</H3>
<p>Note that a different underlying pool <span class="code">p</span> exists
for each different set of template parameters, including <a href=
"../implementation/singleton_pool.html">implementation-specific
ones</a>.</p>
<P>
The <SPAN CLASS="code">Tag</SPAN> template parameter allows different unbounded sets of singleton pools to exist. For example, the <A HREF="pool_alloc.html">pool allocators</A> use two tag classes to ensure that the two different allocator types never share the same underlying singleton pool.
<h2>Template Parameters</h2>
<P>
<SPAN CLASS="code">Tag</SPAN> is never actually used by <SPAN CLASS="code">singleton_pool</SPAN>.
<h3>Tag</h3>
<P>
<H3>RequestedSize</H3>
<p>The <span class="code">Tag</span> template parameter allows different
unbounded sets of singleton pools to exist. For example, the <a href=
"pool_alloc.html">pool allocators</a> use two tag classes to ensure that
the two different allocator types never share the same underlying singleton
pool.</p>
<P>
The requested size of memory chunks to allocate. This is passed as a constructor parameter to the underlying <SPAN CLASS="code">pool</SPAN>. Must be greater than 0.
<p><span class="code">Tag</span> is never actually used by <span class=
"code">singleton_pool</span>.</p>
<P>
<H3>UserAllocator</H3>
<h3>RequestedSize</h3>
<P>
Defines the method that the underlying <SPAN CLASS="code">pool</SPAN> will use to allocate memory from the system. See <A HREF="user_allocator.html">User Allocators</A> for details.
<p>The requested size of memory chunks to allocate. This is passed as a
constructor parameter to the underlying <span class="code">pool</span>.
Must be greater than 0.</p>
<P>
<H2>Semantics</H2>
<h3>UserAllocator</h3>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Symbol Table</EM></CAPTION>
<TR><TH>Symbol<TH>Meaning
<TR><TD CLASS="code">SingletonPool<TD CLASS="code">singleton_pool&lt;Tag, RequestedSize, UserAllocator&gt;
<TR><TD CLASS="code">chunk<TD>value of type <SPAN CLASS="code">void *</SPAN>
<TR><TD CLASS="code">n<TD>value of type <SPAN CLASS="code">size_type</SPAN>
</TABLE>
<p>Defines the method that the underlying <span class="code">pool</span>
will use to allocate memory from the system. See <a href=
"user_allocator.html">User Allocators</a> for details.</p>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Typedefs/Static Const Values</EM></CAPTION>
<TR><TH>Expression<TH>Type/Value
<TR><TD CLASS="code">SingletonPool::tag<TD CLASS="code">Tag
<TR><TD CLASS="code">SingletonPool::user_allocator<TD CLASS="code">UserAllocator
<TR><TD CLASS="code">SingletonPool::size_type<TD CLASS="code">pool&lt;UserAllocator&gt;::size_type
<TR><TD CLASS="code">SingletonPool::difference_type<TD CLASS="code">pool&lt;UserAllocator&gt;::difference_type
<TR><TD CLASS="code">SingletonPool::requested_size<TD CLASS="code">RequestedSize
</TABLE>
<h2>Semantics</h2>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Functions</EM></CAPTION>
<TR><TH>Expression<TH>Return Type<TH>Semantic Equivalent
<TR><TD CLASS="code">SingletonPool::is_from(chunk)<TD CLASS="code">bool<TD><SPAN CLASS="code">SingletonPool::p.is_from(chunk);</SPAN> synchronized
<TR><TD CLASS="code">SingletonPool::malloc()<TD CLASS="code">void *<TD><SPAN CLASS="code">SingletonPool::p.malloc();</SPAN> synchronized
<TR><TD CLASS="code">SingletonPool::ordered_malloc(n)<TD CLASS="code">void *<TD><SPAN CLASS="code">SingletonPool::p.ordered_malloc(n);</SPAN> synchronized
<TR><TD CLASS="code">SingletonPool::free(chunk)<TD CLASS="code">void<TD><SPAN CLASS="code">SingletonPool::p.free(chunk);</SPAN> synchronized
<TR><TD CLASS="code">SingletonPool::ordered_free(chunk)<TD CLASS="code">void<TD><SPAN CLASS="code">SingletonPool::p.ordered_free(chunk);</SPAN> synchronized
<TR><TD CLASS="code">SingletonPool::free(chunk, n)<TD CLASS="code">void<TD><SPAN CLASS="code">SingletonPool::p.free(chunk, n);</SPAN> synchronized
<TR><TD CLASS="code">SingletonPool::ordered_free(chunk, n)<TD CLASS="code">void<TD><SPAN CLASS="code">SingletonPool::p.ordered_free(chunk, n);</SPAN> synchronized
<TR><TD CLASS="code">SingletonPool::release_memory()<TD CLASS="code">bool<TD><SPAN CLASS="code">SingletonPool::p.release_memory();</SPAN> synchronized
<TR><TD CLASS="code">SingletonPool::purge_memory()<TD CLASS="code">bool<TD><SPAN CLASS="code">SingletonPool::p.purge_memory();</SPAN> synchronized
</TABLE>
<table border align="center" summary="">
<caption>
<em>Symbol Table</em>
</caption>
<P>
For more information on the semantics of these functions, see the <A HREF="pool.html">pool interface</A>.
<tr>
<th>Symbol</th>
<P>
<H2>Symbols</H2>
<th>Meaning</th>
</tr>
<P>
<UL>
<LI>boost::singleton_pool</LI>
</UL>
<tr>
<td class="code">SingletonPool</td>
<P>
<H2><A HREF="../implementation/singleton_pool.html">Implementation Details</A></H2>
<td class="code">singleton_pool&lt;Tag, RequestedSize,
UserAllocator&gt;</td>
</tr>
<P>
<HR>
<tr>
<td class="code">chunk</td>
<P>
Copyright &copy; 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)
<td>value of type <span class="code">void *</span></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 class="code">n</td>
<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.
<td>value of type <span class="code">size_type</span></td>
</tr>
</table><br>
</BODY>
</HTML>
<table border align="center" summary="">
<caption>
<em>Typedefs/Static Const Values</em>
</caption>
<tr>
<th>Expression</th>
<th>Type/Value</th>
</tr>
<tr>
<td class="code">SingletonPool::tag</td>
<td class="code">Tag</td>
</tr>
<tr>
<td class="code">SingletonPool::user_allocator</td>
<td class="code">UserAllocator</td>
</tr>
<tr>
<td class="code">SingletonPool::size_type</td>
<td class="code">pool&lt;UserAllocator&gt;::size_type</td>
</tr>
<tr>
<td class="code">SingletonPool::difference_type</td>
<td class="code">pool&lt;UserAllocator&gt;::difference_type</td>
</tr>
<tr>
<td class="code">SingletonPool::requested_size</td>
<td class="code">RequestedSize</td>
</tr>
</table><br>
<table border align="center" summary="">
<caption>
<em>Functions</em>
</caption>
<tr>
<th>Expression</th>
<th>Return Type</th>
<th>Semantic Equivalent</th>
</tr>
<tr>
<td class="code">SingletonPool::is_from(chunk)</td>
<td class="code">bool</td>
<td><span class="code">SingletonPool::p.is_from(chunk);</span>
synchronized</td>
</tr>
<tr>
<td class="code">SingletonPool::malloc()</td>
<td class="code">void *</td>
<td><span class="code">SingletonPool::p.malloc();</span>
synchronized</td>
</tr>
<tr>
<td class="code">SingletonPool::ordered_malloc(n)</td>
<td class="code">void *</td>
<td><span class="code">SingletonPool::p.ordered_malloc(n);</span>
synchronized</td>
</tr>
<tr>
<td class="code">SingletonPool::free(chunk)</td>
<td class="code">void</td>
<td><span class="code">SingletonPool::p.free(chunk);</span>
synchronized</td>
</tr>
<tr>
<td class="code">SingletonPool::ordered_free(chunk)</td>
<td class="code">void</td>
<td><span class="code">SingletonPool::p.ordered_free(chunk);</span>
synchronized</td>
</tr>
<tr>
<td class="code">SingletonPool::free(chunk, n)</td>
<td class="code">void</td>
<td><span class="code">SingletonPool::p.free(chunk, n);</span>
synchronized</td>
</tr>
<tr>
<td class="code">SingletonPool::ordered_free(chunk, n)</td>
<td class="code">void</td>
<td><span class="code">SingletonPool::p.ordered_free(chunk, n);</span>
synchronized</td>
</tr>
<tr>
<td class="code">SingletonPool::release_memory()</td>
<td class="code">bool</td>
<td><span class="code">SingletonPool::p.release_memory();</span>
synchronized</td>
</tr>
<tr>
<td class="code">SingletonPool::purge_memory()</td>
<td class="code">bool</td>
<td><span class="code">SingletonPool::p.purge_memory();</span>
synchronized</td>
</tr>
</table>
<p>For more information on the semantics of these functions, see the
<a href="pool.html">pool interface</a>.</p>
<h2>Symbols</h2>
<ul>
<li>boost::singleton_pool</li>
</ul>
<h2><a href="../implementation/singleton_pool.html">Implementation
Details</a></h2>
<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 &copy; 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>

188
doc/interfaces/user_allocator.html
View File

@@ -1,59 +1,130 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
<HEAD>
<TITLE>Pool</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>User Allocators</H1>
<title>Pool</title>
</head>
<P>
<H2>Introduction</H2>
<body>
<img src="../../../../boost.png" width="276" height="86" alt="C++ Boost">
<P>
Pool objects need to request memory blocks from the system, which the Pool then splits into chunks to allocate to the user. By specifying a <SPAN CLASS="code">UserAllocator</SPAN> template parameter to various Pool interfaces, users can control how those system memory blocks are allocated.
<h1 align="center">User Allocators</h1>
<P>
<H2>Semantics</H2>
<h2>Introduction</h2>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Symbol Table</EM></CAPTION>
<TR><TH>Symbol<TH>Meaning
<TR><TD CLASS="code">UserAllocator<TD>A User Allocator type
<TR><TD CLASS="code">block<TD>value of type <SPAN CLASS="code">char *</SPAN>
<TR><TD CLASS="code">n<TD>value of type <SPAN CLASS="code">UserAllocator::size_type</SPAN>
</TABLE>
<p>Pool objects need to request memory blocks from the system, which the
Pool then splits into chunks to allocate to the user. By specifying a
<span class="code">UserAllocator</span> template parameter to various Pool
interfaces, users can control how those system memory blocks are
allocated.</p>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Typedefs</EM></CAPTION>
<TR><TH>Expression<TH>Type
<TR><TD CLASS="code">UserAllocator::size_type<TD>An unsigned integral type that can represent the size of the largest object to be allocated
<TR><TD CLASS="code">UserAllocator::difference_type<TD>A signed integral type that can represent the difference of any two pointers
</TABLE>
<h2>Semantics</h2>
<P>
<TABLE BORDER ALIGN=CENTER>
<CAPTION><EM>Allocation and Deallocation</EM></CAPTION>
<TR><TH>Expression<TH>Return Type<TH>Pre-Condition/Notes
<TR><TD CLASS="code">UserAllocator::malloc(n)<TD CLASS="code">char *<TD>Attempts to allocate <SPAN CLASS="code">n</SPAN> bytes from the system. Returns 0 if out-of-memory.
<TR><TD CLASS="code">UserAllocator::free(block)<TD CLASS="code">void<TD><SPAN CLASS="code">block</SPAN> must have been previously returned from a call to <SPAN CLASS="code">UserAllocator::malloc</SPAN>.
</TABLE>
<table border align="center" summary="">
<caption>
<em>Symbol Table</em>
</caption>
<P>
<H2>Provided Implementations</H2>
<tr>
<th>Symbol</th>
<P>
There are two <SPAN CLASS="code">UserAllocator</SPAN> classes provided. Both of them are in pool.hpp (see <A HREF="pool.html">pool</A>). The default value for the template parameter <SPAN CLASS="code">UserAllocator</SPAN> is always <SPAN CLASS="code">default_user_allocator_new_delete</SPAN>.
<th>Meaning</th>
</tr>
<P>
<H3>Synopsis</H3>
<tr>
<td class="code">UserAllocator</td>
<PRE CLASS="code">struct default_user_allocator_new_delete
<td>A User Allocator type</td>
</tr>
<tr>
<td class="code">block</td>
<td>value of type <span class="code">char *</span></td>
</tr>
<tr>
<td class="code">n</td>
<td>value of type <span class=
"code">UserAllocator::size_type</span></td>
</tr>
</table><br>
<table border align="center" summary="">
<caption>
<em>Typedefs</em>
</caption>
<tr>
<th>Expression</th>
<th>Type</th>
</tr>
<tr>
<td class="code">UserAllocator::size_type</td>
<td>An unsigned integral type that can represent the size of the
largest object to be allocated</td>
</tr>
<tr>
<td class="code">UserAllocator::difference_type</td>
<td>A signed integral type that can represent the difference of any two
pointers</td>
</tr>
</table><br>
<table border align="center" summary="">
<caption>
<em>Allocation and Deallocation</em>
</caption>
<tr>
<th>Expression</th>
<th>Return Type</th>
<th>Pre-Condition/Notes</th>
</tr>
<tr>
<td class="code">UserAllocator::malloc(n)</td>
<td class="code">char *</td>
<td>Attempts to allocate <span class="code">n</span> bytes from the
system. Returns 0 if out-of-memory.</td>
</tr>
<tr>
<td class="code">UserAllocator::free(block)</td>
<td class="code">void</td>
<td><span class="code">block</span> must have been previously returned
from a call to <span class="code">UserAllocator::malloc</span>.</td>
</tr>
</table>
<h2>Provided Implementations</h2>
<p>There are two <span class="code">UserAllocator</span> classes provided.
Both of them are in pool.hpp (see <a href="pool.html">pool</a>). The
default value for the template parameter <span class=
"code">UserAllocator</span> is always <span class=
"code">default_user_allocator_new_delete</span>.</p>
<h3>Synopsis</h3>
<pre class="code">
struct default_user_allocator_new_delete
{
typedef std::size_t size_type;
typedef std::ptrdiff_t difference_type;
@@ -73,19 +144,24 @@ struct default_user_allocator_malloc_free
{ return reinterpret_cast&lt;char *&gt;(std::malloc(bytes)); }
static void free(char * const block)
{ std::free(block); }
};</PRE>
};
</pre>
<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>

8
doc/pool.css
View File

@@ -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% }