|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r54575 - in sandbox/monotonic/libs/monotonic/doc: . html html/index html/monotonic
From: christian.schladetsch_at_[hidden]
Date: 2009-07-01 22:58:01
Author: cschladetsch
Date: 2009-07-01 22:58:00 EDT (Wed, 01 Jul 2009)
New Revision: 54575
URL: http://svn.boost.org/trac/boost/changeset/54575
Log:
updated docs before going to quickbook format
Text files modified:
sandbox/monotonic/libs/monotonic/doc/containers.xml | 11 ++
sandbox/monotonic/libs/monotonic/doc/html/index.html | 30 ++++---
sandbox/monotonic/libs/monotonic/doc/html/index/s04.html | 6
sandbox/monotonic/libs/monotonic/doc/html/index/s05.html | 10 +-
sandbox/monotonic/libs/monotonic/doc/html/monotonic/containers.html | 17 +++-
sandbox/monotonic/libs/monotonic/doc/html/monotonic/tests.html | 4
sandbox/monotonic/libs/monotonic/doc/html/monotonic/tutorial.html | 152 +++++++++++++++++++++++++++++++++------
sandbox/monotonic/libs/monotonic/doc/tutorial.xml | 150 ++++++++++++++++++++++++++++++++-------
8 files changed, 296 insertions(+), 84 deletions(-)
Modified: sandbox/monotonic/libs/monotonic/doc/containers.xml
==============================================================================
--- sandbox/monotonic/libs/monotonic/doc/containers.xml (original)
+++ sandbox/monotonic/libs/monotonic/doc/containers.xml 2009-07-01 22:58:00 EDT (Wed, 01 Jul 2009)
@@ -9,7 +9,12 @@
<section>
<title>Overview</title>
- <para>This tutorial demonstrates the use of the <emphasis>montonic containers</emphasis> provided in the Boost.Monotonic library.
- </para>
-</section>
+ <para>This tutorial demonstrates the use of the <emphasis>montonic containers</emphasis> provided in the <emphasis>Boost.Monotonic</emphasis> library.
+ </para>
+ <section>
+ <title>Monotonic Containers</title>
+ <para>
+ </para>
+ </section>
+ </section>
</section>
Modified: sandbox/monotonic/libs/monotonic/doc/html/index.html
==============================================================================
--- sandbox/monotonic/libs/monotonic/doc/html/index.html (original)
+++ sandbox/monotonic/libs/monotonic/doc/html/index.html 2009-07-01 22:58:00 EDT (Wed, 01 Jul 2009)
@@ -5,7 +5,7 @@
<link rel="stylesheet" href="boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
<link rel="home" href="index.html" title="Chapter 1. Boost.Monotonic">
-<link rel="next" href="monotonic/tutorial.html" title="Tutorial">
+<link rel="next" href="monotonic/tutorial.html" title="Boost.Monotonic Tutorial">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
@@ -30,7 +30,7 @@
</div></div>
<div><p class="copyright">Copyright © 2009 Christian Schladetsch</p></div>
<div><div class="legalnotice" title="Legal Notice">
-<a name="id648141"></a><p>Use, modification and distribution is subject to the Boost
+<a name="id666709"></a><p>Use, modification and distribution is subject to the Boost
Software License, Version 1.0. (See accompanying file
<code class="filename">LICENSE_1_0.txt</code> or copy at http://www.boost.org/LICENSE_1_0.txt)</p>
</div></div>
@@ -38,29 +38,33 @@
<div class="toc">
<p><b>Table of Contents</b></p>
<dl>
-<dt><span class="section">Introduction</span></dt>
-<dt><span class="section">Tutorial</span></dt>
+<dt><span class="section">Introduction</span></dt>
+<dt><span class="section">Boost.Monotonic Tutorial</span></dt>
<dd><dl>
-<dt><span class="section">Overview</span></dt>
-<dt><span class="section">Basic Usage</span></dt>
-<dt><span class="section">Using Multiple Containers</span></dt>
-<dt><span class="section">Notes</span></dt>
+<dt><span class="section">Overview</span></dt>
+<dt><span class="section">Basic Usage</span></dt>
+<dt><span class="section">Using Multiple Containers</span></dt>
+<dt><span class="section">Using Regions</span></dt>
+<dt><span class="section"><a href="monotonic/tutorial.html#id666918">
+ Using Monotonic Storage
+ </a></span></dt>
+<dt><span class="section">Notes</span></dt>
</dl></dd>
<dt><span class="section">Heterogenous Containers</span></dt>
-<dd><dl><dt><span class="section">Overview</span></dt></dl></dd>
+<dd><dl><dt><span class="section">Overview</span></dt></dl></dd>
<dt><span class="section">Frequently Asked Questions</span></dt>
<dt><span class="section">Design Overview</span></dt>
<dd><dl>
-<dt><span class="section">Class Hierachy</span></dt>
-<dt><span class="section">Abstract Allocator</span></dt>
+<dt><span class="section">Class Hierachy</span></dt>
+<dt><span class="section">Abstract Allocator</span></dt>
</dl></dd>
<dt><span class="section">Testsuite</span></dt>
-<dd><dl><dt><span class="section">Acceptance tests</span></dt></dl></dd>
+<dd><dl><dt><span class="section">Acceptance tests</span></dt></dl></dd>
</dl>
</div>
<div class="section" title="Introduction">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="id648161"></a>Introduction</h2></div></div></div>
+<a name="id666730"></a>Introduction</h2></div></div></div>
<p>
The <span class="emphasis"><em>Boost.Monotonic</em></span> library provides storage, allocation and container types for use in high-performance and real-time applications.
</p>
Modified: sandbox/monotonic/libs/monotonic/doc/html/index/s04.html
==============================================================================
--- sandbox/monotonic/libs/monotonic/doc/html/index/s04.html (original)
+++ sandbox/monotonic/libs/monotonic/doc/html/index/s04.html 2009-07-01 22:58:00 EDT (Wed, 01 Jul 2009)
@@ -24,9 +24,9 @@
</div>
<div class="section" title="Frequently Asked Questions">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="id648286"></a>Frequently Asked Questions</h2></div></div></div>
+<a name="id667026"></a>Frequently Asked Questions</h2></div></div></div>
<div class="qandaset" title="Frequently Asked Questions">
-<a name="id648293"></a><dl><dt>1. <a href="s04.html#id648296">Question?
+<a name="id667033"></a><dl><dt>1. <a href="s04.html#id667036">Question?
</a>
</dt></dl>
<table border="0" width="100%" summary="Q and A Set">
@@ -35,7 +35,7 @@
<tbody>
<tr class="question" title="1.">
<td align="left" valign="top">
-<a name="id648296"></a><a name="id648298"></a><p><b>1.</b></p>
+<a name="id667036"></a><a name="id667038"></a><p><b>1.</b></p>
</td>
<td align="left" valign="top"><p>Question?
</p></td>
Modified: sandbox/monotonic/libs/monotonic/doc/html/index/s05.html
==============================================================================
--- sandbox/monotonic/libs/monotonic/doc/html/index/s05.html (original)
+++ sandbox/monotonic/libs/monotonic/doc/html/index/s05.html 2009-07-01 22:58:00 EDT (Wed, 01 Jul 2009)
@@ -24,15 +24,15 @@
</div>
<div class="section" title="Design Overview">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="id648316"></a>Design Overview</h2></div></div></div>
+<a name="id667056"></a>Design Overview</h2></div></div></div>
<div class="toc"><dl>
-<dt><span class="section">Class Hierachy</span></dt>
-<dt><span class="section">Abstract Allocator</span></dt>
+<dt><span class="section">Class Hierachy</span></dt>
+<dt><span class="section">Abstract Allocator</span></dt>
</dl></div>
<div class="section" title="Class Hierachy"><div class="titlepage"><div><div><h3 class="title">
-<a name="id648323"></a>Class Hierachy</h3></div></div></div></div>
+<a name="id667063"></a>Class Hierachy</h3></div></div></div></div>
<div class="section" title="Abstract Allocator"><div class="titlepage"><div><div><h3 class="title">
-<a name="id648330"></a>Abstract Allocator</h3></div></div></div></div>
+<a name="id667071"></a>Abstract Allocator</h3></div></div></div></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: , at </small></p></td>
Modified: sandbox/monotonic/libs/monotonic/doc/html/monotonic/containers.html
==============================================================================
--- sandbox/monotonic/libs/monotonic/doc/html/monotonic/containers.html (original)
+++ sandbox/monotonic/libs/monotonic/doc/html/monotonic/containers.html 2009-07-01 22:58:00 EDT (Wed, 01 Jul 2009)
@@ -6,7 +6,7 @@
<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
<link rel="home" href="../index.html" title="Chapter 1. Boost.Monotonic">
<link rel="up" href="../index.html" title="Chapter 1. Boost.Monotonic">
-<link rel="prev" href="tutorial.html" title="Tutorial">
+<link rel="prev" href="tutorial.html" title="Boost.Monotonic Tutorial">
<link rel="next" href="../index/s04.html" title="Frequently Asked Questions">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
@@ -25,12 +25,19 @@
<div class="section" title="Heterogenous Containers">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="monotonic.containers"></a>Heterogenous Containers</h2></div></div></div>
-<div class="toc"><dl><dt><span class="section">Overview</span></dt></dl></div>
+<div class="toc"><dl><dt><span class="section">Overview</span></dt></dl></div>
<div class="section" title="Overview">
<div class="titlepage"><div><div><h3 class="title">
-<a name="id648270"></a>Overview</h3></div></div></div>
-<p>This tutorial demonstrates the use of the <span class="emphasis"><em>montonic containers</em></span> provided in the Boost.Monotonic library.
- </p>
+<a name="id666996"></a>Overview</h3></div></div></div>
+<div class="toc"><dl><dt><span class="section">Monotonic Containers</span></dt></dl></div>
+<p>This tutorial demonstrates the use of the <span class="emphasis"><em>montonic containers</em></span> provided in the <span class="emphasis"><em>Boost.Monotonic</em></span> library.
+ </p>
+<div class="section" title="Monotonic Containers">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="id667013"></a>Monotonic Containers</h4></div></div></div>
+<p>
+ </p>
+</div>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
Modified: sandbox/monotonic/libs/monotonic/doc/html/monotonic/tests.html
==============================================================================
--- sandbox/monotonic/libs/monotonic/doc/html/monotonic/tests.html (original)
+++ sandbox/monotonic/libs/monotonic/doc/html/monotonic/tests.html 2009-07-01 22:58:00 EDT (Wed, 01 Jul 2009)
@@ -24,10 +24,10 @@
<div class="section" title="Testsuite">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="monotonic.tests"></a>Testsuite</h2></div></div></div>
-<div class="toc"><dl><dt><span class="section">Acceptance tests</span></dt></dl></div>
+<div class="toc"><dl><dt><span class="section">Acceptance tests</span></dt></dl></div>
<div class="section" title="Acceptance tests">
<div class="titlepage"><div><div><h3 class="title">
-<a name="id643976"></a>Acceptance tests</h3></div></div></div>
+<a name="id667084"></a>Acceptance tests</h3></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col>
Modified: sandbox/monotonic/libs/monotonic/doc/html/monotonic/tutorial.html
==============================================================================
--- sandbox/monotonic/libs/monotonic/doc/html/monotonic/tutorial.html (original)
+++ sandbox/monotonic/libs/monotonic/doc/html/monotonic/tutorial.html 2009-07-01 22:58:00 EDT (Wed, 01 Jul 2009)
@@ -1,13 +1,13 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<title>Tutorial</title>
+<title>Boost.Monotonic Tutorial</title>
<link rel="stylesheet" href="../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
<link rel="home" href="../index.html" title="Chapter 1. Boost.Monotonic">
<link rel="up" href="../index.html" title="Chapter 1. Boost.Monotonic">
<link rel="prev" href="../index.html" title="Chapter 1. Boost.Monotonic">
-<link rel="next" href="../cloneable/containers.html" title="Heterogenous Containers">
+<link rel="next" href="containers.html" title="Heterogenous Containers">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
@@ -20,29 +20,33 @@
</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="../cloneable/containers.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
+<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="containers.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
</div>
-<div class="section" title="Tutorial">
+<div class="section" title="Boost.Monotonic Tutorial">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="monotonic.tutorial"></a>Tutorial</h2></div></div></div>
+<a name="monotonic.tutorial"></a><span class="emphasis"><em>Boost.Monotonic</em></span> Tutorial</h2></div></div></div>
<div class="toc"><dl>
-<dt><span class="section">Overview</span></dt>
-<dt><span class="section">Basic Usage</span></dt>
-<dt><span class="section">Using Multiple Containers</span></dt>
-<dt><span class="section">Notes</span></dt>
+<dt><span class="section">Overview</span></dt>
+<dt><span class="section">Basic Usage</span></dt>
+<dt><span class="section">Using Multiple Containers</span></dt>
+<dt><span class="section">Using Regions</span></dt>
+<dt><span class="section"><a href="tutorial.html#id666918">
+ Using Monotonic Storage
+ </a></span></dt>
+<dt><span class="section">Notes</span></dt>
</dl></div>
<div class="section" title="Overview">
<div class="titlepage"><div><div><h3 class="title">
-<a name="id643839"></a>Overview</h3></div></div></div>
+<a name="id666779"></a>Overview</h3></div></div></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>
+ </p>
</div>
<div class="section" title="Basic Usage">
<div class="titlepage"><div><div><h3 class="title">
-<a name="id643850"></a>Basic Usage</h3></div></div></div>
+<a name="id666790"></a>Basic Usage</h3></div></div></div>
<p>
-The following is a very quick introduction to Boost.Monotonic:
-</p>
+ The following is a very quick introduction to <span class="emphasis"><em>Boost.Monotonic</em></span>:
+ </p>
<pre class="programlisting">
#include <boost/monotonic/allocator.hpp>
@@ -58,17 +62,20 @@
monotonic::static_storage<>::release();
return 0;
}
-</pre>
+ </pre>
<p>
-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 monotonic 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 one 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>
+Here we have created a <code class="computeroutput">std::list</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>
-The above example is clearly trivial, but if you were to benchmark it against using a default std::allocator you will find that monotonic is much faster[1]. This is the main reason 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.
-</p>
+ While 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.
+ </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>
<div class="section" title="Using Multiple Containers">
<div class="titlepage"><div><div><h3 class="title">
-<a name="id643871"></a>Using Multiple Containers</h3></div></div></div>
+<a name="id666823"></a>Using Multiple Containers</h3></div></div></div>
<pre class="programlisting">
int main()
{
@@ -78,22 +85,117 @@
Map map;
for (size_t n = 0; n < 10000; ++n)
{
- map[rand()].push_back(n);
+ map[rand()%100].push_back(n);
}
}
monotonic::static_storage<>::release();
return 0;
};
+ </pre>
+<p>
+ In this admittedly contrived example, we create a map of ints to vectors of ints, which each container using a monotonic allocator. 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.
+ </p>
+<p>
+ The key point here is that you can use a <code class="computeroutput">monotonic::allocator</code> anywhere that you would otherwise use a <code class="computeroutput">std::allocator</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. We will deal with stateful monotonic allocators that can use local stack-based storage in a later section.
+ </p>
+</div>
+<div class="section" title="Using Regions">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id666851"></a>Using Regions</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">monotonic::allocator</code>, as shown here:
+ </p>
+<pre class="programlisting">
+struct my_region_A { };
+struct my_region_B { };
+
+int main()
+{
+ {
+ std::list<int, monotonic::allocator<int, my_region_A> > A_list;
+ std::list<int, monotonic::allocator<int, my_region_B> > B_list;
+ // use A_list and B_list
+ }
+ monotonic::static_storage<my_region_A>::release();
+ monotonic::static_storage<my_region_B>::release();
+ return 0;
+}
+ </pre>
+<p>
+ Here, we have defined two storage regions, designated with the type-tags <code class="computeroutput">my_region_A</code> and <code class="computeroutput">my_region_B</code>. These are passed as the second type argument to a <code class="computeroutput">monotonic::allocator</code> in order to segment out the storage used.
+</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>
+<pre class="programlisting">
+class System
+{
+ struct region {};
+ typedef std::vector<Object, monotonic::allocator<Object, region> > Objects;
+
+public:
+ void update()
+ {
+ {
+ Objects objects;
+ // populate and use objects container
+ //...
+ }
+ // reset storage, ready for next update
+ monotonic::static_storage<region>::reset();
+ }
+};
+</pre>
+<p>
+Here we have used a private region-tag <code class="computeroutput">region</code> to guarantee that storage used by local containers such as <code class="computeroutput">Objects</code> 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.
+</p>
+</div>
+<div class="section" title="Using Monotonic Storage">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="id666918"></a>
+ Using Monotonic Storage
+ </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>
+<pre class="programlisting">
+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;
+}
</pre>
<p>
- In this admittedly contrived example, we create a map of ints to vectors of ints, which each container using a monotonic allocator. Again, storage will only ever increase, so we must release it after we have finished using it. Again as well, benchmarking the performance of this against other allocation schemes[2] show that monotonic allocation is extremely fast and efficient.
+ Of course, we could have just made <code class="computeroutput">num</code>, <code class="computeroutput">str</code> and <code class="computeroutput">bytes</code> on the stack by declaring them as local variables and be done with it. There is no 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">monotonic::storage</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. In this sense, <code class="computeroutput">monotonic::storage</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>
<div class="section" title="Notes">
<div class="titlepage"><div><div><h3 class="title">
-<a name="id643886"></a>Notes</h3></div></div></div>
+<a name="id666969"></a>Notes</h3></div></div></div>
+<p>
[1] See further discussion on efficiency at xxx
-[2] See performance results at yyy
+</p>
+<p>
+ [2] See the performance results, comparing monotonic allocation with Boost.PoolAllocator, Boost.FastPoolAllocator, std::allocator and Intel's TBB allocation system.
+</p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
@@ -105,7 +207,7 @@
</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="../cloneable/containers.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
+<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="containers.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
</div>
</body>
</html>
Modified: sandbox/monotonic/libs/monotonic/doc/tutorial.xml
==============================================================================
--- sandbox/monotonic/libs/monotonic/doc/tutorial.xml (original)
+++ sandbox/monotonic/libs/monotonic/doc/tutorial.xml 2009-07-01 22:58:00 EDT (Wed, 01 Jul 2009)
@@ -2,22 +2,21 @@
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
<section last-revision="$Date:$" id="monotonic.tutorial">
- <title>Tutorial</title>
- <using-namespace name="boost"/>
- <using-namespace name="boost::monotonic"/>
-
- <section>
- <title>Overview</title>
-<para>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.
-</para>
-
-</section>
-
-<section><title>Basic Usage</title>
-<para>
-The following is a very quick introduction to Boost.Monotonic:
-</para>
-<programlisting>
+ <title><emphasis>Boost.Monotonic</emphasis> Tutorial</title>
+ <using-namespace name="boost"/>
+ <using-namespace name="boost::monotonic"/>
+
+ <section>
+ <title>Overview</title>
+ <para>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.
+ </para>
+ </section>
+
+ <section><title>Basic Usage</title>
+ <para>
+ The following is a very quick introduction to <emphasis>Boost.Monotonic</emphasis>:
+ </para>
+ <programlisting>
#include <boost/monotonic/allocator.hpp>
using namespace boost;
@@ -32,15 +31,18 @@
monotonic::static_storage<>::release();
return 0;
}
-</programlisting>
-<para>
-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 monotonic 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 one 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.
-</para>
-<para>
-The above example is clearly trivial, but if you were to benchmark it against using a default std::allocator you will find that monotonic is much faster[1]. This is the main reason 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.
-</para>
-</section>
-<section><title>Using Multiple Containers</title>
+ </programlisting>
+ <para>
+Here we have created a <code>std::list</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.
+ </para>
+ <para>
+ While 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ </section>
+ <section><title>Using Multiple Containers</title>
<programlisting>
int main()
{
@@ -50,20 +52,112 @@
Map map;
for (size_t n = 0; n < 10000; ++n)
{
- map[rand()].push_back(n);
+ map[rand()%100].push_back(n);
}
}
monotonic::static_storage<>::release();
return 0;
};
+ </programlisting>
+ <para>
+ In this admittedly contrived example, we create a map of ints to vectors of ints, which each container using a monotonic allocator. 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.
+ </para>
+ <para>
+ The key point here is that you can use a <code>monotonic::allocator</code> anywhere that you would otherwise use a <code>std::allocator</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. We will deal with stateful monotonic allocators that can use local stack-based storage in a later section.
+ </para>
+ </section>
+ <section><title>Using Regions</title>
+ <para>
+ 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 <emphasis>regions</emphasis>. This is done by passing a user-supplied <emphasis>region tag type</emphasis> to the type signature of a <code>monotonic::allocator</code>, as shown here:
+ </para>
+ <programlisting>
+struct my_region_A { };
+struct my_region_B { };
+
+int main()
+{
+ {
+ std::list<int, monotonic::allocator<int, my_region_A> > A_list;
+ std::list<int, monotonic::allocator<int, my_region_B> > B_list;
+ // use A_list and B_list
+ }
+ monotonic::static_storage<my_region_A>::release();
+ monotonic::static_storage<my_region_B>::release();
+ return 0;
+}
+ </programlisting>
+<para>
+ Here, we have defined two storage regions, designated with the type-tags <code>my_region_A</code> and <code>my_region_B</code>. These are passed as the second type argument to a <code>monotonic::allocator</code> in order to segment out the storage used.
+</para>
+<para>
+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:
+</para>
+<programlisting>
+class System
+{
+ struct region {};
+ typedef std::vector<Object, monotonic::allocator<Object, region> > Objects;
+
+public:
+ void update()
+ {
+ {
+ Objects objects;
+ // populate and use objects container
+ //...
+ }
+ // reset storage, ready for next update
+ monotonic::static_storage<region>::reset();
+ }
+};
</programlisting>
<para>
- In this admittedly contrived example, we create a map of ints to vectors of ints, which each container using a monotonic allocator. Again, storage will only ever increase, so we must release it after we have finished using it. Again as well, benchmarking the performance of this against other allocation schemes[2] show that monotonic allocation is extremely fast and efficient.
+Here we have used a private region-tag <code>region</code> to guarantee that storage used by local containers such as <code>Objects</code> 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.
+</para>
+</section>
+<section>
+ <title>
+ Using Monotonic Storage
+ </title>
+ <para>
+ While monotonic allocators use monotonic storage, we can also use this storage directly and wherever we want efficient resource management.
+ </para>
+ <programlisting>
+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;
+}
+</programlisting>
+<para>
+ Of course, we could have just made <code>num</code>, <code>str</code> and <code>bytes</code> on the stack by declaring them as local variables and be done with it. There is no functional difference in this case, except that you are responsible for invoking object destructors. So how is this at all useful?
+ </para>
+ <para>We can use <code>monotonic::storage</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. In this sense, <code>monotonic::storage</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.
+</para>
+<para>
+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.
</para>
</section>
<section><title>Notes</title>
+<para>
[1] See further discussion on efficiency at xxx
-[2] See performance results at yyy
+</para>
+<para>
+ [2] See the performance <ulink url="https://svn.boost.org/svn/boost/sandbox/monotonic/libs/monotonic/test/results">results</ulink>, comparing monotonic allocation with Boost.PoolAllocator, Boost.FastPoolAllocator, std::allocator and Intel's TBB allocation system.
+</para>
</section>
</section>
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