Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r54734 - in sandbox/monotonic/libs/monotonic/doc: . html html/monotonic_storage html/monotonic_storage/tutorial
From: christian.schladetsch_at_[hidden]
Date: 2009-07-06 18:43:12

Author: cschladetsch
Date: 2009-07-06 18:43:11 EDT (Mon, 06 Jul 2009)
New Revision: 54734
URL: http://svn.boost.org/trac/boost/changeset/54734

Log:
updated docs

Added:
   sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial/stack.html (contents, props changed)
Text files modified:
   sandbox/monotonic/libs/monotonic/doc/html/index.html | 7 +-
   sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/change_log.html | 4
   sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/containers.html | 10 ++--
   sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial.html | 3
   sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial/monotonic_stack.html | 3
   sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial/using_regions.html | 6 +-
   sandbox/monotonic/libs/monotonic/doc/html/standalone_HTML.manifest | 2
   sandbox/monotonic/libs/monotonic/doc/monotonic.qbk | 85 +++++++++++++++++++++++----------------
   8 files changed, 67 insertions(+), 53 deletions(-)

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-06 18:43:11 EDT (Mon, 06 Jul 2009)
@@ -28,7 +28,7 @@
</h3></div></div></div>
<div>Copyright © 2009 Christian Schladetsch</div>
<div><div class="legalnotice" title="Legal Notice">
-<a name="id648979"></a>
+<a name="id659902"></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)
 
@@ -47,8 +47,7 @@
<dt><a href="monotonic_storage/tutorial/using_multiple_containers.html">Using
 Multiple Containers</a></dt>
<dt>Using Regions</dt>
-<dt><a href="monotonic_storage/tutorial/monotonic_stack.html">Monotonic
- Stack</a></dt>
+<dt>Stack</dt>
</dl></dd>
<dt>Containers</dt>
<dd><dl><dt>Chain</dt></dl></dd>
@@ -56,7 +55,7 @@
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left">Last revised: July 06, 2009 at 21:55:04 GMT</td>
+<td align="left">Last revised: July 06, 2009 at 22:36:04 GMT</td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>

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-06 18:43:11 EDT (Mon, 06 Jul 2009)
@@ -27,14 +27,14 @@
<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="id649084"></a>
+<a name="id660007"></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="id649105"></a>
+<a name="id660028"></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">

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-06 18:43:11 EDT (Mon, 06 Jul 2009)
@@ -6,7 +6,7 @@
<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/monotonic_stack.html" title="Monotonic Stack">
+<link rel="prev" href="tutorial/stack.html" title="Stack">
<link rel="next" href="containers/chain.html" title="Chain">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
@@ -20,7 +20,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="tutorial/monotonic_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/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>
</div>
<div class="section" title="Containers">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
@@ -30,7 +30,7 @@

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

@@ -84,7 +84,7 @@
</table></div>
<div class="footnotes">
 <hr width="100" align="left">
-<div class="footnote">[<a name="ftn.id654617" href="#id654617" class="para">1</a>] 
+<div class="footnote">[<a name="ftn.id665771" href="#id665771" class="para">1</a>] 
 these are based on boost::interprocess::containers
 </div>
</div>
@@ -99,7 +99,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
-<a accesskey="p" href="tutorial/monotonic_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/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>
</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-06 18:43:11 EDT (Mon, 06 Jul 2009)
@@ -31,8 +31,7 @@
<dt><a href="tutorial/using_multiple_containers.html">Using
Multiple Containers</a></dt>
<dt>Using Regions</dt>
-<dt><a href="tutorial/monotonic_stack.html">Monotonic
- Stack</a></dt>
+<dt>Stack</dt>
</dl></div>

This tutorial progresses through the basic usage of the library, demonstrating

Modified: sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial/monotonic_stack.html
==============================================================================
--- sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial/monotonic_stack.html (original)
+++ sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial/monotonic_stack.html 2009-07-06 18:43:11 EDT (Mon, 06 Jul 2009)
@@ -86,7 +86,8 @@
 requests for the cases where that inline buffer is not large enough.
 

- When the stack goes out of scope, all objects are automatically destroyed.
+ When a stack goes out of scope, all objects in that stack are automatically
+ destroyed.
 
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>

