Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r54804 - in sandbox/monotonic/libs/monotonic: doc doc/html doc/html/images doc/html/monotonic_storage test/Tests
From: christian.schladetsch_at_[hidden]
Date: 2009-07-08 15:53:49

Author: cschladetsch
Date: 2009-07-08 15:53:48 EDT (Wed, 08 Jul 2009)
New Revision: 54804
URL: http://svn.boost.org/trac/boost/changeset/54804

Log:
changed to build docs from sandbox

Added:
   sandbox/monotonic/libs/monotonic/doc/html/images/
   sandbox/monotonic/libs/monotonic/doc/html/images/alert.png (contents, props changed)
   sandbox/monotonic/libs/monotonic/doc/html/images/blank.png (contents, props changed)
   sandbox/monotonic/libs/monotonic/doc/html/images/caution.png (contents, props changed)
   sandbox/monotonic/libs/monotonic/doc/html/images/draft.png (contents, props changed)
   sandbox/monotonic/libs/monotonic/doc/html/images/home.png (contents, props changed)
   sandbox/monotonic/libs/monotonic/doc/html/images/important.png (contents, props changed)
   sandbox/monotonic/libs/monotonic/doc/html/images/next.png (contents, props changed)
   sandbox/monotonic/libs/monotonic/doc/html/images/next_disabled.png (contents, props changed)
   sandbox/monotonic/libs/monotonic/doc/html/images/note.png (contents, props changed)
   sandbox/monotonic/libs/monotonic/doc/html/images/prev.png (contents, props changed)
   sandbox/monotonic/libs/monotonic/doc/html/images/prev_disabled.png (contents, props changed)
   sandbox/monotonic/libs/monotonic/doc/html/images/smiley.png (contents, props changed)
   sandbox/monotonic/libs/monotonic/doc/html/images/tip.png (contents, props changed)
   sandbox/monotonic/libs/monotonic/doc/html/images/toc-blank.png (contents, props changed)
   sandbox/monotonic/libs/monotonic/doc/html/images/toc-minus.png (contents, props changed)
   sandbox/monotonic/libs/monotonic/doc/html/images/toc-plus.png (contents, props changed)
   sandbox/monotonic/libs/monotonic/doc/html/images/up.png (contents, props changed)
   sandbox/monotonic/libs/monotonic/doc/html/images/up_disabled.png (contents, props changed)
   sandbox/monotonic/libs/monotonic/doc/html/images/warning.png (contents, props changed)
Text files modified:
   sandbox/monotonic/libs/monotonic/doc/Jamfile.v2 | 18 -
   sandbox/monotonic/libs/monotonic/doc/html/index.html | 99 ++++++++-
   sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/change_log.html | 18
   sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/containers.html | 26 +-
   sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial.html | 382 ++++++++++++++++++++++++++++++++++++++-
   sandbox/monotonic/libs/monotonic/doc/html/standalone_HTML.manifest | 6
   sandbox/monotonic/libs/monotonic/test/Tests/tests.cpp | 4
   7 files changed, 483 insertions(+), 70 deletions(-)

Modified: sandbox/monotonic/libs/monotonic/doc/Jamfile.v2
==============================================================================
--- sandbox/monotonic/libs/monotonic/doc/Jamfile.v2 (original)
+++ sandbox/monotonic/libs/monotonic/doc/Jamfile.v2 2009-07-08 15:53:48 EDT (Wed, 08 Jul 2009)
@@ -1,26 +1,14 @@
project boost/monotonic/doc ;

import boostbook : boostbook ;
-using quickbook ;
+#//using quickbook ;

-xml monotonic : monotonic.qbk ;
+#//xml monotonic : monotonic.qbk ;

#path-constant images : ../../../doc/html ;
path-constant images : . ;

boostbook standalone
:
- monotonic
- :
- <xsl:param>boost.root=../../../..
- <xsl:param>boost.libraries=../../../../libs/libraries.htm
- #<xsl:param>html.stylesheet=../../../../doc/html/boostbook.css
- <xsl:param>html.stylesheet=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
+ monotonic.xml
;

Added: sandbox/monotonic/libs/monotonic/doc/html/images/alert.png
==============================================================================
Binary file. No diff available.

Added: sandbox/monotonic/libs/monotonic/doc/html/images/blank.png
==============================================================================
Binary file. No diff available.

Added: sandbox/monotonic/libs/monotonic/doc/html/images/caution.png
==============================================================================
Binary file. No diff available.

Added: sandbox/monotonic/libs/monotonic/doc/html/images/draft.png
==============================================================================
Binary file. No diff available.

