Subject: [Boost-commit] svn:boost r71187 - in sandbox/guild/pool/libs/pool/doc: . Doxygen images implementation interfaces
From: john_at_[hidden]
Date: 2011-04-11 12:10:39
Author: johnmaddock
Date: 2011-04-11 12:10:36 EDT (Mon, 11 Apr 2011)
New Revision: 71187
URL: http://svn.boost.org/trac/boost/changeset/71187
Log:
Tidy up intro.
Remove dead files.
Add missing graphics.
Added:
sandbox/guild/pool/libs/pool/doc/images/
sandbox/guild/pool/libs/pool/doc/images/MB4.PNG (contents, props changed)
sandbox/guild/pool/libs/pool/doc/images/PC2.PNG (contents, props changed)
sandbox/guild/pool/libs/pool/doc/images/PC3.PNG (contents, props changed)
sandbox/guild/pool/libs/pool/doc/images/PC4.PNG (contents, props changed)
sandbox/guild/pool/libs/pool/doc/images/PC5.PNG (contents, props changed)
sandbox/guild/pool/libs/pool/doc/images/mb1.PNG (contents, props changed)
sandbox/guild/pool/libs/pool/doc/images/mb1.svg (contents, props changed)
sandbox/guild/pool/libs/pool/doc/images/mb2.PNG (contents, props changed)
sandbox/guild/pool/libs/pool/doc/images/mb2.svg (contents, props changed)
sandbox/guild/pool/libs/pool/doc/images/mb3.PNG (contents, props changed)
sandbox/guild/pool/libs/pool/doc/images/mb3.svg (contents, props changed)
sandbox/guild/pool/libs/pool/doc/images/mb4.svg (contents, props changed)
sandbox/guild/pool/libs/pool/doc/images/pc1.PNG (contents, props changed)
sandbox/guild/pool/libs/pool/doc/images/pc1.svg (contents, props changed)
sandbox/guild/pool/libs/pool/doc/images/pc2.svg (contents, props changed)
sandbox/guild/pool/libs/pool/doc/images/pc3.svg (contents, props changed)
sandbox/guild/pool/libs/pool/doc/images/pc4.svg (contents, props changed)
sandbox/guild/pool/libs/pool/doc/images/pc5.svg (contents, props changed)
Removed:
sandbox/guild/pool/libs/pool/doc/Doxygen/
sandbox/guild/pool/libs/pool/doc/concepts.html
sandbox/guild/pool/libs/pool/doc/implementation/
sandbox/guild/pool/libs/pool/doc/index.html
sandbox/guild/pool/libs/pool/doc/interfaces/
sandbox/guild/pool/libs/pool/doc/interfaces.html
Binary files modified:
sandbox/guild/pool/libs/pool/doc/pool.pdf
Text files modified:
sandbox/guild/pool/libs/pool/doc/jamfile.v2 | 162 ++++++++++++++++++++--------------------
sandbox/guild/pool/libs/pool/doc/pool.qbk | 92 ++++++++++------------
2 files changed, 124 insertions(+), 130 deletions(-)
Deleted: sandbox/guild/pool/libs/pool/doc/concepts.html
Added: sandbox/guild/pool/libs/pool/doc/images/MB4.PNG
Added: sandbox/guild/pool/libs/pool/doc/images/PC2.PNG
Added: sandbox/guild/pool/libs/pool/doc/images/PC3.PNG
Added: sandbox/guild/pool/libs/pool/doc/images/PC4.PNG
Added: sandbox/guild/pool/libs/pool/doc/images/PC5.PNG
Added: sandbox/guild/pool/libs/pool/doc/images/mb1.PNG
Added: sandbox/guild/pool/libs/pool/doc/images/mb1.svg
Added: sandbox/guild/pool/libs/pool/doc/images/mb2.PNG
Added: sandbox/guild/pool/libs/pool/doc/images/mb2.svg
Added: sandbox/guild/pool/libs/pool/doc/images/mb3.PNG
Added: sandbox/guild/pool/libs/pool/doc/images/mb3.svg
Added: sandbox/guild/pool/libs/pool/doc/images/mb4.svg
Added: sandbox/guild/pool/libs/pool/doc/images/pc1.PNG
Added: sandbox/guild/pool/libs/pool/doc/images/pc1.svg
Added: sandbox/guild/pool/libs/pool/doc/images/pc2.svg
Added: sandbox/guild/pool/libs/pool/doc/images/pc3.svg
Added: sandbox/guild/pool/libs/pool/doc/images/pc4.svg
Added: sandbox/guild/pool/libs/pool/doc/images/pc5.svg
Deleted: sandbox/guild/pool/libs/pool/doc/index.html
Deleted: sandbox/guild/pool/libs/pool/doc/interfaces.html
Modified: sandbox/guild/pool/libs/pool/doc/jamfile.v2
Modified: sandbox/guild/pool/libs/pool/doc/pool.pdf
Modified: sandbox/guild/pool/libs/pool/doc/pool.qbk
==============================================================================
--- sandbox/guild/pool/libs/pool/doc/concepts.html 2011-04-11 12:10:36 EDT (Mon, 11 Apr 2011)
+++ (empty file)
@@ -1,407 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
-"http://www.w3.org/TR/html4/loose.dtd">
-
-<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">
-
- <title>Pool Concepts</title>
-</head>
-
-<body>
- <img src="../../../boost.png" width="276" height="86" alt="C++ Boost">
-
- <h1 align="center">Pool Concepts</h1>
-
- <blockquote>
- "Dynamic memory allocation has been a fundamental part of most computer
- systems since roughly 1960..."<sup>1</sup>
- </blockquote>
-
- <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>
-
- <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>
-
- <p>The heap is complicated. It has to satisfy any type of memory request,
- for any size, and do it <em>fast</em>. The common approaches to memory
- management have to do with splitting the memory up into portions, and
- keeping them ordered by size in some sort of a tree or list structure. Add
- in other factors, such as locality and estimating lifetime, and heaps
- quickly become very complicated. So complicated, in fact, that there is no
- known "perfect" answer to the problem of how to do dynamic memory
- allocation. The diagrams below illustrate how most common memory managers
- work: for each chunk of memory, it uses part of that memory to maintain its
- internal tree or list structure. Even when a chunk is <span class=
- "code">malloc</span>'ed out to a program, the memory manager must "save"
- some information in it — usually just its size. Then, when the block
- is <span class="code">free</span>'d, the memory manager can easily tell how
- large it is.</p>
-
- <table cellspacing="0" border="3" rules="none" style=
- "float: left; clear: both;" summary="">
- <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>
-
- <table cellspacing="0" border="3" rules="none" style=
- "float: right; clear: both;" summary="">
- <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>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>2</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>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 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>
-
- <h1 align="center">Simple Segregated Storage</h1>
-
- <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>
-
- <table cellspacing="0" border="3" rules="none" align="center" style=
- "clear: both;" summary="">
- <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>
-
- <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>
-
- <p>Simple Segregated Storage works by interleaving a <em>free list</em>
- within the unused chunks. For example:</p>
-
- <table cellspacing="0" border="3" rules="none" style=
- "float: left; clear: both;" summary="">
- <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>
-
- <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></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></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=
- "../../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
- height="31" width="88"></a></p>
-
- <p>Revised
- <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05
- December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38516" --></p>
-
- <p><i>Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT
- com)</i></p>
-
- <p><i>Distributed under the Boost Software License, Version 1.0. (See
- accompanying file LICENSE_1_0.txt or
- copy at <a href=
- "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt>)</i></p>
-</body>
-</html>
==============================================================================
Binary file. No diff available.
==============================================================================
Binary file. No diff available.
==============================================================================
Binary file. No diff available.
==============================================================================
Binary file. No diff available.
==============================================================================
Binary file. No diff available.
==============================================================================
Binary file. No diff available.
==============================================================================
Binary file. No diff available.
==============================================================================
Binary file. No diff available.
==============================================================================
Binary file. No diff available.
==============================================================================
Binary file. No diff available.
==============================================================================
Binary file. No diff available.
==============================================================================
Binary file. No diff available.
==============================================================================
Binary file. No diff available.
==============================================================================
Binary file. No diff available.
==============================================================================
Binary file. No diff available.
==============================================================================
Binary file. No diff available.
==============================================================================
Binary file. No diff available.
==============================================================================
Binary file. No diff available.
==============================================================================
--- sandbox/guild/pool/libs/pool/doc/index.html 2011-04-11 12:10:36 EDT (Mon, 11 Apr 2011)
+++ (empty file)
@@ -1,231 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
-"http://www.w3.org/TR/html4/loose.dtd">
-
-<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">
-
- <title>Boost Pool Library</title>
-</head>
-
-<body>
- <img src="../../../boost.png" width="276" height="86" alt="C++ Boost">
-
- <h1 align="center">Boost Pool Library</h1>
-
- <h2>Introduction</h2>
-
- <h3>What is Pool?</h3>
-
- <p>Pool allocation is a memory allocation scheme that is very fast, but
- limited in its usage. For more information on pool allocation (also called
- "simple segregated storage"), see <a href="concepts.html">the concepts
- document</a>.</p>
-
- <h3>Why should I use 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>
-
- <h3>When 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>
-
- <p>In general, use Pools when you need a more efficient way to do unusual
- memory control.</p>
-
- <h3>How do I use Pool?</h3>
-
- <p>See the pool interfaces document, which
- covers the different Pool interfaces supplied by this library.</p>
-
- <h2>Library Structure and Dependencies</h2>
-
- <p>Forward declarations of all the exposed symbols for this library are in
- the header <span class="code"><boost/pool/poolfwd.hpp></span>.</p>
-
- <p>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>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>Every header used only by the implementation is in the subdirectory
- <span class="code">detail/</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>
-
- <h2>Installation</h2>
-
- <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>
-
- <h2>Building the Test Programs</h2>
-
- <p>The subdirectory "build" contains subdirectories for several different
- platforms. These subdirectories contain all necessary work-around code for
- that platform, as well as makefiles or IDE project files as appropriate.</p>
-
- <p>Read the "readme.txt" in the proper subdirectory, if it exists.</p>
-
- <p>The standard makefile targets are "all", "clean" (which deletes any
- intermediate files), and "veryclean" (which deletes any intermediate files
- and executables). All intermediate and executable files are built in the
- same directory as the makefile/project file. If there is a project file
- supplied instead of a makefile, "clean" and "veryclean" shell scripts/batch
- files will be provided.</p>
-
- <p>Project files and makefiles for additional platforms may be sent to
- Stephen Cleary at scleary AT jerviswebb DOT com.</p>
-
- <h2>Documentation Map</h2>
-
- <ul>
- <li>Overview of Pooling
-
- <ul>
- <li>concepts.html - The basic ideas behind
- pooling.</li>
-
- <li><a href=
- "implementation/alignment.html">implementation/alignment.html</a> -
- How we guarantee alignment portably.</li>
-
- <li>interfaces.html - 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>interfaces/pool.html - 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>implementation/for.html
- - 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=
- "../../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
- height="31" width="88"></a></p>
-
- <p>Revised
- <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05 December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38516" --></p>
-
- <p><i>Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)</i></p>
-
- <p><i>Distributed under the Boost Software License, Version 1.0. (See
- accompanying file LICENSE_1_0.txt or
- copy at <a href=
- "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt>)</i></p>
-</body>
-</html>
==============================================================================
--- sandbox/guild/pool/libs/pool/doc/interfaces.html 2011-04-11 12:10:36 EDT (Mon, 11 Apr 2011)
+++ (empty file)
@@ -1,153 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
-"http://www.w3.org/TR/html4/loose.dtd">
-
-<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">
-
- <title>Boost Pool Interfaces</title>
-</head>
-
-<body>
- <img src="../../../boost.png" width="276" height="86" alt="C++ Boost">
-
- <h1 align="center">Boost Pool Interfaces</h1>
-
- <h2>Introduction</h2>
-
- <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>
-
- <h2>Terminology and Tradeoffs</h2>
-
- <h3>Object Usage vs. Singleton Usage</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><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>
-
- <h3>Out-of-Memory Conditions: Exceptions vs. Null Return</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>
-
- <h2>The Interfaces</h2>
-
- <h3>pool</h3>
-
- <p>The pool interface is a simple Object
- Usage interface with Null Return.</p>
-
- <p>Example:</p>
- <pre class="code">
-void func()
-{
- boost::pool<> p(sizeof(int));
- for (int i = 0; i < 10000; ++i)
- {
- 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>
-
- <h3>object_pool</h3>
-
- <p>The object_pool interface 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:</p>
- <pre class="code">
-struct X { ... }; // has destructor with side-effects
-
-void func()
-{
- boost::object_pool<X> p;
- for (int i = 0; i < 10000; ++i)
- {
- 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>
-
- <h3>singleton_pool</h3>
-
- <p>The singleton_pool interface
- 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:</p>
- <pre class="code">
-struct MyPoolTag { };
-
-typedef boost::singleton_pool<MyPoolTag, sizeof(int)> my_pool;
-void func()
-{
- for (int i = 0; i < 10000; ++i)
- {
- int * const t = my_pool::malloc();
- ... // Do something with t; don't take the time to free() it
- }
- // Explicitly free all malloc()'ed int's
- my_pool::purge_memory();
-}
-</pre>
-
- <h3>pool_alloc</h3>
-
- <p>The pool_alloc interface 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:</p>
- <pre class="code">
-void func()
-{
- std::vector<int, boost::pool_allocator<int> > v;
- for (int i = 0; i < 10000; ++i)
- v.push_back(13);
-} // Exiting the function does NOT free the system memory allocated by the pool allocator
- // You must call
- // boost::singleton_pool<boost::pool_allocator_tag, sizeof(int)>::release_memory()
- // in order to force that
-</pre>
-
- <h2>Future Directions</h2>
-
- <p>Another pool interface will be written: a base class for per-class pool
- allocation. This "pool_base" interface will be Singleton Usage with
- Exceptions, and built on the singleton_pool interface.</p>
- <hr>
-
- <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
- "../../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
- height="31" width="88"></a></p>
-
- <p>Revised
- <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05 December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38516" --></p>
-
- <p><i>Copyright © 2000, 2001 Stephen Cleary (scleary AT jerviswebb DOT com)</i></p>
-
- <p><i>Distributed under the Boost Software License, Version 1.0. (See
- accompanying file LICENSE_1_0.txt or
- copy at <a href=
- "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt>)</i></p>
-</body>
-</html>
==============================================================================
--- sandbox/guild/pool/libs/pool/doc/jamfile.v2 (original)
+++ sandbox/guild/pool/libs/pool/doc/jamfile.v2 2011-04-11 12:10:36 EDT (Mon, 11 Apr 2011)
@@ -85,94 +85,94 @@
pool
:
- # General settings
- # =================
- # Path for links to Boost.
- <xsl:param>boost.root=../../../../..
- # Path for libraries index:
- <xsl:param>boost.libraries=../../../../../libs/libraries.htm
- # Use the main Boost stylesheet:
- #<xsl:param>html.stylesheet=../../doc/html/boostbook.css
- <xsl:param>html.stylesheet=./boostbook.css
-
- #<xsl:param>nav.layout=none # No navigation bar (home, prev, next).
- # defining creates a runtime error: Global parameter nav.layout already defined
- <xsl:param>nav.layout=horizontal # to get a horizontal navigation bar (you probably DO want this).
-
- # Path for links to Boost logo.
- #<xsl:param>boost.root=.. # already defined
- <xsl:param>boost.image=Boost # options are: none (no logo), Boost (for boost.png), or your own logo, for example, inspired_by_boost.png
- <xsl:param>boost.image.src=./images/boost.png #
- <xsl:param>boost.image.w=180 # Width of logo in pixels. (JM has W = 162, h = 46)
- <xsl:param>boost.image.h=90 # Height of logo in pixels.
+ # General settings
+ # =================
+ # Path for links to Boost.
+ <xsl:param>boost.root=../../../../..
+ # Path for libraries index:
+ <xsl:param>boost.libraries=../../../../../libs/libraries.htm
+ # Use the main Boost stylesheet:
+ #<xsl:param>html.stylesheet=../../doc/html/boostbook.css
+ <xsl:param>html.stylesheet=./boostbook.css
+
+ #<xsl:param>nav.layout=none # No navigation bar (home, prev, next).
+ # defining creates a runtime error: Global parameter nav.layout already defined
+ <xsl:param>nav.layout=horizontal # to get a horizontal navigation bar (you probably DO want this).
+
+ # Path for links to Boost logo.
+ #<xsl:param>boost.root=.. # already defined
+ <xsl:param>boost.image=Boost # options are: none (no logo), Boost (for boost.png), or your own logo, for example, inspired_by_boost.png
+ <xsl:param>boost.image.src=./images/boost.png #
+ <xsl:param>boost.image.w=180 # Width of logo in pixels. (JM has W = 162, h = 46)
+ <xsl:param>boost.image.h=90 # Height of logo in pixels.
- # Options for html and pdf
- # ========================
- # No indent on body text:
- <xsl:param>body.start.indent=0pt
- # Margin size:
- <xsl:param>page.margin.inner=0.5in
- # Margin size:
- <xsl:param>page.margin.outer=0.5in
- # Yes, we want graphics for admonishments:
- <xsl:param>admon.graphics=1
+ # Options for html and pdf
+ # ========================
+ # No indent on body text:
+ <xsl:param>body.start.indent=0pt
+ # Margin size:
+ <xsl:param>page.margin.inner=0.5in
+ # Margin size:
+ <xsl:param>page.margin.outer=0.5in
+ # Yes, we want graphics for admonishments:
+ <xsl:param>admon.graphics=1
- # HTML options:
- # =============
- # Use graphics icons not text for navigation:
- <xsl:param>navig.graphics=1
- # How far down we chunk nested sections, basically all of them:
- <xsl:param>chunk.section.depth=2
- # Don't put the first section on the same page as the TOC itself:
- <xsl:param>chunk.first.sections=1
- # How far down sections get TOC's
- <xsl:param>toc.section.depth=4
- # Max depth in each TOC:
- <xsl:param>toc.max.depth=2
- # How far down we go with TOC's
- <xsl:param>generate.section.toc.level=10
- # Horizontal ? spacing in table cells.
- <format>html:<xsl:param>html.cellspacing=3 # pixels
- # Vertical spacing in table cells.
- <format>html:<xsl:param>html.cellpadding=5 # pixels
+ # HTML options:
+ # =============
+ # Use graphics icons not text for navigation:
+ <xsl:param>navig.graphics=1
+ # How far down we chunk nested sections, basically all of them:
+ <xsl:param>chunk.section.depth=2
+ # Don't put the first section on the same page as the TOC itself:
+ <xsl:param>chunk.first.sections=1
+ # How far down sections get TOC's
+ <xsl:param>toc.section.depth=4
+ # Max depth in each TOC:
+ <xsl:param>toc.max.depth=2
+ # How far down we go with TOC's
+ <xsl:param>generate.section.toc.level=10
+ # Horizontal ? spacing in table cells.
+ <format>html:<xsl:param>html.cellspacing=3 # pixels
+ # Vertical spacing in table cells.
+ <format>html:<xsl:param>html.cellpadding=5 # pixels
<format>html:<xsl:param>boost.max.id.part.length=40
- # PDF Options:
- # ============
- # TOC Generation: this is needed for FOP-0.9 and later:
- <format>pdf:<xsl:param>fop1.extensions=0
- # Or enable this if you're using XEP:
- <format>pdf:<xsl:param>xep.extensions=1
- # TOC generation: this is needed for FOP 0.2, but must not be set to zero for FOP-0.9!
- <format>pdf:<xsl:param>fop.extensions=0
- # No indent on body text:
- <xsl:param>body.start.indent=0pt
- # Margin size:
- <xsl:param>page.margin.inner=0.5in
- # Margin size:
- <xsl:param>page.margin.outer=0.5in
+ # PDF Options:
+ # ============
+ # TOC Generation: this is needed for FOP-0.9 and later:
+ <format>pdf:<xsl:param>fop1.extensions=0
+ # Or enable this if you're using XEP:
+ <format>pdf:<xsl:param>xep.extensions=1
+ # TOC generation: this is needed for FOP 0.2, but must not be set to zero for FOP-0.9!
+ <format>pdf:<xsl:param>fop.extensions=0
+ # No indent on body text:
+ <xsl:param>body.start.indent=0pt
+ # Margin size:
+ <xsl:param>page.margin.inner=0.5in
+ # Margin size:
+ <xsl:param>page.margin.outer=0.5in
- # Yes, we want graphics for admonishments:
- <xsl:param>admon.graphics=1
+ # Yes, we want graphics for admonishments:
+ <xsl:param>admon.graphics=1
- # Set these one for PDF generation *only*:
- # default png graphics are awful in PDF form,
- # better use SVG instead:
- #<format>pdf:<xsl:param>admon.graphics.extension=".svg"
- <format>pdf:<xsl:param>admon.graphics.extension=".png" # Only png images are available.
- <format>pdf:<xsl:param>admon.graphics.path=$(nav_images)/ # next, prev, note, tip ... for pdf.
- <format>pdf:<xsl:param>use.role.for.mediaobject=1
- <format>pdf:<xsl:param>preferred.mediaobject.role=print
- <format>pdf:<xsl:param>img.src.path=$(images_location)/ # graphics (diagrams) for pdf.
- <format>pdf:<xsl:param>draft.mode="no"
- <format>pdf:<xsl:param>boost.url.prefix=I:/boost-sandbox/guild/pool/libs/pool/doc/html
+ # Set these one for PDF generation *only*:
+ # default png graphics are awful in PDF form,
+ # better use SVG instead:
+ #<format>pdf:<xsl:param>admon.graphics.extension=".svg"
+ <format>pdf:<xsl:param>admon.graphics.extension=".png" # Only png images are available.
+ <format>pdf:<xsl:param>admon.graphics.path=$(nav_images)/ # next, prev, note, tip ... for pdf.
+ <format>pdf:<xsl:param>use.role.for.mediaobject=1
+ <format>pdf:<xsl:param>preferred.mediaobject.role=print
+ <format>pdf:<xsl:param>img.src.path=$(images_location)/ # graphics (diagrams) for pdf.
+ <format>pdf:<xsl:param>draft.mode="no"
+ <format>pdf:<xsl:param>boost.url.prefix=I:/boost-sandbox/guild/pool/libs/pool/doc/html
- <dependency>autodoc #
- <dependency>css-install
- <dependency>png-install
- <dependency>svg-install
- <dependency>pool-png-install
- <dependency>pool-svg-install
+ <dependency>autodoc #
+ <dependency>css-install
+ <dependency>png-install
+ <dependency>svg-install
+ <dependency>pool-png-install
+ <dependency>pool-svg-install
;
path-constant boost-root : [ modules.peek : BOOST ] ;
==============================================================================
Binary files. No diff available.
==============================================================================
--- sandbox/guild/pool/libs/pool/doc/pool.qbk (original)
+++ sandbox/guild/pool/libs/pool/doc/pool.qbk 2011-04-11 12:10:36 EDT (Mon, 11 Apr 2011)
@@ -44,23 +44,22 @@
[def __pool_simple_segregated_storage [link boost_pool.pool.pooling.simple Simple Segregated Storage]]
[def __todo [link boost_pool.appendices.todo TODO]]
+[def __UserAllocator [link boost_pool.pool.pooling.user_allocator UserAllocator]]
[template mu[]'''μ'''] [/ µ Greek small letter mu]
[template plusminus[]'''±'''] [/ plus or minus sign]
-[template graphic[name] '''<inlinemediaobject>
+[template graphic[name]
+'''
+<inlinemediaobject>
<imageobject role="html">
-<imagedata align="center" fileref="./images/'''[name]'''.png"></imagedata>
+<imagedata align="center" fileref="../images/'''[name]'''.png"></imagedata>
</imageobject>
<imageobject role="print">
-<imagedata align="center" fileref="./images/'''[name]'''.svg"></imagedata>
-</imageobject>
-
-<imageobject role="pdf">
-<imagedata align="center" fileref="/images/'''[name]'''.svg"></imagedata>
+<imagedata align="center" fileref="../images/'''[name]'''.svg"></imagedata>
</imageobject>
-
-</inlinemediaobject>''']
+</inlinemediaobject>
+''']
[section:pool Boost Pool Library]
@@ -146,6 +145,23 @@
[endsect] [/section:usage How do I use Pool?]
+[section:installation Installation]
+
+The Boost Pool library is a header-only 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!
+
+[endsect] [/section:installation Installation]
+
+[section:testing Building the Test Programs]
+
+A jamfile.v2 is provided which can be run is the usual way, for example:
+
+``boost\libs\pool\test> bjam -a >pool_test.log``
+
+[endsect] [/section:testing Building the Test Programs]
+
[section:interfaces Boost Pool Interfaces - What interfaces are provided and when to use each one.]
[h4 Introduction]
@@ -176,25 +192,27 @@
[h5 Ordered versus unordered]
-Unordered segregates the memory block specified by block of size `sz` bytes into
-partition_sz-sized chunks, and adds that free list to its own. Only if the block was
-empty before the call is the block ordered.
-
-Ordered segregates the memory block specified by block of size `sz` bytes into
-partition_sz-sized chunks, and merges that free list into its own,
-so that the order is preserved.
+An ordered pool maintains it's free list in order of the address of each free block -
+this is the most efficient way if you're likely to allocate arrays of objects.
+However, freeing an object can be O(N) in the number of currently free blocks which
+can be prohibitively expensive in some situations.
+
+An unordered pool does not maintain it's free list in any particular order, as a result
+allocation and freeing single objects is very fast, but allocating arrays may be slow
+(and in particular the pool may not be aware that it contains enough free memory for the
+allocation request, and unnecessarily allocate more memory).
[section:interfaces Pool Interfaces]
[section:pool pool]
-The [classref boost::pool::pool pool]
+The [classref boost::pool pool]
interface is a simple Object Usage interface with Null Return.
-[classref boost::pool::pool pool] is a fast memory allocator,
+[classref boost::pool pool] is a fast memory allocator,
and guarantees proper alignment of all allocated chunks.
-[headerref boost/pool/pool.hpp pool.hpp] provides two UserAllocator classes
+[headerref boost/pool/pool.hpp pool.hpp] provides two __UserAllocator classes
and a [classref boost::pool template class pool],
which extends and generalizes the framework provided by the
__pool_simple_segregated_storage solution.
@@ -202,10 +220,10 @@
[*Synopsis]
-There are two `UserAllocator` classes provided.
+There are two __UserAllocator classes provided.
Both of them are in [headerref boost/pool/pool.hpp pool.hpp].
-The default value for the template parameter `UserAllocator` is always
+The default value for the template parameter __UserAllocator is always
`default_user_allocator_new_delete`.
``
@@ -231,9 +249,6 @@
{ std::free(block); }
};
- struct default_user_allocator_new_delete; // see User Allocators
- struct default_user_allocator_malloc_free; // see User Allocators
-
template <typename UserAllocator = default_user_allocator_new_delete>
class pool
{
@@ -265,6 +280,7 @@
void ordered_free(void * chunks, size_type n);
};
``
+
[*Example:]
``
void func()
@@ -277,6 +293,7 @@
}
} // on function exit, p is destroyed, and all malloc()'ed ints are implicitly freed.
``
+
[endsect] [/section pool]
@@ -331,7 +348,7 @@
['UserAllocator]
Defines the method that the underlying Pool will use to allocate memory from the system.
-Default is default_user_allocator_new_delete. See User Allocators for details.
+Default is default_user_allocator_new_delete. See ____UserAllocator for details.
[*Example:]
struct X { ... }; // has destructor with side-effects.
@@ -553,6 +570,7 @@
See User Allocators for details.
[*Example:]
+
void func()
{
std::vector<int, boost::pool_allocator<int> > v;
@@ -569,23 +587,6 @@
[endsect] [/section:interfaces- What interfaces are provided and when to use each one.]
-[section:installation Installation]
-
-The Boost Pool library is a header-only 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!
-
-[endsect] [/section:installation Installation]
-
-[section:testing Building the Test Programs]
-
-A jamfile.v2 is provided which can be run is the usual way, for example:
-
-``boost\libs\pool\test> bjam -a >pool_test.log``
-
-[endsect] [/section:testing Building the Test Programs]
-
[section:pooling Pool in More Depth]
[section:concepts Basic ideas behind pooling]
@@ -859,13 +860,6 @@
[graphic mb2]
-Finally, here is a convoluted example where the requested_size is 7,
-`sizeof(void *) == 3, and sizeof(size_type) == 5`,
-showing how the least common multiple guarantees alignment requirements
-even in the oddest of circumstances:
-
-[graphic mb3]
-
[section:chunks How Contiguous Chunks are Handled]
The theorem above guarantees all alignment requirements for allocating chunks