mirror of
https://github.com/boostorg/pool.git
synced 2026-01-25 06:22:14 +00:00
202 lines
8.4 KiB
HTML
202 lines
8.4 KiB
HTML
<!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>
|
|
|
|
<IMG SRC="../../../../c++boost.gif" WIDTH=276 HEIGHT=86 ALT="C++ Boost">
|
|
|
|
<H1 ALIGN=CENTER>pool_alloc - Boost Pool Standard Allocators</H1>
|
|
|
|
<P>
|
|
<H2>Introduction</H2>
|
|
|
|
<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 <typename T,
|
|
typename UserAllocator = default_user_allocator_new_delete>
|
|
class pool_allocator
|
|
{
|
|
public:
|
|
typedef UserAllocator user_allocator;
|
|
typedef T value_type;
|
|
typedef value_type * pointer;
|
|
typedef const value_type * const_pointer;
|
|
typedef value_type & reference;
|
|
typedef const value_type & const_reference;
|
|
typedef typename pool<UserAllocator>::size_type size_type;
|
|
typedef typename pool<UserAllcoator>::difference_type difference_type;
|
|
|
|
template <typename U>
|
|
struct rebind
|
|
{ typedef pool_allocator<U, UserAllocator> other; };
|
|
|
|
public:
|
|
pool_allocator();
|
|
pool_allocator(const pool_allocator &);
|
|
// The following is not explicit, mimicking std::allocator [20.4.1]
|
|
template <typename U>
|
|
pool_allocator(const pool_allocator<U, UserAllocator> &);
|
|
pool_allocator & operator=(const pool_allocator &);
|
|
~pool_allocator();
|
|
|
|
static pointer address(reference r);
|
|
static const_pointer address(const_reference s);
|
|
static size_type max_size();
|
|
static void construct(pointer ptr, const value_type & t);
|
|
static void destroy(pointer ptr);
|
|
|
|
bool operator==(const pool_allocator &) const;
|
|
bool operator!=(const pool_allocator &) const;
|
|
|
|
static pointer allocate(size_type n);
|
|
static pointer allocate(size_type n, pointer);
|
|
static void deallocate(pointer ptr, size_type n);
|
|
};
|
|
|
|
struct fast_pool_allocator_tag { };
|
|
|
|
template <typename T
|
|
typename UserAllocator = default_user_allocator_new_delete>
|
|
class fast_pool_allocator
|
|
{
|
|
public:
|
|
typedef UserAllocator user_allocator;
|
|
typedef T value_type;
|
|
typedef value_type * pointer;
|
|
typedef const value_type * const_pointer;
|
|
typedef value_type & reference;
|
|
typedef const value_type & const_reference;
|
|
typedef typename pool<UserAllocator>::size_type size_type;
|
|
typedef typename pool<UserAllocator>::difference_type difference_type;
|
|
|
|
template <typename U>
|
|
struct rebind
|
|
{ typedef fast_pool_allocator<U, UserAllocator> other; };
|
|
|
|
public:
|
|
fast_pool_allocator();
|
|
fast_pool_allocator(const fast_pool_allocator &);
|
|
// The following is not explicit, mimicking std::allocator [20.4.1]
|
|
template <typename U>
|
|
fast_pool_allocator(const fast_pool_allocator<U, UserAllocator> &);
|
|
fast_pool_allocator & operator=(const fast_pool_allocator &);
|
|
~fast_pool_allocator();
|
|
|
|
static pointer address(reference r);
|
|
static const_pointer address(const_reference s);
|
|
static size_type max_size();
|
|
static void construct(pointer ptr, const value_type & t);
|
|
static void destroy(pointer ptr);
|
|
|
|
bool operator==(const fast_pool_allocator &) const;
|
|
bool operator!=(const fast_pool_allocator &) const;
|
|
|
|
static pointer allocate(size_type n);
|
|
static pointer allocate(size_type n, pointer);
|
|
static void deallocate(pointer ptr, size_type n);
|
|
|
|
static pointer allocate();
|
|
static void deallocate(pointer ptr);
|
|
};</PRE>
|
|
|
|
<P>
|
|
<H2>Template Parameters</H2>
|
|
|
|
<P>
|
|
<H3>T</H3>
|
|
|
|
<P>
|
|
The first template parameter is the type of object to allocate/deallocate.
|
|
|
|
<P>
|
|
<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>
|
|
<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>
|
|
In addition, the <SPAN CLASS="code">fast_pool_allocator</SPAN> also provides an additional allocation and an additional deallocation function:
|
|
|
|
<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<T, UserAllocator></SPAN>
|
|
<TR><TD CLASS="code">p<TD>value of type <SPAN CLASS="code">T *</SPAN>
|
|
</TABLE>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
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>
|
|
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<int></SPAN> and <SPAN CLASS="code">pool_allocator<void *></SPAN> will both allocate/deallocate from/to the same pool.
|
|
|
|
<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>
|
|
|
|
<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>
|
|
|
|
<P>
|
|
<H2><A HREF="../implementation/pool_alloc.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> |