Added: sandbox/monotonic/libs/monotonic/doc/html/images/home.png
==============================================================================
Binary file. No diff available.

Added: sandbox/monotonic/libs/monotonic/doc/html/images/important.png
==============================================================================
Binary file. No diff available.

Added: sandbox/monotonic/libs/monotonic/doc/html/images/next.png
==============================================================================
Binary file. No diff available.

Added: sandbox/monotonic/libs/monotonic/doc/html/images/next_disabled.png
==============================================================================
Binary file. No diff available.

Added: sandbox/monotonic/libs/monotonic/doc/html/images/note.png
==============================================================================
Binary file. No diff available.

Added: sandbox/monotonic/libs/monotonic/doc/html/images/prev.png
==============================================================================
Binary file. No diff available.

Added: sandbox/monotonic/libs/monotonic/doc/html/images/prev_disabled.png
==============================================================================
Binary file. No diff available.

Added: sandbox/monotonic/libs/monotonic/doc/html/images/smiley.png
==============================================================================
Binary file. No diff available.

Added: sandbox/monotonic/libs/monotonic/doc/html/images/tip.png
==============================================================================
Binary file. No diff available.

Added: sandbox/monotonic/libs/monotonic/doc/html/images/toc-blank.png
==============================================================================
Binary file. No diff available.

Added: sandbox/monotonic/libs/monotonic/doc/html/images/toc-minus.png
==============================================================================
Binary file. No diff available.

Added: sandbox/monotonic/libs/monotonic/doc/html/images/toc-plus.png
==============================================================================
Binary file. No diff available.

Added: sandbox/monotonic/libs/monotonic/doc/html/images/up.png
==============================================================================
Binary file. No diff available.

Added: sandbox/monotonic/libs/monotonic/doc/html/images/up_disabled.png
==============================================================================
Binary file. No diff available.

Added: sandbox/monotonic/libs/monotonic/doc/html/images/warning.png
==============================================================================
Binary file. No diff available.

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-08 15:53:48 EDT (Wed, 08 Jul 2009)
@@ -5,19 +5,19 @@
<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="Monotonic Storage 0.3">
-<link rel="next" href="monotonic_storage/intro.html" title="Introduction">
+<link rel="next" href="monotonic_storage/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 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>
+<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="spirit-nav"><a accesskey="n" href="monotonic_storage/change_log.html"><img src="../../doc/html/images/next.png" alt="Next"></a></div>
<div class="article" title="Monotonic Storage 0.3">
<div class="titlepage">
<div>
@@ -28,7 +28,7 @@
</h3></div></div></div>
<div>Copyright © 2009 Christian Schladetsch</div>
<div><div class="legalnotice" title="Legal Notice">
-<a name="id670824"></a>
+<a name="id670952"></a>
 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)
 
@@ -39,26 +39,95 @@
<div class="toc">
Table of Contents
<dl>
-<dt> Introduction</dt>
+<dt> Introduction</dt>
<dt> Change Log</dt>
<dt> Tutorial</dt>
<dd><dl>
-<dt>Basic Usage</dt>
-<dt><a href="monotonic_storage/tutorial/using_multiple_containers.html">Using
+<dt>Basic Usage</dt>
+<dt><a href="monotonic_storage/tutorial.html#monotonic_storage.tutorial.using_multiple_containers">Using
 Multiple Containers</a></dt>
-<dt>Using Regions</dt>
-<dt>Stack</dt>
+<dt>Using Regions</dt>
+<dt>Stack</dt>
</dl></dd>
<dt>Containers</dt>
-<dd><dl><dt>Chain</dt></dl></dd>
+<dd><dl><dt>Chain</dt></dl></dd>
</dl>
</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="index.html#monotonic_storage.intro" title="Introduction"> Introduction</a>
+</h2></div></div></div>
+
+ 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 BSS, stack, or
+ the heap, or transparently from a combination of the BSS, stack and heap. Allocation
+ is fast, because de-allocation does nothing
+ [<a name="id670993" href="#ftn.id670993" class="footnote">1</a>]
+ . As such, the amount of storage used by a monotonic allocator can only ever
+ increase - hence the name of the library. A LIFO allocation model is also provided.
+ 
+
+ 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, but there are many use-cases where use of this library provides
+ new functionality
+ [<a name="id671038" href="#ftn.id671038" class="footnote">2</a>]
+ .
+ 
+
+ 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:
+ 
+<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>
+<div class="footnotes">
+ <hr width="100" align="left">
+<div class="footnote">[<a name="ftn.id670993" href="#id670993" class="para">1</a>] 
+ except for <code class="computeroutput">monotonic::stack<></code>
+ </div>
+<div class="footnote">[<a name="ftn.id671038" href="#id671038" class="para">2</a>] 
+ such as in self- or mutually-recursive algorithms
+ </div>
+</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left">Last revised: July 07, 2009 at 09:33:35 GMT</td>
+<td align="left">Last revised: July 08, 2009 at 19:50:58 GMT</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>
+<div class="spirit-nav"><a accesskey="n" href="monotonic_storage/change_log.html"><img src="../../doc/html/images/next.png" alt="Next"></a></div>
</body>
</html>

