boost_1_45_0/libs/pool/doc/interfaces/pool_alloc.html - nest-learning-thermostat/5.0/boost - Git at Google

 <!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_alloc - Boost Pool Standard Allocators</title>
 </head>

 <body>
   <img src="../../../../boost.png" width="276" height="86" alt="C++ Boost">

   <h1 align="center">pool_alloc - Boost Pool Standard Allocators</h1>

   <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 &lt;typename T,
     typename UserAllocator = default_user_allocator_new_delete&gt;
 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 &amp; reference;
     typedef const value_type &amp; const_reference;
     typedef typename pool&lt;UserAllocator&gt;::size_type size_type;
     typedef typename pool&lt;UserAllcoator&gt;::difference_type difference_type;

     template &lt;typename U&gt;
     struct rebind
     { typedef pool_allocator&lt;U, UserAllocator&gt; other; };

   public:
     pool_allocator();
     pool_allocator(const pool_allocator &amp;);
     // The following is not explicit, mimicking std::allocator [20.4.1]
     template &lt;typename U&gt;
     pool_allocator(const pool_allocator&lt;U, UserAllocator&gt; &amp;);
     pool_allocator &amp; operator=(const pool_allocator &amp;);
     ~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 &amp; t);
     static void destroy(pointer ptr);

     bool operator==(const pool_allocator &amp;) const;
     bool operator!=(const pool_allocator &amp;) 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 &lt;typename T
     typename UserAllocator = default_user_allocator_new_delete&gt;
 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 &amp; reference;
     typedef const value_type &amp; const_reference;
     typedef typename pool&lt;UserAllocator&gt;::size_type size_type;
     typedef typename pool&lt;UserAllocator&gt;::difference_type difference_type;

     template &lt;typename U&gt;
     struct rebind
     { typedef fast_pool_allocator&lt;U, UserAllocator&gt; other; };

   public:
     fast_pool_allocator();
     fast_pool_allocator(const fast_pool_allocator &amp;);
     // The following is not explicit, mimicking std::allocator [20.4.1]
     template &lt;typename U&gt;
     fast_pool_allocator(const fast_pool_allocator&lt;U, UserAllocator&gt; &amp;);
     fast_pool_allocator &amp; operator=(const fast_pool_allocator &amp;);
     ~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 &amp; t);
     static void destroy(pointer ptr);

     bool operator==(const fast_pool_allocator &amp;) const;
     bool operator!=(const fast_pool_allocator &amp;) 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>

   <h2>Template Parameters</h2>

   <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>

   <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" summary="">
     <caption>
       <em>Symbol Table</em>
     </caption>

     <tr>
       <th>Symbol</th>

       <th>Meaning</th>
     </tr>

     <tr>
       <td class="code">PoolAlloc</td>

       <td><span class="code">fast_pool_allocator&lt;T,
       UserAllocator&gt;</span></td>
     </tr>

     <tr>
       <td class="code">p</td>

       <td>value of type <span class="code">T *</span></td>
     </tr>
   </table><br>

   <table border align="center" summary="">
     <caption>
       <em>Additional allocation/deallocation functions (<span class=
       "code">fast_pool_allocator</span> only)</em>
     </caption>

     <tr>
       <th>Expression</th>

       <th>Return Type</th>

       <th>Semantic Equivalence</th>
     </tr>

     <tr>
       <td class="code">PoolAlloc::allocate()</td>

       <td class="code">T *</td>

       <td class="code">PoolAlloc::allocate(1)</td>
     </tr>

     <tr>
       <td class="code">PoolAlloc::deallocate(p)</td>

       <td>void</td>

       <td class="code">PoolAlloc::deallocate(p, 1)</td>
     </tr>
   </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>

   <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=
   "../../../../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 &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>
	<!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_alloc - Boost Pool Standard Allocators</title>
	</head>

	<body>
	<img src="../../../../boost.png" width="276" height="86" alt="C++ Boost">

	<h1 align="center">pool_alloc - Boost Pool Standard Allocators</h1>

	<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>

	<h2>Template Parameters</h2>

	<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>

	<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" summary="">
	<caption>
	<em>Symbol Table</em>
	</caption>

	<tr>
	<th>Symbol</th>

	<th>Meaning</th>
	</tr>

	<tr>
	<td class="code">PoolAlloc</td>

	<td><span class="code">fast_pool_allocator<T,
	UserAllocator></span></td>
	</tr>

	<tr>
	<td class="code">p</td>

	<td>value of type <span class="code">T *</span></td>
	</tr>
	</table><br>

	<table border align="center" summary="">
	<caption>
	<em>Additional allocation/deallocation functions (<span class=
	"code">fast_pool_allocator</span> only)</em>
	</caption>

	<tr>
	<th>Expression</th>

	<th>Return Type</th>

	<th>Semantic Equivalence</th>
	</tr>

	<tr>
	<td class="code">PoolAlloc::allocate()</td>

	<td class="code">T *</td>

	<td class="code">PoolAlloc::allocate(1)</td>
	</tr>

	<tr>
	<td class="code">PoolAlloc::deallocate(p)</td>

	<td>void</td>

	<td class="code">PoolAlloc::deallocate(p, 1)</td>
	</tr>
	</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>

	<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<int></span> and <span class=
	"code">pool_allocator<void *></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=
	"../../../../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>