mirror of
https://github.com/boostorg/pool.git
synced 2026-01-23 17:52:15 +00:00
143 lines
7.9 KiB
HTML
143 lines
7.9 KiB
HTML
<!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>
|
|
|
|
<IMG SRC="../../../../c++boost.gif" WIDTH=276 HEIGHT=86 ALT="C++ Boost">
|
|
|
|
<H1 ALIGN=CENTER>Pool</H1>
|
|
|
|
<P>
|
|
<H2>Introduction</H2>
|
|
|
|
<P>
|
|
<SPAN CLASS="code">pool</SPAN> is a fast memory allocator, and guarantees proper alignment of all allocated chunks.
|
|
|
|
<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>
|
|
|
|
<P>
|
|
<H2>Template Parameters</H2>
|
|
|
|
<P>
|
|
<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>
|
|
|
|
<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<UserAllocator>
|
|
<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>
|
|
|
|
<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>
|
|
|
|
<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">(&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>
|
|
|
|
<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>
|
|
|
|
<P>
|
|
<H2>Symbols</H2>
|
|
|
|
<P>
|
|
<UL>
|
|
<LI>boost::default_user_allocator_new_delete</LI>
|
|
<LI>boost::default_user_allocator_malloc_new</LI>
|
|
<LI>boost::pool</LI>
|
|
</UL>
|
|
|
|
<P>
|
|
<H2><A HREF="../implementation/pool.html">Implementation Details</A></H2>
|
|
|
|
<P>
|
|
<HR>
|
|
|
|
<P>
|
|
Copyright © 2000, 2001 Stephen Cleary (<A HREF="mailto:shammah@voyager.net">shammah@voyager.net</A>)
|
|
|
|
<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 "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.
|
|
|
|
</BODY>
|
|
</HTML> |