Added: sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial/stack.html
==============================================================================
--- (empty file)
+++ sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial/stack.html 2009-07-06 18:43:11 EDT (Mon, 06 Jul 2009)
@@ -0,0 +1,137 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Stack</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="Monotonic Storage 0.3">
+<link rel="up" href="../tutorial.html" title="Tutorial">
+<link rel="prev" href="using_regions.html" title="Using Regions">
+<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 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><a accesskey="n" href="../containers.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+</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="stack.html" 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.
+ 
+
+ 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..);
+
+ boost::array<T, Size> &array = stack.push_array<T, Size>();
+
+ stack.pop();
+ ...
+}
+</pre>
+
+ 
+
+ 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, as shown above.
+ 
+<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 ...
+
+ size_t size = stack.size();
+ 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;
+
+ // unecessary in this case; will be cleared when stack leaves scope
+ stack.clear();
+}
+</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.
+ 
+
+ 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.
+ 
+
+ When a stack goes out of scope, all objects in that stack are automatically
+ destroyed.
+ 
+</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
+ 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)
+ 
+</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><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/monotonic_storage/tutorial/using_regions.html
==============================================================================
--- sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial/using_regions.html (original)
+++ sandbox/monotonic/libs/monotonic/doc/html/monotonic_storage/tutorial/using_regions.html 2009-07-06 18:43:11 EDT (Mon, 06 Jul 2009)
@@ -7,7 +7,7 @@
<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="monotonic_stack.html" title="Monotonic Stack">
+<link rel="next" href="stack.html" title="Stack">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
@@ -20,7 +20,7 @@
</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="monotonic_stack.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+<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="stack.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">
@@ -113,7 +113,7 @@
</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="monotonic_stack.html"><img src="../../../../../../doc/html/images/next.png" alt="Next"></a>
+<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="stack.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-06 18:43:11 EDT (Mon, 06 Jul 2009)
@@ -5,6 +5,6 @@
monotonic_storage/tutorial/basic_usage.html
monotonic_storage/tutorial/using_multiple_containers.html
monotonic_storage/tutorial/using_regions.html
-monotonic_storage/tutorial/monotonic_stack.html
+monotonic_storage/tutorial/stack.html
monotonic_storage/containers.html
monotonic_storage/containers/chain.html

Modified: sandbox/monotonic/libs/monotonic/doc/monotonic.qbk
==============================================================================
--- sandbox/monotonic/libs/monotonic/doc/monotonic.qbk (original)
+++ sandbox/monotonic/libs/monotonic/doc/monotonic.qbk 2009-07-06 18:43:11 EDT (Mon, 06 Jul 2009)
@@ -266,46 +266,61 @@

[endsect]

-[section Monotonic Stack]
+[section Stack]

While monotonic allocators use monotonic storage, we can also use this storage
directly and wherever we want efficient resource management.

+The general usage pattern is:
+
``
-int main()
+monotonic::stack<Size> stack;
{
- // define local storage of 4k on the stack.
- // allocations will use the heap after the inline stack-based storage
- // has been exhausted.
- typedef monotonic::stack<4*1024> Stack;
- Stack stack;
- {
- int &num = stack.push<int>();
- std::string &str = stack.push<std::string>("foo"); // objects are created in-place on the stack
- boost::array<char, 1000> &bytes = stack.push_array<char, 1000>();
-
- // use bytes
- std::generate_n(bytes.begin(), 1000, rand);
-
- // pop them off the stack
- stack.pop();
-
- float &num2 = stack.push<float>();
- stack.pop();
-
- assert(stack.size() == 2);
-
- BOOST_FOREACH(Stack::value_type const &elem, stack)
- {
- cout << elem.get_type().name() << endl;
- }
-
- DoSomethingElseWith(stack);
-
- // can copy stacks, but cannot compare them
- Stack copy = stack;
- }
- return 0;
+ T0 &t0 = stack.push<T0>(..args..);
+ T1 &t1 = stack.push<T1>(..args..);
+ ....
+ Tn &tn = stack.push<Tn>(..args..);
+
+ boost::array<T, Size> &array = stack.push_array<T, Size>();
+
+ stack.pop();
+ ...
+}
+``
+
+The default inline size of a `stack<>` object is defined as `boost::monotonic::DefaltSizes::InlineSize`.
+
+We can use a `stack<>` as a platform-independant `alloca(size)` by pushing an array of bytes, as shown above.
+
+[note It is best practise to open a new statement block before using a `stack<>` object. This ensures that the objects
+on the `stack<>` still have storage when when they are automatically deleted]
+
+We can also iterate over the stack, get the stack size, and clear the stack:
+
+``
+typedef monotonic::stack<> Stack;
+Stack stack;
+{
+ ... add objects to the stack ...
+
+ size_t size = stack.size();
+ 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;
+
+ // unecessary in this case; will be cleared when stack leaves scope
+ stack.clear();
}
``

@@ -318,7 +333,7 @@
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.

-When the stack goes out of scope, all objects are automatically destroyed.
+When a stack goes out of scope, all objects in that stack are automatically destroyed.

[endsect]

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