Subject: [Boost-commit] svn:boost r71151 - sandbox/shifted_ptr/libs/smart_ptr/doc
From: phil_at_[hidden]
Date: 2011-04-09 15:26:30
Author: pbouchard
Date: 2011-04-09 15:26:29 EDT (Sat, 09 Apr 2011)
New Revision: 71151
URL: http://svn.boost.org/trac/boost/changeset/71151
Log:
* Added rationale
Text files modified:
sandbox/shifted_ptr/libs/smart_ptr/doc/rationale.html | 59 +++++++++++++++++++++++++--------------
1 files changed, 37 insertions(+), 22 deletions(-)
Modified: sandbox/shifted_ptr/libs/smart_ptr/doc/rationale.html
==============================================================================
--- sandbox/shifted_ptr/libs/smart_ptr/doc/rationale.html (original)
+++ sandbox/shifted_ptr/libs/smart_ptr/doc/rationale.html 2011-04-09 15:26:29 EDT (Sat, 09 Apr 2011)
@@ -60,34 +60,49 @@
<dl class="index">
<dt>Introduction</dt>
- <dt>First topic</dt>
+ <dt>Cyclicism</dt>
+
+ <dt>Initialization</dt>
- <dt>Second topic</dt>
+ <dt>Union</dt>
- <dt>Footnotes</dt>
+ <dt>Naming Convention</dt>
</dl>
<h2><a name="introduction" id="introduction"></a>Introduction</h2>
- <p>{{text}}</p>
-
- <h2><a name="topic1" id="topic1"></a>First Topic</h2>
-
- <p>{{text}}</p>
-
- <h2><a name="topic2" id="topic2"></a>Second Topic</h2>
-
- <p>{{text}}</p>
-
- <h2><a name="footnotes" id="footnotes"></a>Footnotes</h2>
-
- <dl>
- <dt><a name="footnote1" class="footnote" id="footnote1">(1)</a>
- {{text}}</dt>
-
- <dt><a name="footnote2" class="footnote" id="footnote2">(2)</a>
- {{text}}</dt>
- </dl>
+ <p>Shifted Pointer introduces the concept of <i>set</i> where it is defined to be a one or many memory blocks referencing each other allocated on the heap pointed
+ to by one or many <i>shifted_ptr<T></i>s allocated on the stack or the data segment (non heap) of the application. Each <i>set</i> is consequently composed of a
+ list of all memory blocks constituting it and a counter tracking the number of times the <i>set</i> is referenced by a <i>shifted_ptr<T></i> from the stack or the data
+ segment.</p>
+
+ <h2><a name="cyclicism" id="cyclicism"></a>Cyclicism</h2>
+
+ <p>Therefore whenever a <i>set</i> counter finds out the number of <i>shifted_ptr<T></i> referencing it to be zero, the deallocation of each memory block composing
+ the <i>set</i> is enforced. Thus whether the <i>set</i> was composed of memory blocks referencing each other in a cyclic way or not, all of them will be subject to
+ destruction and deallocation indifferent from the cyclicism problem presented by the reference counters.</p>
+
+ <h2><a name="initialization" id="initialization"></a>Initialization</h2>
+
+ <p>A <i>shifted_ptr<T></i> is initialized differently depending on the memory segment it is being instanciated on. If it is found to be residing the stack or the data
+ segment then a new <i>set</i> counter will also be instanciated. If it is found to be living on the heap then a more complicated mechanism is involved to track the
+ last memory block that was allocated in the same thread, find its address and stack up the <i>set</i> it will be part of until the first <i>shifted_ptr<T></i> found on
+ the stack is or data segment is initialized, where the new <i>set</i> counter will be shared with all of the newly allocated blocks of memory referencing each other.</p>
+
+ <h2><a name="union" id="union"></a>Union</h2>
+
+ <p>A <i>set</i> will be unified with another <i>set</i> whenever one of its member is found to reference a member from a different <i>set</i>. The counter from the
+ first <i>set</i> will be added to the counter from the second <i>set</i> and a redirection of the first counter to the second will occur so that all elements from the
+ first <i>set</i> make direct use of the second counter. Once two <i>set</i>s are unified they will stay unified even if the new reference responsible for unifying the
+ <i>set</i>s is once again disjointed.</p>
+
+ <h2><a name="naming" id="naming"></a>Naming Convention</h2>
+
+ <p>The name <i>shifted_ptr<T></i> first comes from one of its caracteristic where the reference counter is allocated at the same time the pointee object is. Only the
+ pointer to the object is known by <i>shifted_ptr<T></i> and in order to access the reference counter, the pointer to the top of the object is "shifted" up. The name of
+ the class <i>shifted<T></i> used to instanciate all pointee objects is simply taken from the name <i>shifted_ptr<T></i> it will be affected to.
+ </p>
+
<hr>
<p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=