Modified: sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/change_log.html
==============================================================================
--- sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/change_log.html (original)
+++ sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/change_log.html 2009-07-08 15:53:48 EDT (Wed, 08 Jul 2009)
@@ -6,35 +6,35 @@
<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="prev" href="../index.html" title="Monotonic Storage 0.3">
<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 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>
+<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>
+<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="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="id670966"></a>
+<a name="id671094"></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="id670986"></a>
+<a name="id671114"></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">
@@ -51,7 +51,7 @@
</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>
+<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="tutorial.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
</div>
</body>
</html>

Modified: sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/containers.html
==============================================================================
--- sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/containers.html (original)
+++ sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/containers.html 2009-07-08 15:53:48 EDT (Wed, 08 Jul 2009)
@@ -6,31 +6,30 @@
<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="tutorial/stack.html" title="Stack">
-<link rel="next" href="containers/chain.html" title="Chain">
+<link rel="prev" 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 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>
+<td align="center">More</td>
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="tutorial/stack.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/chain.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
+<a accesskey="p" href="tutorial.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>
</div>
<div class="section" title="Containers">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="monotonic_storage.containers"></a><a class="link" href="containers.html" title="Containers">Containers</a>
</h2></div></div></div>
-<div class="toc"><dl><dt>Chain</dt></dl></div>
+<div class="toc"><dl><dt>Chain</dt></dl></div>

 Along with an allocator, storage and stack system, the Monotonic library provides
 a set of containers that use stateful monotonic allocators
- [<a name="id677241" href="#ftn.id677241" class="footnote">5</a>]
+ [<a name="id677323" href="#ftn.id677323" class="footnote">5</a>]
 .
 

@@ -73,7 +72,7 @@
 
<div class="note" title="Note"><table border="0" summary="Note">
<tr>
-<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/html/images/note.png"></td>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/html/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top">
@@ -82,9 +81,12 @@
 in the example
 </td></tr>
</table></div>
+<div class="section" title="Chain"><div class="titlepage"><div><div><h3 class="title">
+<a name="monotonic_storage.containers.chain"></a><a class="link" href="containers.html#monotonic_storage.containers.chain" title="Chain">Chain</a>
+</h3></div></div></div></div>
<div class="footnotes">
 <hr width="100" align="left">
-<div class="footnote">[<a name="ftn.id677241" href="#id677241" class="para">5</a>] 
+<div class="footnote">[<a name="ftn.id677323" href="#id677323" class="para">5</a>] 
 these are based on boost::interprocess::containers
 </div>
</div>
@@ -99,7 +101,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="tutorial/stack.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/chain.html"><img src="../../../../../doc/html/images/next.png" alt="Next"></a>
+<a accesskey="p" href="tutorial.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>
</div>
</body>
</html>

Modified: sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial.html
==============================================================================
--- sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial.html (original)
+++ sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial.html 2009-07-08 15:53:48 EDT (Wed, 08 Jul 2009)
@@ -7,31 +7,31 @@
<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">
+<link rel="next" href="containers.html" title="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 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>
+<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>
+<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="containers.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>Basic Usage</dt>
-<dt><a href="tutorial/using_multiple_containers.html">Using
+<dt>Basic Usage</dt>
+<dt><a href="tutorial.html#monotonic_storage.tutorial.using_multiple_containers">Using
 Multiple Containers</a></dt>
-<dt>Using Regions</dt>
-<dt>Stack</dt>
+<dt>Using Regions</dt>
+<dt>Stack</dt>
</dl></div>

 This tutorial progresses through the basic usage of the library, demonstrating
@@ -40,6 +40,366 @@
 and finally demonstrates the use of the supplied container library with stack-based
 local storage.
 
