|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r54577 - in sandbox/monotonic/libs/monotonic/doc: . html html/monotonic_storage html/monotonic_storage/tutorial
From: christian.schladetsch_at_[hidden]
Date: 2009-07-02 01:19:45
Author: cschladetsch
Date: 2009-07-02 01:19:43 EDT (Thu, 02 Jul 2009)
New Revision: 54577
URL: http://svn.boost.org/trac/boost/changeset/54577
Log:
added quickbook-based docs
Added:
sandbox/monotonic/libs/monotonic/doc/
sandbox/monotonic/libs/monotonic/doc/Jamfile.v2 (contents, props changed)
sandbox/monotonic/libs/monotonic/doc/html/
sandbox/monotonic/libs/monotonic/doc/html/index.html (contents, props changed)
sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/
sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/change_log.html (contents, props changed)
sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/intro.html (contents, props changed)
sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial/
sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial.html (contents, props changed)
sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial/basic_usage.html (contents, props changed)
sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial/using_monotonic_storage.html (contents, props changed)
sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial/using_multiple_containers.html (contents, props changed)
sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial/using_regions.html (contents, props changed)
sandbox/monotonic/libs/monotonic/doc/html/standalone_HTML.manifest (contents, props changed)
sandbox/monotonic/libs/monotonic/doc/monotonic.qbk (contents, props changed)
Added: sandbox/monotonic/libs/monotonic/doc/Jamfile.v2
==============================================================================
--- (empty file)
+++ sandbox/monotonic/libs/monotonic/doc/Jamfile.v2 2009-07-02 01:19:43 EDT (Thu, 02 Jul 2009)
@@ -0,0 +1,24 @@
+project boost/monotonic/doc ;
+
+import boostbook : boostbook ;
+using quickbook ;
+
+xml monotonic : monotonic.qbk ;
+
+path-constant images : ../../../doc/html ;
+
+boostbook standalone
+ :
+ monotonic
+ :
+ <xsl:param>boost.root=../../../..
+ <xsl:param>boost.libraries=../../../../libs/libraries.htm
+ <xsl:param>html.stylesheet=../../../../doc/html/boostbook.css
+ <xsl:param>generate.section.toc.level=3
+ <xsl:param>chunk.section.depth=2
+ <xsl:param>chunk.first.sections=1
+
+ #<xsl:param>callout.graphics.path=../../images/callouts//
+ <format>pdf:<xsl:param>img.src.path=$(images)/
+ <format>pdf:<xsl:param>boost.url.prefix=http://www.boost.org/doc/libs/release/doc/html
+ ;
Added: sandbox/monotonic/libs/monotonic/doc/html/index.html
==============================================================================
--- (empty file)
+++ sandbox/monotonic/libs/monotonic/doc/html/index.html 2009-07-02 01:19:43 EDT (Thu, 02 Jul 2009)
@@ -0,0 +1,63 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Monotonic Storage 0.3</title>
+<link rel="stylesheet" href="../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
+<link rel="home" href="index.html" title="Monotonic Storage 0.3">
+<link rel="next" href="monotonic_storage/intro.html" title="Introduction">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav"><a accesskey="n" href="monotonic_storage/intro.html"><img src="../../../../doc/html/images/next.png" alt="Next"></a></div>
+<div class="article" title="Monotonic Storage 0.3">
+<div class="titlepage">
+<div>
+<div><h2 class="title">
+<a name="monotonic_storage"></a>Monotonic Storage 0.3</h2></div>
+<div><div class="authorgroup"><div class="author"><h3 class="author">
+<span class="firstname">Christian</span> <span class="surname">Schladetsch</span>
+</h3></div></div></div>
+<div><p class="copyright">Copyright © 2009 Christian Schladetsch</p></div>
+<div><div class="legalnotice" title="Legal Notice">
+<a name="id670245"></a><p>
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ </p>
+</div></div>
+</div>
+<hr>
+</div>
+<div class="toc">
+<p><b>Table of Contents</b></p>
+<dl>
+<dt><span class="section"> Introduction</span></dt>
+<dt><span class="section"> Change Log</span></dt>
+<dt><span class="section"> Tutorial</span></dt>
+<dd><dl>
+<dt><span class="section">Basic Usage</span></dt>
+<dt><span class="section"><a href="monotonic_storage/tutorial/using_multiple_containers.html">Using
+ Multiple Containers</a></span></dt>
+<dt><span class="section">Using Regions</span></dt>
+<dt><span class="section"><a href="monotonic_storage/tutorial/using_monotonic_storage.html">Using
+ Monotonic Storage</a></span></dt>
+</dl></dd>
+</dl>
+</div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"><p><small>Last revised: July 02, 2009 at 05:12:25 GMT</small></p></td>
+<td align="right"><div class="copyright-footer"></div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav"><a accesskey="n" href="monotonic_storage/intro.html"><img src="../../../../doc/html/images/next.png" alt="Next"></a></div>
+</body>
+</html>
Added: sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/change_log.html
==============================================================================
--- (empty file)
+++ sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/change_log.html 2009-07-02 01:19:43 EDT (Thu, 02 Jul 2009)
@@ -0,0 +1,57 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Change Log</title>
+<link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
+<link rel="home" href="../index.html" title="Monotonic Storage 0.3">
+<link rel="up" href="../index.html" title="Monotonic Storage 0.3">
+<link rel="prev" href="intro.html" title="Introduction">
+<link rel="next" href="tutorial.html" title="Tutorial">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="intro.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="tutorial.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" title="Change Log">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="monotonic_storage.change_log"></a><a class="link" href="change_log.html" title="Change Log"> Change Log</a>
+</h2></div></div></div>
+<a name="monotonic_storage.change_log.version_0_4"></a><h4>
+<a name="id670351"></a>
+ <a class="link" href="change_log.html#monotonic_storage.change_log.version_0_4">Version 0.4</a>
+ </h4>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ Added reclaimable storage
+ </li></ul></div>
+<a name="monotonic_storage.change_log.version_0_3"></a><h4>
+<a name="id670371"></a>
+ <a class="link" href="change_log.html#monotonic_storage.change_log.version_0_3">Version 0.3</a>
+ </h4>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ Added region- and access-tags.
+ </li></ul></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2009 Christian Schladetsch<p>
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="intro.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="tutorial.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Added: sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/intro.html
==============================================================================
--- (empty file)
+++ sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/intro.html 2009-07-02 01:19:43 EDT (Thu, 02 Jul 2009)
@@ -0,0 +1,90 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Introduction</title>
+<link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
+<link rel="home" href="../index.html" title="Monotonic Storage 0.3">
+<link rel="up" href="../index.html" title="Monotonic Storage 0.3">
+<link rel="prev" href="../index.html" title="Monotonic Storage 0.3">
+<link rel="next" href="change_log.html" title="Change Log">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../index.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="change_log.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" title="Introduction">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="monotonic_storage.intro"></a><a class="link" href="intro.html" title="Introduction"> Introduction</a>
+</h2></div></div></div>
+<p>
+ The <span class="bold"><strong>Boost.Monotonic</strong></span> library provides storage,
+ allocation and container types for use in high-performance and real-time applications.
+ </p>
+<p>
+ The library provides a means for allocation to come from the stack, or the
+ heap, or a combination of both the stack and the heap. Allocation is fast,
+ because de-allocation does nothing. As such, the amount of storage used by
+ a monotonic allocator can only ever increase - hence the name of the library.
+ </p>
+<p>
+ Allocation can be <span class="emphasis"><em>regionalised</em></span> by application of user-supplied
+ 'tag types' to specify a logical storage region. A second tag may be used to
+ specify the <span class="emphasis"><em>access type</em></span> for the region - which can be
+ either global, guarded by a mutex, or using thread-local storage.
+ </p>
+<p>
+ <span class="bold"><strong>Boost.Monotonic</strong></span> is generally used where performace
+ is a key concern. By making deallocation a no-op, allocation of memory resources
+ is extremely fast. In general, the programmer is required to release storage
+ used at an appropriate time, however local scoping systems are provided by
+ the library for the most common use cases.
+ </p>
+<p>
+ Features include:
+ </p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem">
+ fast allocation from the stack
+ </li>
+<li class="listitem">
+ automatic extension to the heap as needed
+ </li>
+<li class="listitem">
+ storage can be segmented into independant regions
+ </li>
+<li class="listitem">
+ support for thread-safe storage, and thread-local storage
+ </li>
+<li class="listitem">
+ storage can be accessed directly, providing a 'first-class stack' system
+ </li>
+<li class="listitem">
+ containers that can use storage from the stack, from the heap, or both the
+ stack and the heap
+ </li>
+</ul></div>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2009 Christian Schladetsch<p>
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../index.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="change_log.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Added: sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial.html
==============================================================================
--- (empty file)
+++ sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial.html 2009-07-02 01:19:43 EDT (Thu, 02 Jul 2009)
@@ -0,0 +1,58 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Tutorial</title>
+<link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
+<link rel="home" href="../index.html" title="Monotonic Storage 0.3">
+<link rel="up" href="../index.html" title="Monotonic Storage 0.3">
+<link rel="prev" href="change_log.html" title="Change Log">
+<link rel="next" href="tutorial/basic_usage.html" title="Basic Usage">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="change_log.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="tutorial/basic_usage.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" title="Tutorial">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="monotonic_storage.tutorial"></a><a class="link" href="tutorial.html" title="Tutorial"> Tutorial</a>
+</h2></div></div></div>
+<div class="toc"><dl>
+<dt><span class="section">Basic Usage</span></dt>
+<dt><span class="section"><a href="tutorial/using_multiple_containers.html">Using
+ Multiple Containers</a></span></dt>
+<dt><span class="section">Using Regions</span></dt>
+<dt><span class="section"><a href="tutorial/using_monotonic_storage.html">Using
+ Monotonic Storage</a></span></dt>
+</dl></div>
+<p>
+ This tutorial progresses through the basic usage of the library, demonstrating
+ how to use a monotonic allocator with STL containers, how to use monotonic
+ storage directly without an allocator, how to use regions and access tags,
+ and finally demonstrates the use of the supplied container library with stack-based
+ local storage.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2009 Christian Schladetsch<p>
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="change_log.html"><img src="../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="tutorial/basic_usage.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Added: sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial/basic_usage.html
==============================================================================
--- (empty file)
+++ sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial/basic_usage.html 2009-07-02 01:19:43 EDT (Thu, 02 Jul 2009)
@@ -0,0 +1,90 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Basic Usage</title>
+<link rel="stylesheet" href="../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
+<link rel="home" href="../../index.html" title="Monotonic Storage 0.3">
+<link rel="up" href="../tutorial.html" title="Tutorial">
+<link rel="prev" href="../tutorial.html" title="Tutorial">
+<link rel="next" href="using_multiple_containers.html" title="Using Multiple Containers">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../tutorial.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorial.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="using_multiple_containers.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" title="Basic Usage">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="monotonic_storage.tutorial.basic_usage"></a><a class="link" href="basic_usage.html" title="Basic Usage">Basic Usage</a>
+</h3></div></div></div>
+<p>
+ The following is a very quick introduction to <span class="bold"><strong>Boost.Monotonic</strong></span>:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">monotonic</span><span class="special">/</span><span class="identifier">allocator</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
+
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">;</span>
+
+<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
+<span class="special">{</span>
+ <span class="special">{</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">monotonic</span><span class="special">::</span><span class="identifier">allocator</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span> <span class="special">></span> <span class="identifier">list</span><span class="special">;</span>
+ <span class="keyword">for</span> <span class="special">(</span><span class="identifier">size_t</span> <span class="identifier">n</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">n</span> <span class="special"><</span> <span class="number">1000</span><span class="special">;</span> <span class="special">++</span><span class="identifier">n</span><span class="special">)</span>
+ <span class="identifier">list</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">n</span><span class="special">);</span>
+ <span class="special">}</span>
+ <span class="identifier">monotonic</span><span class="special">::</span><span class="identifier">static_storage</span><span class="special"><>::</span><span class="identifier">release</span><span class="special">();</span>
+ <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
+<span class="special">}</span>
+</pre>
+<p>
+ </p>
+<p>
+ Here we have created a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span></code>
+ using a monotonic allocator. While we add new elements to the list in the
+ for-loop, allocation is coming from storage in the default region with default
+ access. The first 32k of allocation will come from the BSS segment embedded
+ in the application image (the amount of such storage is configurable), then
+ once that local storage is exhausted, later allocation requests will be serviced
+ from the heap. Since de-allocation does nothing in a monotonic allocator,
+ we must manually release the resources once we are finished, as shown above.
+ </p>
+<p>
+ While this example is trivial, if you were to benchmark it against using
+ a default <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">allocator</span></code> you will find that monotonic
+ allocation is much faster[1].
+ </p>
+<p>
+ This is one of the main reasons for using this library; to provide efficient
+ storage and allocation for temporary containers.
+ </p>
+<p>
+ We shall now move on to some more interesting examples, including how to
+ use multiple containers that share the same strorage, using regions, using
+ local stack-based storage, and dealing with threading issues.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2009 Christian Schladetsch<p>
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="../tutorial.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorial.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="using_multiple_containers.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Added: sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial/using_monotonic_storage.html
==============================================================================
--- (empty file)
+++ sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial/using_monotonic_storage.html 2009-07-02 01:19:43 EDT (Thu, 02 Jul 2009)
@@ -0,0 +1,99 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Using Monotonic Storage</title>
+<link rel="stylesheet" href="../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
+<link rel="home" href="../../index.html" title="Monotonic Storage 0.3">
+<link rel="up" href="../tutorial.html" title="Tutorial">
+<link rel="prev" href="using_regions.html" title="Using Regions">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="using_regions.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorial.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a>
+</div>
+<div class="section" title="Using Monotonic Storage">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="monotonic_storage.tutorial.using_monotonic_storage"></a><a class="link" href="using_monotonic_storage.html" title="Using Monotonic Storage">Using
+ Monotonic Storage</a>
+</h3></div></div></div>
+<p>
+ While monotonic allocators use monotonic storage, we can also use this storage
+ directly and wherever we want efficient resource management.
+ </p>
+<p>
+ <code class="computeroutput"></code> int main() { <span class="emphasis"><em>/ define local storage of 4k on the
+ stack. /</em></span> allocations will use the heap after the inline stack-based
+ storage // has been exhausted. monotonic::storage<4*1024> storage;
+ { int &amp;num = storage.create<int>(); std::string &amp;str
+ = storage.create<std::string>(); char *bytes = storage.allocate_bytes(3000);
+ </p>
+<pre class="programlisting"><span class="comment">// use num, str, bytes as needed
+</span>
+<span class="comment">// call std::string's destructor directly, or use storage.destroy
+</span><span class="identifier">storage</span><span class="special">.</span><span class="identifier">destroy</span><span class="special">(</span><span class="identifier">str</span><span class="special">);</span>
+ <span class="special">}</span>
+ <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
+</pre>
+<p>
+ // use num, str, bytes as needed
+ </p>
+<pre class="programlisting"><span class="comment">// call std::string's destructor directly, or use storage.destroy
+</span><span class="identifier">storage</span><span class="special">.</span><span class="identifier">destroy</span><span class="special">(</span><span class="identifier">str</span><span class="special">);</span>
+ <span class="special">}</span>
+ <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
+</pre>
+<p>
+ // call std::string's destructor directly, or use storage.destroy storage.destroy(str);
+ } return 0; }
+ </p>
+<p>
+ Of course, we could have just made <code class="computeroutput"><span class="identifier">num</span></code>,
+ <code class="computeroutput"><span class="identifier">str</span></code> and <code class="computeroutput"><span class="identifier">bytes</span></code>
+ on the stack by declaring them as local variables and be done with it - well,
+ except for having a dynamically-sized array of bytes on the stack. There
+ is no other functional difference in this case, except that you are responsible
+ for invoking object destructors. So how is this at all useful?
+ </p>
+<p>
+ We can use <code class="computeroutput"><span class="identifier">monotonic</span><span class="special">::</span><span class="identifier">storage</span></code> as a form of "first-class
+ scope" which can be created, manipulated, passed as as argument, returned
+ as a value or reference, and destroyed as needed.
+ </p>
+<p>
+ In this sense, <code class="computeroutput"><span class="identifier">monotonic</span><span class="special">::</span><span class="identifier">storage</span></code>
+ is just like your very own C++ stack which you can share between objects
+ and functions and even across process boundaries, independantly of the underlying
+ machine-based stack.
+ </p>
+<p>
+ Also unlike the stack, storage will use the heap when its local inline stack-based
+ buffer is exhuasted. This makes it ideal for using things like local buffers
+ and containers that generally will be small enough to fit onto the stack,
+ but with the fallback safety of transparently using the heap to service later
+ requests for the cases where that inline buffer is not large enough.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2009 Christian Schladetsch<p>
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="using_regions.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorial.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a>
+</div>
+</body>
+</html>
Added: sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial/using_multiple_containers.html
==============================================================================
--- (empty file)
+++ sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial/using_multiple_containers.html 2009-07-02 01:19:43 EDT (Thu, 02 Jul 2009)
@@ -0,0 +1,87 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Using Multiple Containers</title>
+<link rel="stylesheet" href="../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
+<link rel="home" href="../../index.html" title="Monotonic Storage 0.3">
+<link rel="up" href="../tutorial.html" title="Tutorial">
+<link rel="prev" href="basic_usage.html" title="Basic Usage">
+<link rel="next" href="using_regions.html" title="Using Regions">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="basic_usage.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorial.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="using_regions.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" title="Using Multiple Containers">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="monotonic_storage.tutorial.using_multiple_containers"></a><a class="link" href="using_multiple_containers.html" title="Using Multiple Containers">Using
+ Multiple Containers</a>
+</h3></div></div></div>
+<p>
+ In this example, we create a map of ints to vectors of ints, with each container
+ using a monotonic allocator:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
+<span class="special">{</span>
+ <span class="special">{</span>
+ <span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">monotonic</span><span class="special">::</span><span class="identifier">allocator</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span> <span class="special">></span> <span class="identifier">Vector</span><span class="special">;</span>
+ <span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">Vector</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">less</span><span class="special"><</span><span class="keyword">int</span><span class="special">>,</span> <span class="identifier">monotonic</span><span class="special">::</span><span class="identifier">allocator</span><span class="special"><</span><span class="identifier">Vector</span><span class="special">></span> <span class="special">></span> <span class="identifier">Map</span><span class="special">;</span>
+ <span class="identifier">Map</span> <span class="identifier">map</span><span class="special">;</span>
+ <span class="keyword">for</span> <span class="special">(</span><span class="identifier">size_t</span> <span class="identifier">n</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">n</span> <span class="special"><</span> <span class="number">10000</span><span class="special">;</span> <span class="special">++</span><span class="identifier">n</span><span class="special">)</span>
+ <span class="special">{</span>
+ <span class="identifier">map</span><span class="special">[</span><span class="identifier">rand</span><span class="special">()%</span><span class="number">100</span><span class="special">].</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">n</span><span class="special">);</span>
+ <span class="special">}</span>
+ <span class="special">}</span>
+ <span class="identifier">monotonic</span><span class="special">::</span><span class="identifier">static_storage</span><span class="special"><>::</span><span class="identifier">release</span><span class="special">();</span>
+ <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+ </p>
+<p>
+ Again, storage will only ever increase, so we must release it after we have
+ finished using it.
+ </p>
+<p>
+ Benchmarking the performance of this against other allocation schemes[2]
+ show that monotonic allocation is extremely fast and efficient.
+ </p>
+<p>
+ The key point here is that you can use a <code class="computeroutput"><span class="identifier">monotonic</span><span class="special">::</span><span class="identifier">allocator</span></code>
+ anywhere that you would otherwise use a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">allocator</span></code>
+ or any other STL-compliant custom allocator. Monotonic allocators of the
+ same type are effectively stateless, and may be default-constructed, used,
+ and discarded as needed.
+ </p>
+<p>
+ We will deal with stateful monotonic allocators that can use local stack-based
+ storage in a later section.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2009 Christian Schladetsch<p>
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="basic_usage.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorial.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="using_regions.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Added: sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial/using_regions.html
==============================================================================
--- (empty file)
+++ sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial/using_regions.html 2009-07-02 01:19:43 EDT (Thu, 02 Jul 2009)
@@ -0,0 +1,119 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Using Regions</title>
+<link rel="stylesheet" href="../../../../../../doc/html/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
+<link rel="home" href="../../index.html" title="Monotonic Storage 0.3">
+<link rel="up" href="../tutorial.html" title="Tutorial">
+<link rel="prev" href="using_multiple_containers.html" title="Using Multiple Containers">
+<link rel="next" href="using_monotonic_storage.html" title="Using Monotonic Storage">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
+<td align="center">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="using_multiple_containers.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorial.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="using_monotonic_storage.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+<div class="section" title="Using Regions">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="monotonic_storage.tutorial.using_regions"></a><a class="link" href="using_regions.html" title="Using Regions">Using Regions</a>
+</h3></div></div></div>
+<p>
+ While it can be useful to have one storage area for all allocations, at times
+ will will want to segment our memory usage into different <span class="emphasis"><em>regions</em></span>.
+ This is done by passing a user-supplied <span class="emphasis"><em>region tag type</em></span>
+ to the type signature of a <code class="computeroutput"><span class="identifier">monotonic</span><span class="special">::</span><span class="identifier">allocator</span></code>,
+ as shown here:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">my_region_A</span> <span class="special">{</span> <span class="special">};</span>
+<span class="keyword">struct</span> <span class="identifier">my_region_B</span> <span class="special">{</span> <span class="special">};</span>
+
+<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
+<span class="special">{</span>
+ <span class="special">{</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">monotonic</span><span class="special">::</span><span class="identifier">allocator</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">my_region_A</span><span class="special">></span> <span class="special">></span> <span class="identifier">A_list</span><span class="special">;</span>
+ <span class="identifier">A_list</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">1</span><span class="special">);</span>
+ <span class="special">{</span>
+ <span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">monotonic</span><span class="special">::</span><span class="identifier">allocator</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">my_region_B</span><span class="special">></span> <span class="special">></span> <span class="identifier">B_list</span><span class="special">;</span>
+ <span class="identifier">B_list</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">2</span><span class="special">);</span>
+ <span class="special">}</span>
+ <span class="identifier">monotonic</span><span class="special">::</span><span class="identifier">static_storage</span><span class="special"><</span><span class="identifier">my_region_B</span><span class="special">>::</span><span class="identifier">release</span><span class="special">();</span>
+ <span class="identifier">A_list</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">3</span><span class="special">);</span>
+ <span class="special">}</span>
+ <span class="identifier">monotonic</span><span class="special">::</span><span class="identifier">static_storage</span><span class="special"><</span><span class="identifier">my_region_A</span><span class="special">>::</span><span class="identifier">release</span><span class="special">();</span>
+ <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
+<span class="special">}</span>
+</pre>
+<p>
+ </p>
+<p>
+ Here, we have defined two storage regions, designated with the type-tags
+ <code class="computeroutput"><span class="identifier">my_region_A</span></code> and <code class="computeroutput"><span class="identifier">my_region_B</span></code>. These are passed as the second
+ type argument to a <code class="computeroutput"><span class="identifier">monotonic</span><span class="special">::</span><span class="identifier">allocator</span></code>
+ in order to segment out the storage used. These regions are independant of
+ each other; releasing storage for <code class="computeroutput"><span class="identifier">B_list</span></code>
+ does not effect the storage for <code class="computeroutput"><span class="identifier">A_list</span></code>.
+ </p>
+<p>
+ Using segmented storage systems helps with logical seperation of resource
+ usage amoung different sub-systems within an application. It also helps with
+ ensuring privacy when using local storage, as demonstrated below:
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">System</span>
+<span class="special">{</span>
+ <span class="keyword">struct</span> <span class="identifier">region</span> <span class="special">{};</span>
+ <span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="identifier">Object</span><span class="special">,</span> <span class="identifier">monotonic</span><span class="special">::</span><span class="identifier">allocator</span><span class="special"><</span><span class="identifier">Object</span><span class="special">,</span> <span class="identifier">region</span><span class="special">></span> <span class="special">></span> <span class="identifier">Objects</span><span class="special">;</span>
+
+<span class="keyword">public</span><span class="special">:</span>
+ <span class="keyword">void</span> <span class="identifier">update</span><span class="special">()</span>
+ <span class="special">{</span>
+ <span class="special">{</span>
+ <span class="identifier">Objects</span> <span class="identifier">objects</span><span class="special">;</span>
+ <span class="identifier">GatherRelevant</span><span class="special">(</span><span class="identifier">objects</span><span class="special">);</span>
+ <span class="identifier">Process</span><span class="special">(</span><span class="identifier">objects</span><span class="special">);</span>
+ <span class="identifier">Update</span><span class="special">(</span><span class="identifier">objects</span><span class="special">);</span>
+ <span class="special">}</span>
+ <span class="comment">// reset storage, ready for next update
+</span> <span class="identifier">monotonic</span><span class="special">::</span><span class="identifier">static_storage</span><span class="special"><</span><span class="identifier">region</span><span class="special">>::</span><span class="identifier">reset</span><span class="special">();</span>
+ <span class="special">}</span>
+<span class="special">};</span>
+</pre>
+<p>
+ </p>
+<p>
+ We have used a private region-tag <code class="computeroutput"><span class="identifier">region</span></code>
+ to guarantee that storage used by local containers such as <code class="computeroutput"><span class="identifier">Objects</span></code> is not shared with any other system.
+ </p>
+<p>
+ Note that this is a typical use-case for monotonic allocation, as it uses
+ a locally defined container which is populated, used and discarded regularly.
+ </p>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright © 2009 Christian Schladetsch<p>
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="using_multiple_containers.html"><img src="../../../../../../doc/html/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorial.html"><img src="../../../../../../doc/html/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/html/images/home.png" alt="Home"></a><a accesskey="n" href="using_monotonic_storage.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>
Added: sandbox/monotonic/libs/monotonic/doc/html/standalone_HTML.manifest
==============================================================================
--- (empty file)
+++ sandbox/monotonic/libs/monotonic/doc/html/standalone_HTML.manifest 2009-07-02 01:19:43 EDT (Thu, 02 Jul 2009)
@@ -0,0 +1,8 @@
+index.html
+monotonic_storage/intro.html
+monotonic_storage/change_log.html
+monotonic_storage/tutorial.html
+monotonic_storage/tutorial/basic_usage.html
+monotonic_storage/tutorial/using_multiple_containers.html
+monotonic_storage/tutorial/using_regions.html
+monotonic_storage/tutorial/using_monotonic_storage.html
Added: sandbox/monotonic/libs/monotonic/doc/monotonic.qbk
==============================================================================
--- (empty file)
+++ sandbox/monotonic/libs/monotonic/doc/monotonic.qbk 2009-07-02 01:19:43 EDT (Thu, 02 Jul 2009)
@@ -0,0 +1,314 @@
+[article Monotonic Storage
+ [quickbook 1.4]
+ [version 0.3]
+ [authors [Schladetsch, Christian]]
+ [copyright 2009 Christian Schladetsch]
+ [purpose /WikiWiki/ Fast resource management]
+ [license
+ Distributed under the Boost Software License, Version 1.0.
+ (See accompanying file LICENSE_1_0.txt or copy at
+ [@http://www.boost.org/LICENSE_1_0.txt])
+ ]
+]
+
+[/ QuickBook Document version 1.4 ]
+[/ Sept 24, 2002 ]
+[/ Sept 2, 2004 ]
+[/ Feb 14, 2005 ]
+[/ Sept 13, 2005 ]
+
+[/ Some links]
+
+[def __note__ [$images/note.png]]
+[def __alert__ [$images/alert.png]]
+[def __tip__ [$images/tip.png]]
+[def :-) [$images/smiley.png]]
+[def __spirit__ [@http://spirit.sourceforge.net Spirit]]
+[def __boostbook__ [@http://www.boost.org/doc/html/boostbook.html BoostBook]]
+[def __docbook__ [@http://www.docbook.org/ DocBook]]
+
+[def __comments__ [link monotonic.syntax.comments Comments]]
+
+[def __font_styles__ [link monotonic.syntax.phrase.font_styles Font Styles]]
+[def __quotations__ [link monotonic.syntax.phrase.quotations Quotations]]
+[def __replaceable__ [link monotonic.syntax.phrase.replaceable Replaceble]]
+[def __simple_formatting__ [link monotonic.syntax.phrase.simple_formatting Simple formatting]]
+[def __inline_code__ [link monotonic.syntax.phrase.inline_code Inline code]]
+[def __code_blocks__ [link monotonic.syntax.phrase.code_blocks Code blocks]]
+[def __source_mode__ [link monotonic.syntax.phrase.source_mode Source Mode]]
+[def __line_break__ [link monotonic.syntax.phrase.line_break line-break]]
+[def __anchors__ [link monotonic.syntax.phrase.anchors Anchors]]
+[def __links__ [link monotonic.syntax.phrase.links Links]]
+[def __anchor_links__ [link monotonic.syntax.phrase.anchor_links Anchor links]]
+[def __refentry_links__ [link monotonic.syntax.phrase.refentry_links refentry links]]
+[def __code_links__ [link monotonic.syntax.phrase.code_links function, class, member, enum, macro, concept or header links]]
+[def __escape__ [link monotonic.syntax.phrase.escape Escape]]
+[def __single_char_escape__ [link monotonic.syntax.phrase.single_char_escape Single char escape]]
+[def __images__ [link monotonic.syntax.phrase.images Images]]
+[def __cond__ [link monotonic.syntax.phrase.cond Conditional Generation]]
+
+[def __document__ [link monotonic.syntax.block.document Document]]
+[def __section__ [link monotonic.syntax.block.section Section]]
+[def __xinclude__ [link monotonic.syntax.block.xinclude xinclude]]
+[def __paragraphs__ [link monotonic.syntax.block.paragraphs Paragraphs]]
+[def __ordered_lists__ [link monotonic.syntax.block.lists.ordered_lists Ordered lists]]
+[def __list_hierarchies__ [link monotonic.syntax.block.lists.list_hierarchies List Hierarchies]]
+[def __long_list_lines__ [link monotonic.syntax.block.lists.long_list_lines Long List Lines]]
+[def __unordered_lists__ [link monotonic.syntax.block.lists.unordered_lists Unordered lists]]
+[def __mixed_lists__ [link monotonic.syntax.block.lists.mixed_lists Mixed lists]]
+[def __code__ [link monotonic.syntax.block.code Code]]
+[def __escape_back__ [link monotonic.syntax.block.escape_back Escaping Back To QuickBook]]
+[def __preformatted__ [link monotonic.syntax.block.preformatted Preformatted]]
+[def __blockquote__ [link monotonic.syntax.block.blockquote Blockquote]]
+[def __heading__ [link monotonic.syntax.block.headings Heading]]
+[def __macros__ [link monotonic.syntax.block.macros Macros]]
+[def __templates__ [link monotonic.syntax.block.templates Templates]]
+[def __predefined_macros__ [link monotonic.syntax.block.predefined_macros Predefined Macros]]
+[def __blurbs__ [link monotonic.syntax.block.blurbs Blurbs]]
+[def __admonitions__ [link monotonic.syntax.block.admonitions Admonitions]]
+[def __tables__ [link monotonic.syntax.block.tables Tables]]
+[def __variable_lists__ [link monotonic.syntax.block.variable_lists Variable Lists]]
+[def __include__ [link monotonic.syntax.block.include Include]]
+[def __import__ [link monotonic.syntax.block.import Import]]
+
+[section:intro Introduction]
+
+The [*Boost.Monotonic] library provides storage, allocation and container types for use
+in high-performance and real-time applications.
+
+The library provides a means for allocation to come from the stack, or the heap, or a combination of
+ both the stack and the heap. Allocation is fast, because de-allocation does nothing.
+ As such, the amount of storage used by a monotonic allocator can only ever increase
+ - hence the name of the library.
+
+Allocation can be ['regionalised] by application of user-supplied 'tag types' to specify a
+logical storage region. A second tag may be used to specify the
+['access type] for the region - which can be either global, guarded by a mutex, or using thread-local storage.
+
+[*Boost.Monotonic] is generally used where performace is a key concern.
+By making deallocation a no-op, allocation of memory resources is extremely fast.
+In general, the programmer is required to release storage used at an appropriate time,
+however local scoping systems are provided by the library for the most common use cases.
+
+Features include:
+
+* fast allocation from the stack
+* automatic extension to the heap as needed
+* storage can be segmented into independant regions
+* support for thread-safe storage, and thread-local storage
+* storage can be accessed directly, providing a 'first-class stack' system
+* containers that can use storage from the stack, from the heap, or both the stack and the heap
+
+[endsect]
+
+[section:change_log Change Log]
+
+[h3 Version 0.4]
+
+* Added reclaimable storage
+
+[h3 Version 0.3]
+
+* Added region- and access-tags.
+
+[endsect]
+
+[section:tutorial Tutorial]
+
+This tutorial progresses through the basic usage of the library,
+demonstrating how to use a monotonic allocator with STL containers,
+how to use monotonic storage directly without an allocator, how to use
+regions and access tags, and finally demonstrates the use of the
+supplied container library with stack-based local storage.
+
+[section Basic Usage]
+
+The following is a very quick introduction to [*Boost.Monotonic]:
+
+``
+#include <boost/monotonic/allocator.hpp>
+
+using namespace boost;
+
+int main()
+{
+ {
+ std::list<int, monotonic::allocator<int> > list;
+ for (size_t n = 0; n < 1000; ++n)
+ list.push_back(n);
+ }
+ monotonic::static_storage<>::release();
+ return 0;
+}
+``
+
+Here we have created a `std::list` using a monotonic allocator.
+While we add new elements to the list in the for-loop, allocation is coming
+from storage in the default region with default access. The first 32k of allocation
+will come from the BSS segment embedded in the application image (the amount
+of such storage is configurable), then once that local storage is exhausted,
+later allocation requests will be serviced from the heap. Since de-allocation
+does nothing in a monotonic allocator, we must manually release the resources
+once we are finished, as shown above.
+
+While this example is trivial, if you were to benchmark it against using
+a default `std::allocator` you will find that monotonic allocation is much faster[1].
+
+This is one of the main reasons for using this library; to provide efficient storage
+and allocation for temporary containers.
+
+We shall now move on to some more interesting examples, including how to use
+multiple containers that share the same strorage, using regions, using local
+stack-based storage, and dealing with threading issues.
+
+[endsect]
+
+[section Using Multiple Containers]
+
+In this example, we create a map of ints to vectors of ints,
+with each container using a monotonic allocator:
+
+``
+int main()
+{
+ {
+ typedef std::vector<int, monotonic::allocator<int> > Vector;
+ typedef std::map<int, Vector, std::less<int>, monotonic::allocator<Vector> > Map;
+ Map map;
+ for (size_t n = 0; n < 10000; ++n)
+ {
+ map[rand()%100].push_back(n);
+ }
+ }
+ monotonic::static_storage<>::release();
+ return 0;
+};
+``
+
+Again, storage will only ever increase, so we must release it after we have finished using it.
+
+Benchmarking the performance of this against other allocation schemes[2] show that
+monotonic allocation is extremely fast and efficient.
+
+The key point here is that you can use a `monotonic::allocator` anywhere that
+you would otherwise use a `std::allocator` or any other STL-compliant custom
+allocator. Monotonic allocators of the same type are effectively stateless,
+and may be default-constructed, used, and discarded as needed.
+
+We will deal with stateful monotonic allocators that can use local stack-based storage in a later section.
+
+[endsect]
+
+[section Using Regions]
+
+While it can be useful to have one storage area for all allocations,
+at times will will want to segment our memory usage into different ['regions].
+This is done by passing a user-supplied ['region tag type] to the type signature
+of a `monotonic::allocator`, as shown here:
+
+``
+struct my_region_A { };
+struct my_region_B { };
+
+int main()
+{
+ {
+ std::list<int, monotonic::allocator<int, my_region_A> > A_list;
+ A_list.push_back(1);
+ {
+ std::list<int, monotonic::allocator<int, my_region_B> > B_list;
+ B_list.push_back(2);
+ }
+ monotonic::static_storage<my_region_B>::release();
+ A_list.push_back(3);
+ }
+ monotonic::static_storage<my_region_A>::release();
+ return 0;
+}
+``
+
+Here, we have defined two storage regions, designated with the type-tags `my_region_A`
+and `my_region_B`. These are passed as the second type argument to a `monotonic::allocator`
+in order to segment out the storage used. These regions are independant of each other;
+releasing storage for `B_list` does not effect the storage for `A_list`.
+
+Using segmented storage systems helps with logical seperation of resource usage
+amoung different sub-systems within an application. It also helps with ensuring
+privacy when using local storage, as demonstrated below:
+
+``
+class System
+{
+ struct region {};
+ typedef std::vector<Object, monotonic::allocator<Object, region> > Objects;
+
+public:
+ void update()
+ {
+ {
+ Objects objects;
+ GatherRelevant(objects);
+ Process(objects);
+ Update(objects);
+ }
+ // reset storage, ready for next update
+ monotonic::static_storage<region>::reset();
+ }
+};
+``
+
+We have used a private region-tag `region` to guarantee that storage used
+by local containers such as `Objects` is not shared with any other system.
+
+Note that this is a typical use-case for monotonic allocation, as it uses a locally
+defined container which is populated, used and discarded regularly.
+
+[endsect]
+
+[section Using Monotonic Storage]
+
+While monotonic allocators use monotonic storage, we can also use this storage
+directly and wherever we want efficient resource management.
+
+``
+int main()
+{
+ // define local storage of 4k on the stack.
+ // allocations will use the heap after the inline stack-based storage
+ // has been exhausted.
+ monotonic::storage<4*1024> storage;
+ {
+ int &num = storage.create<int>();
+ std::string &str = storage.create<std::string>();
+ char *bytes = storage.allocate_bytes(3000);
+
+ // use num, str, bytes as needed
+
+ // call std::string's destructor directly, or use storage.destroy
+ storage.destroy(str);
+ }
+ return 0;
+}
+
+Of course, we could have just made `num`, `str` and `bytes` on the stack by declaring them as
+local variables and be done with it - well, except for having a dynamically-sized array of bytes
+on the stack. There is no other functional difference in this case, except that you are
+responsible for invoking object destructors. So how is this at all useful?
+
+We can use `monotonic::storage` as a form of "first-class scope" which can be created,
+manipulated, passed as as argument, returned as a value or reference, and destroyed as needed.
+
+In this sense, `monotonic::storage` is just like your very own C++ stack which you can share
+between objects and functions and even across process boundaries, independantly of the
+underlying machine-based stack.
+
+Also unlike the stack, storage will use the heap when its local inline stack-based buffer is exhuasted.
+This makes it ideal for using things like local buffers and containers that generally will be small
+enough to fit onto the stack, but with the fallback safety of transparently using the heap to
+service later requests for the cases where that inline buffer is not large enough.
+
+[endsect]
+
+
+[endsect]
+
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk