mirror of
https://github.com/boostorg/pool.git
synced 2026-01-23 17:52:15 +00:00
d88008b987
that use it are valid. Merged revisions 53047-53048 via svnmerge from https://svn.boost.org/svn/boost/trunk ........ r53047 | danieljames | 2009-05-16 15:17:20 +0100 (Sat, 16 May 2009) | 1 line Fix some validation errors. ........ r53048 | danieljames | 2009-05-16 15:23:59 +0100 (Sat, 16 May 2009) | 1 line Use a local copy of the valid HTML 4.01 icon. ........ [SVN r53258]
380 lines
10 KiB
HTML
380 lines
10 KiB
HTML
<!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</title>
|
|
</head>
|
|
|
|
<body>
|
|
<img src="../../../../boost.png" width="276" height="86" alt="C++ Boost">
|
|
|
|
<h1 align="center">Pool</h1>
|
|
|
|
<h2>Introduction</h2>
|
|
|
|
<p><span class="code">pool</span> is a fast memory allocator, and
|
|
guarantees proper alignment of all allocated chunks.</p>
|
|
|
|
<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 <typename UserAllocator = default_user_allocator_new_delete>
|
|
class pool
|
|
{
|
|
private:
|
|
pool(const pool &);
|
|
void operator=(const pool &);
|
|
|
|
public:
|
|
typedef UserAllocator user_allocator;
|
|
typedef typename UserAllocator::size_type size_type;
|
|
typedef typename UserAllocator::difference_type difference_type;
|
|
|
|
explicit pool(size_type requested_size);
|
|
~pool();
|
|
|
|
bool release_memory();
|
|
bool purge_memory();
|
|
|
|
bool is_from(void * chunk) const;
|
|
size_type get_requested_size() const;
|
|
|
|
void * malloc();
|
|
void * ordered_malloc();
|
|
void * ordered_malloc(size_type n);
|
|
|
|
void free(void * chunk);
|
|
void ordered_free(void * chunk);
|
|
void free(void * chunks, size_type n);
|
|
void ordered_free(void * chunks, size_type n);
|
|
};
|
|
</pre>
|
|
|
|
<h2>Template Parameters</h2>
|
|
|
|
<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>
|
|
|
|
<h2>Semantics</h2>
|
|
|
|
<table border align="center" summary="">
|
|
<caption>
|
|
<em>Symbol Table</em>
|
|
</caption>
|
|
|
|
<tr>
|
|
<th>Symbol</th>
|
|
|
|
<th>Meaning</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="code">Pool</td>
|
|
|
|
<td class="code">pool<UserAllocator></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="code">t</td>
|
|
|
|
<td>value of type <span class="code">Pool</span></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="code">u</td>
|
|
|
|
<td>value of type <span class="code">const Pool</span></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="code">chunk</td>
|
|
|
|
<td>value of type <span class="code">void *</span></td>
|
|
</tr>
|
|
|
|
<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">(&t)->~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=
|
|
"../../../../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 <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>
|