+<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="tutorial.html#monotonic_storage.tutorial.basic_usage" title="Basic Usage">Basic Usage</a>
+</h3></div></div></div>
+
+ The following is a very quick introduction to Boost.Monotonic:
+ 
+
+
+
+<pre class="programlisting">#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;
+}
+</pre>
+
+ 
+
+ 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.
+ 
+
+ While this example is trivial, if you were to benchmark it against using
+ a default <code class="computeroutput">std::allocator</code> 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.
+ 
+</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="tutorial.html#monotonic_storage.tutorial.using_multiple_containers" title="Using Multiple Containers">Using
+ Multiple Containers</a>
+</h3></div></div></div>
+
+ In this example, we create a map of ints to vectors of ints, with each container
+ using a monotonic allocator:
+ 
+
+
+
+<pre class="programlisting">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;
+};
+</pre>
+
+ 
+
+ 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 <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.
+ 
+</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="tutorial.html#monotonic_storage.tutorial.using_regions" title="Using Regions">Using Regions</a>
+</h3></div></div></div>
+
+ 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 <code class="computeroutput">monotonic::allocator</code>,
+ as shown here:
+ 
+
+
+
+<pre class="programlisting">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;
+}
+</pre>
+
+ 
+
+ 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. These regions are independant of
+ each other; releasing storage for <code class="computeroutput">B_list</code>
+ does not effect the storage for <code class="computeroutput">A_list</code>.
+ 
+
+ 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:
+ 
+
+
+
+<pre class="programlisting">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();
+ }
+};
+</pre>
+
+ 
+
+ 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.
+ 
+</div>
+<div class="section" title="Stack">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="monotonic_storage.tutorial.stack"></a><a class="link" href="tutorial.html#monotonic_storage.tutorial.stack" title="Stack">Stack</a>
+</h3></div></div></div>
+
+ While monotonic allocators use monotonic storage, we can also use this storage
+ directly and wherever we want efficient resource management. Using a <code class="computeroutput">monotonic::stack<></code>
+ gives you a first-class C++ stack which you can use at will, pass as an argument
+ or return as a result
+ [<a name="id675924" href="#ftn.id675924" class="footnote">3</a>]
+ .
+ 
+
+ The general usage pattern is:
+ 
+
+
+
+<pre class="programlisting">monotonic::stack<Size> stack;
+{
+ T0 &t0 = stack.push<T0>(..args..);
+ T1 &t1 = stack.push<T1>(..args..);
+ ....
+ Tn &tn = stack.push<Tn>(..args..);
+
+ stack.pop();
+ stack.pop();
+ ...
+}
+</pre>
+
+ 
+
+ Objects are created in-place using emplace semantics.
+ You just provide the type and construction arguments - your object will be
+ either on the stack or the heap and you needn't worry either way. Objects
+ are not copied, which means you can safely use types
+ that do not have default constructors or assignment overloads with <code class="computeroutput">stack<></code>.
+ 
+
+ All objects pushed onto the <code class="computeroutput">stack<></code> are destroyed when the stack leaves
+ scope - there is no need to pop them all explicitly. New objects can be added
+ between <code class="computeroutput">push</code> and <code class="computeroutput">pop</code>.
+ 
+
+ You can set the amount of C++ machine stack to use by saying <code class="computeroutput">stack<num_bytes></code>.The
+ default inline size of a <code class="computeroutput">stack<></code> object is defined as <code class="computeroutput">boost::monotonic::DefaltSizes::InlineSize</code>.
+ 
+
+ We can use a <code class="computeroutput">stack<></code>
+ as a platform-independant <code class="computeroutput">alloca(size)</code>
+ by pushing an array of bytes, by using <code class="computeroutput">stack.push<char [N]></code> or <code class="computeroutput">stack.push<boost::array<char, N> ></code>
+ or more generally <code class="computeroutput">stack.push_array<Ty, N></code>.
+ 
+
+ When we call <code class="computeroutput">stack.pop()</code>,
+ the last value added to the stack is destroyed and the stack pointer is set
+ to the end of the previous object on the stack. Objects are added using correct
+ machine alignment. Calling <code class="computeroutput">pop</code>
+ on an empty stack throws an <code class="computeroutput">empty_stack</code>
+ exception.
+ 
+<div class="note" title="Note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/html/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top">
+ It is best practise to open a new statement block before using a <code class="computeroutput">stack<></code>
+ object. This ensures that the objects on the <code class="computeroutput">stack<></code> still have storage when when they
+ are automatically deleted
+ </td></tr>
+</table></div>
+
+ We can also iterate over the stack, get the stack size, and clear the stack:
+ 
+
+
+
+<pre class="programlisting">typedef monotonic::stack<> Stack;
+Stack stack;
+{
+ ... add objects to the stack ...
+
+ array<char, 1000> &bytes = stack.push_array<char, 1000>();
+
+ // number of elements on the stack
+ size_t size = stack.size();
+
+ // number of bytes used
+ size_t used_bytes = stack.bytes_used();
+
+ // iterate over heterogenous elements
+ Stack::const_iterator elem = stack.begin(), end = stack.end();
+ for (; elem != end; ++elem)
+ {
+ cout << elem->get_type().name() << endl;
+ if (elem->is_type<int>())
+ {
+ int num = elem->get<int>();
+ cout << num << endl;
+ }
+ }
+
+ // stacks are first-class objects and can be copied, passed
+ // as arguments and returned as results
+ Stack copy = stack;
+}
+</pre>
+
+ 
+
+ <code class="computeroutput">monotonic::stack<></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. They can be copied and compared and iterated over.
+ 
+<div class="warning" title="Warning"><table border="0" summary="Warning">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../doc/html/images/warning.png"></td>
+<th align="left">Warning</th>
+</tr>
+<tr><td align="left" valign="top">
+ Copying <code class="computeroutput">stack<></code>
+ objects performs a slicing copy. To safely copy general stacks, use <code class="computeroutput">boost::cloneable::stack<></code>
+ [<a name="id677096" href="#ftn.id677096" class="footnote">4</a>]
+ instead
+ </td></tr>
+</table></div>
+
+ Unlike the C++ stack, storage for a <code class="computeroutput">stack<></code> will use the heap when its local
+ inline stack-based buffer is exhuasted. This makes it ideal for local buffers
+ that will generally 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. This is especially useful
+ in recursive functions, which can be readily re-written to use a <code class="computeroutput">monotonic::stack<></code>
+ and thus be divorced from the limitations of the C++ stack.
+ 
+<div class="note" title="Note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/html/images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top">
+ When a <code class="computeroutput">stack<></code>
+ goes out of scope, all objects in that stack are destroyed
+ </td></tr>
+</table></div>
+
+ You can use <code class="computeroutput">monotonic::enter</code> to localise usage of a stack:
+ 
+
+
+
+<pre class="programlisting">template <class Stack>
+void UseStack(Stack &stack)
+{
+ monotonic::enter local(stack);
+}
+</pre>
+
+ 
+
+ This ensures that the stack leaves in the same state that it entered, by
+ <code class="computeroutput">pop</code>ping until the stack is
+ balanced. If the stack is smaller when <code class="computeroutput">local</code>
+ leaves scope than when it entered scope, it will throw <code class="computeroutput">boost::monotonic::uneven_stack</code>.
+ 
+</div>
+<div class="footnotes">
+ <hr width="100" align="left">
+<div class="footnote">[<a name="ftn.id675924" href="#id675924" class="para">3</a>] 
+ To avoid slicing copies, use Boost.Cloneable.Stack
+ </div>
+<div class="footnote">[<a name="ftn.id677096" href="#id677096" class="para">4</a>] 
+ TODO
+ </div>
+</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
@@ -51,7 +411,7 @@
</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>
+<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="containers.html"><img src="../../../doc/html/images/next.png" alt="Next"></a>
</div>
</body>
</html>

