[llvm-commits] [llvm] r52360 - in /llvm/trunk: docs/ProgrammersManual.html include/llvm/User.h
Gabor Greif
ggreif at gmail.com
Mon Jun 16 14:06:12 PDT 2008
Author: ggreif
Date: Mon Jun 16 16:06:12 2008
New Revision: 52360
URL: http://llvm.org/viewvc/llvm-project?rev=52360&view=rev
Log:
Move some documentation from the header file into ProgrammersManual. About to improve.
Modified:
llvm/trunk/docs/ProgrammersManual.html
llvm/trunk/include/llvm/User.h
Modified: llvm/trunk/docs/ProgrammersManual.html
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/ProgrammersManual.html?rev=52360&r1=52359&r2=52360&view=diff
==============================================================================
--- llvm/trunk/docs/ProgrammersManual.html (original)
+++ llvm/trunk/docs/ProgrammersManual.html Mon Jun 16 16:06:12 2008
@@ -138,7 +138,8 @@
<li><a href="#AbstractTypeUser">The AbstractTypeUser Class</a></li>
</ul></li>
- <li><a href="#SymbolTable">The <tt>ValueSymbolTable</tt> and <tt>TypeSymbolTable</tt> classes </a></li>
+ <li><a href="#SymbolTable">The <tt>ValueSymbolTable</tt> and <tt>TypeSymbolTable</tt> classes</a></li>
+ <li><a href="#UserLayout">The <tt>User</tt> and owned <tt>Use</tt> classes' memory layout</a></li>
</ul></li>
<li><a href="#coreclasses">The Core LLVM Class Hierarchy Reference</a>
@@ -173,7 +174,8 @@
<div class="doc_author">
<p>Written by <a href="mailto:sabre at nondot.org">Chris Lattner</a>,
<a href="mailto:dhurjati at cs.uiuc.edu">Dinakar Dhurjati</a>,
- <a href="mailto:jstanley at cs.uiuc.edu">Joel Stanley</a>, and
+ <a href="mailto:ggreif at gmail.com">Gabor Greif</a>,
+ <a href="mailto:jstanley at cs.uiuc.edu">Joel Stanley</a> and
<a href="mailto:rspencer at x10sys.com">Reid Spencer</a></p>
</div>
@@ -2207,7 +2209,7 @@
by most clients. It should only be used when iteration over the symbol table
names themselves are required, which is very special purpose. Note that not
all LLVM
-<a href="#Value">Value</a>s have names, and those without names (i.e. they have
+<tt><a href="#Value">Value</a></tt>s have names, and those without names (i.e. they have
an empty name) do not exist in the symbol table.
</p>
@@ -2223,7 +2225,184 @@
-<!-- *********************************************************************** -->
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="UserLayout">The <tt>User</tt> and owned <tt>Use</tt> classes' memory layout</a>
+</div>
+
+<div class="doc_text">
+<p>The <tt><a href="http://llvm.org/doxygen/classllvm_1_1User.html">
+User</a></tt> class provides a base for expressing the ownership of <tt>User</tt>
+towards other <tt><a href="http://llvm.org/doxygen/classllvm_1_1Value.html">
+Value</a></tt>s. The <tt><a href="http://llvm.org/doxygen/classllvm_1_1Use.html">
+Use</a></tt> helper class is employed to do the bookkeeping and facilitate O(1)
+addition and removal.</p>
+
+<pre>
+ -----------------------------------------------------------------
+ --- Interaction and relationship between User and Use objects ---
+ -----------------------------------------------------------------
+
+
+A subclass of User can choose between incorporating its Use objects
+or refer to them out-of-line by means of a pointer. A mixed variant
+(some Uses inline others hung off) is impractical and breaks the invariant
+that the Use objects belonging to the same User form a contiguous array.
+
+We have 2 different layouts in the User (sub)classes:
+
+Layout a)
+The Use object(s) are inside (resp. at fixed offset) of the User
+object and there are a fixed number of them.
+
+Layout b)
+The Use object(s) are referenced by a pointer to an
+array from the User object and there may be a variable
+number of them.
+
+Initially each layout will possess a direct pointer to the
+start of the array of Uses. Though not mandatory for layout a),
+we stick to this redundancy for the sake of simplicity.
+The User object will also store the number of Use objects it
+has. (Theoretically this information can also be calculated
+given the scheme presented below.)
+
+Special forms of allocation operators (operator new)
+will enforce the following memory layouts:
+
+
+# Layout a) will be modelled by prepending the User object
+# by the Use[] array.
+#
+# ...---.---.---.---.-------...
+# | P | P | P | P | User
+# '''---'---'---'---'-------'''
+
+
+# Layout b) will be modelled by pointing at the Use[] array.
+#
+# .-------...
+# | User
+# '-------'''
+# |
+# v
+# .---.---.---.---...
+# | P | P | P | P |
+# '---'---'---'---'''
+
+ (In the above figures 'P' stands for the Use** that
+ is stored in each Use object in the member Use::Prev)
+
+
+Since the Use objects will be deprived of the direct pointer to
+their User objects, there must be a fast and exact method to
+recover it. This is accomplished by the following scheme:
+
+A bit-encoding in the 2 LSBits of the Use::Prev will allow to find the
+start of the User object:
+
+00 --> binary digit 0
+01 --> binary digit 1
+10 --> stop and calc (s)
+11 --> full stop (S)
+
+Given a Use*, all we have to do is to walk till we get
+a stop and we either have a User immediately behind or
+we have to walk to the next stop picking up digits
+and calculating the offset:
+
+.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.----------------
+| 1 | s | 1 | 0 | 1 | 0 | s | 1 | 1 | 0 | s | 1 | 1 | s | 1 | S | User (or User*)
+'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'----------------
+ |+15 |+10 |+6 |+3 |+1
+ | | | | |__>
+ | | | |__________>
+ | | |______________________>
+ | |______________________________________>
+ |__________________________________________________________>
+
+
+Only the significant number of bits need to be stored between the
+stops, so that the worst case is 20 memory accesses when there are
+1000 Use objects.
+
+The following literate Haskell fragment demonstrates the concept:
+
+> import Test.QuickCheck
+>
+> digits :: Int -> [Char] -> [Char]
+> digits 0 acc = '0' : acc
+> digits 1 acc = '1' : acc
+> digits n acc = digits (n `div` 2) $ digits (n `mod` 2) acc
+>
+> dist :: Int -> [Char] -> [Char]
+> dist 0 [] = ['S']
+> dist 0 acc = acc
+> dist 1 acc = let r = dist 0 acc in 's' : digits (length r) r
+> dist n acc = dist (n - 1) $ dist 1 acc
+>
+> takeLast n ss = reverse $ take n $ reverse ss
+>
+> test = takeLast 40 $ dist 20 []
+>
+
+Printing <test> gives: "1s100000s11010s10100s1111s1010s110s11s1S"
+
+The reverse algorithm computes the
+length of the string just by examining
+a certain prefix:
+
+> pref :: [Char] -> Int
+> pref "S" = 1
+> pref ('s':'1':rest) = decode 2 1 rest
+> pref (_:rest) = 1 + pref rest
+>
+> decode walk acc ('0':rest) = decode (walk + 1) (acc * 2) rest
+> decode walk acc ('1':rest) = decode (walk + 1) (acc * 2 + 1) rest
+> decode walk acc _ = walk + acc
+>
+
+Now, as expected, printing <pref test> gives 40.
+
+We can quickCheck this with following property:
+
+> testcase = dist 2000 []
+> testcaseLength = length testcase
+>
+> identityProp n = n > 0 && n <= testcaseLength ==> length arr == pref arr
+> where arr = takeLast n testcase
+
+As expected <quickCheck identityProp> gives:
+
+*Main> quickCheck identityProp
+OK, passed 100 tests.
+
+Let's be a bit more exhaustive:
+
+>
+> deepCheck p = check (defaultConfig { configMaxTest = 500 }) p
+>
+
+And here is the result of <deepCheck identityProp>:
+
+*Main> deepCheck identityProp
+OK, passed 500 tests.
+
+
+To maintain the invariant that the 2 LSBits of each Use** in Use
+never change after being set up, setters of Use::Prev must re-tag the
+new Use** on every modification. Accordingly getters must strip the
+tag bits.
+
+For layout b) instead of the User we will find a pointer (User* with LSBit set).
+Following this pointer brings us to the User. A portable trick will ensure
+that the first bytes of User (if interpreted as a pointer) will never have
+the LSBit set.
+</pre>
+
+</div>
+
+ <!-- *********************************************************************** -->
<div class="doc_section">
<a name="coreclasses">The Core LLVM Class Hierarchy Reference </a>
</div>
Modified: llvm/trunk/include/llvm/User.h
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/include/llvm/User.h?rev=52360&r1=52359&r2=52360&view=diff
==============================================================================
--- llvm/trunk/include/llvm/User.h (original)
+++ llvm/trunk/include/llvm/User.h Mon Jun 16 16:06:12 2008
@@ -23,171 +23,6 @@
namespace llvm {
-/*==============================================================================
-
-
- -----------------------------------------------------------------
- --- Interaction and relationship between User and Use objects ---
- -----------------------------------------------------------------
-
-
-A subclass of User can choose between incorporating its Use objects
-or refer to them out-of-line by means of a pointer. A mixed variant
-(some Uses inline others hung off) is impractical and breaks the invariant
-that the Use objects belonging to the same User form a contiguous array.
-
-We have 2 different layouts in the User (sub)classes:
-
-Layout a)
-The Use object(s) are inside (resp. at fixed offset) of the User
-object and there are a fixed number of them.
-
-Layout b)
-The Use object(s) are referenced by a pointer to an
-array from the User object and there may be a variable
-number of them.
-
-Initially each layout will possess a direct pointer to the
-start of the array of Uses. Though not mandatory for layout a),
-we stick to this redundancy for the sake of simplicity.
-The User object will also store the number of Use objects it
-has. (Theoretically this information can also be calculated
-given the scheme presented below.)
-
-Special forms of allocation operators (operator new)
-will enforce the following memory layouts:
-
-
-# Layout a) will be modelled by prepending the User object
-# by the Use[] array.
-#
-# ...---.---.---.---.-------...
-# | P | P | P | P | User
-# '''---'---'---'---'-------'''
-
-
-# Layout b) will be modelled by pointing at the Use[] array.
-#
-# .-------...
-# | User
-# '-------'''
-# |
-# v
-# .---.---.---.---...
-# | P | P | P | P |
-# '---'---'---'---'''
-
- (In the above figures 'P' stands for the Use** that
- is stored in each Use object in the member Use::Prev)
-
-
-Since the Use objects will be deprived of the direct pointer to
-their User objects, there must be a fast and exact method to
-recover it. This is accomplished by the following scheme:
-
-A bit-encoding in the 2 LSBits of the Use::Prev will allow to find the
-start of the User object:
-
-00 --> binary digit 0
-01 --> binary digit 1
-10 --> stop and calc (s)
-11 --> full stop (S)
-
-Given a Use*, all we have to do is to walk till we get
-a stop and we either have a User immediately behind or
-we have to walk to the next stop picking up digits
-and calculating the offset:
-
-.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.----------------
-| 1 | s | 1 | 0 | 1 | 0 | s | 1 | 1 | 0 | s | 1 | 1 | s | 1 | S | User (or User*)
-'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'----------------
- |+15 |+10 |+6 |+3 |+1
- | | | | |__>
- | | | |__________>
- | | |______________________>
- | |______________________________________>
- |__________________________________________________________>
-
-
-Only the significant number of bits need to be stored between the
-stops, so that the worst case is 20 memory accesses when there are
-1000 Use objects.
-
-The following literate Haskell fragment demonstrates the concept:
-
-> import Test.QuickCheck
->
-> digits :: Int -> [Char] -> [Char]
-> digits 0 acc = '0' : acc
-> digits 1 acc = '1' : acc
-> digits n acc = digits (n `div` 2) $ digits (n `mod` 2) acc
->
-> dist :: Int -> [Char] -> [Char]
-> dist 0 [] = ['S']
-> dist 0 acc = acc
-> dist 1 acc = let r = dist 0 acc in 's' : digits (length r) r
-> dist n acc = dist (n - 1) $ dist 1 acc
->
-> takeLast n ss = reverse $ take n $ reverse ss
->
-> test = takeLast 40 $ dist 20 []
->
-
-Printing <test> gives: "1s100000s11010s10100s1111s1010s110s11s1S"
-
-The reverse algorithm computes the
-length of the string just by examining
-a certain prefix:
-
-> pref :: [Char] -> Int
-> pref "S" = 1
-> pref ('s':'1':rest) = decode 2 1 rest
-> pref (_:rest) = 1 + pref rest
->
-> decode walk acc ('0':rest) = decode (walk + 1) (acc * 2) rest
-> decode walk acc ('1':rest) = decode (walk + 1) (acc * 2 + 1) rest
-> decode walk acc _ = walk + acc
->
-
-Now, as expected, printing <pref test> gives 40.
-
-We can quickCheck this with following property:
-
-> testcase = dist 2000 []
-> testcaseLength = length testcase
->
-> identityProp n = n > 0 && n <= testcaseLength ==> length arr == pref arr
-> where arr = takeLast n testcase
-
-As expected <quickCheck identityProp> gives:
-
-*Main> quickCheck identityProp
-OK, passed 100 tests.
-
-Let's be a bit more exhaustive:
-
->
-> deepCheck p = check (defaultConfig { configMaxTest = 500 }) p
->
-
-And here is the result of <deepCheck identityProp>:
-
-*Main> deepCheck identityProp
-OK, passed 500 tests.
-
-
-To maintain the invariant that the 2 LSBits of each Use** in Use
-never change after being set up, setters of Use::Prev must re-tag the
-new Use** on every modification. Accordingly getters must strip the
-tag bits.
-
-For layout b) instead of the User we will find a pointer (User* with LSBit set).
-Following this pointer brings us to the User. A portable trick will ensure
-that the first bytes of User (if interpreted as a pointer) will never have
-the LSBit set.
-
-==============================================================================*/
-
/// OperandTraits - Compile-time customization of
/// operand-related allocators and accessors
/// for use of the User class
More information about the llvm-commits
mailing list