Modified: sandbox/monotonic/libs/monotonic/doc/html/standalone_HTML.manifest
==============================================================================
--- sandbox/monotonic/libs/monotonic/doc/html/standalone_HTML.manifest (original)
+++ sandbox/monotonic/libs/monotonic/doc/html/standalone_HTML.manifest 2009-07-08 15:53:48 EDT (Wed, 08 Jul 2009)
@@ -1,10 +1,4 @@
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/stack.html
monotonic_storage/containers.html
-monotonic_storage/containers/chain.html

Modified: sandbox/monotonic/libs/monotonic/test/Tests/tests.cpp
==============================================================================
--- sandbox/monotonic/libs/monotonic/test/Tests/tests.cpp (original)
+++ sandbox/monotonic/libs/monotonic/test/Tests/tests.cpp 2009-07-08 15:53:48 EDT (Wed, 08 Jul 2009)
@@ -89,11 +89,11 @@

BOOST_AUTO_TEST_CASE(test_stack)
{
- /*
 monotonic::stack<> stack;
 {
 size_t top = stack.top();
 int &n2 = stack.push<int>();
+ /*
 float &f0 = stack.push<float>();
 char &n3 = stack.push<char>();
 Tracked &tracked = stack.push<Tracked>();
@@ -115,8 +115,8 @@
 size_t top2 = stack.top();
 BOOST_ASSERT(top2 == top);
 BOOST_ASSERT(Tracked::count == 0);
+ */
 }
- */
}

BOOST_AUTO_TEST_CASE(test_fixed_stack)

Date view	Thread view	Subject view	Author view

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