llvm.org GIT mirror llvm / e98fc27
Move some documentation from the header file into ProgrammersManual. About to improve. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@52360 91177308-0d34-0410-b5e6-96231b3b80d8 Gabor Greif 12 years ago
2 changed file(s) with 183 addition(s) and 169 deletion(s). Raw diff Collapse all Expand all
137137
  • The AbstractTypeUser Class
  • 138138
    139139
    140
  • The ValueSymbolTable and TypeSymbolTable classes
  • 140
  • The ValueSymbolTable and TypeSymbolTable classes
  • 141
  • The User and owned Use classes' memory layout
  • 141142
    142143
    143144
  • The Core LLVM Class Hierarchy Reference
  • 172173
    173174

    Written by Chris Lattner,

    174175 Dinakar Dhurjati,
    175 Joel Stanley, and
    176 Gabor Greif,
    177 Joel Stanley and
    176178 Reid Spencer

    177179
    178180
    22062208 by most clients. It should only be used when iteration over the symbol table
    22072209 names themselves are required, which is very special purpose. Note that not
    22082210 all LLVM
    2209 <a href="#Value">Value>s have names, and those without names (i.e. they have
    2211 <tt>Value>s have names, and those without names (i.e. they have
    22102212 an empty name) do not exist in the symbol table.
    22112213

    22122214
    22222224
    22232225
    22242226
    2225
    2227
    2228
    2229 The User and owned Use classes' memory layout
    2230
    2231
    2232
    2233

    The

    2234 User class provides a base for expressing the ownership of User
    2235 towards other
    2236 Values. The
    2237 Use helper class is employed to do the bookkeeping and facilitate O(1)
    2238 addition and removal.

    2239
    2240
    
                      
                    
    2241 -----------------------------------------------------------------
    2242 --- Interaction and relationship between User and Use objects ---
    2243 -----------------------------------------------------------------
    2244
    2245
    2246 A subclass of User can choose between incorporating its Use objects
    2247 or refer to them out-of-line by means of a pointer. A mixed variant
    2248 (some Uses inline others hung off) is impractical and breaks the invariant
    2249 that the Use objects belonging to the same User form a contiguous array.
    2250
    2251 We have 2 different layouts in the User (sub)classes:
    2252
    2253 Layout a)
    2254 The Use object(s) are inside (resp. at fixed offset) of the User
    2255 object and there are a fixed number of them.
    2256
    2257 Layout b)
    2258 The Use object(s) are referenced by a pointer to an
    2259 array from the User object and there may be a variable
    2260 number of them.
    2261
    2262 Initially each layout will possess a direct pointer to the
    2263 start of the array of Uses. Though not mandatory for layout a),
    2264 we stick to this redundancy for the sake of simplicity.
    2265 The User object will also store the number of Use objects it
    2266 has. (Theoretically this information can also be calculated
    2267 given the scheme presented below.)
    2268
    2269 Special forms of allocation operators (operator new)
    2270 will enforce the following memory layouts:
    2271
    2272
    2273 # Layout a) will be modelled by prepending the User object
    2274 # by the Use[] array.
    2275 #
    2276 # ...---.---.---.---.-------...
    2277 # | P | P | P | P | User
    2278 # '''---'---'---'---'-------'''
    2279
    2280
    2281 # Layout b) will be modelled by pointing at the Use[] array.
    2282 #
    2283 # .-------...
    2284 # | User
    2285 # '-------'''
    2286 # |
    2287 # v
    2288 # .---.---.---.---...
    2289 # | P | P | P | P |
    2290 # '---'---'---'---'''
    2291
    2292 (In the above figures 'P' stands for the Use** that
    2293 is stored in each Use object in the member Use::Prev)
    2294
    2295
    2296 Since the Use objects will be deprived of the direct pointer to
    2297 their User objects, there must be a fast and exact method to
    2298 recover it. This is accomplished by the following scheme:
    2299
    2300 A bit-encoding in the 2 LSBits of the Use::Prev will allow to find the
    2301 start of the User object:
    2302
    2303 00 --> binary digit 0
    2304 01 --> binary digit 1
    2305 10 --> stop and calc (s)
    2306 11 --> full stop (S)
    2307
    2308 Given a Use*, all we have to do is to walk till we get
    2309 a stop and we either have a User immediately behind or
    2310 we have to walk to the next stop picking up digits
    2311 and calculating the offset:
    2312
    2313 .---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.----------------
    2314 | 1 | s | 1 | 0 | 1 | 0 | s | 1 | 1 | 0 | s | 1 | 1 | s | 1 | S | User (or User*)
    2315 '---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'----------------
    2316 |+15 |+10 |+6 |+3 |+1
    2317 | | | | |__>
    2318 | | | |__________>
    2319 | | |______________________>
    2320 | |______________________________________>
    2321 |__________________________________________________________>
    2322
    2323
    2324 Only the significant number of bits need to be stored between the
    2325 stops, so that the worst case is 20 memory accesses when there are
    2326 1000 Use objects.
    2327
    2328 The following literate Haskell fragment demonstrates the concept:
    2329
    2330 > import Test.QuickCheck
    2331 >
    2332 > digits :: Int -> [Char] -> [Char]
    2333 > digits 0 acc = '0' : acc
    2334 > digits 1 acc = '1' : acc
    2335 > digits n acc = digits (n `div` 2) $ digits (n `mod` 2) acc
    2336 >
    2337 > dist :: Int -> [Char] -> [Char]
    2338 > dist 0 [] = ['S']
    2339 > dist 0 acc = acc
    2340 > dist 1 acc = let r = dist 0 acc in 's' : digits (length r) r
    2341 > dist n acc = dist (n - 1) $ dist 1 acc
    2342 >
    2343 > takeLast n ss = reverse $ take n $ reverse ss
    2344 >
    2345 > test = takeLast 40 $ dist 20 []
    2346 >
    2347
    2348 Printing gives: "1s100000s11010s10100s1111s1010s110s11s1S"
    2349
    2350 The reverse algorithm computes the
    2351 length of the string just by examining
    2352 a certain prefix:
    2353
    2354 > pref :: [Char] -> Int
    2355 > pref "S" = 1
    2356 > pref ('s':'1':rest) = decode 2 1 rest
    2357 > pref (_:rest) = 1 + pref rest
    2358 >
    2359 > decode walk acc ('0':rest) = decode (walk + 1) (acc * 2) rest
    2360 > decode walk acc ('1':rest) = decode (walk + 1) (acc * 2 + 1) rest
    2361 > decode walk acc _ = walk + acc
    2362 >
    2363
    2364 Now, as expected, printing gives 40.
    2365
    2366 We can quickCheck this with following property:
    2367
    2368 > testcase = dist 2000 []
    2369 > testcaseLength = length testcase
    2370 >
    2371 > identityProp n = n > 0 && n <= testcaseLength ==> length arr == pref arr
    2372 > where arr = takeLast n testcase
    2373
    2374 As expected gives:
    2375
    2376 *Main> quickCheck identityProp
    2377 OK, passed 100 tests.
    2378
    2379 Let's be a bit more exhaustive:
    2380
    2381 >
    2382 > deepCheck p = check (defaultConfig { configMaxTest = 500 }) p
    2383 >
    2384
    2385 And here is the result of :
    2386
    2387 *Main> deepCheck identityProp
    2388 OK, passed 500 tests.
    2389
    2390
    2391 To maintain the invariant that the 2 LSBits of each Use** in Use
    2392 never change after being set up, setters of Use::Prev must re-tag the
    2393 new Use** on every modification. Accordingly getters must strip the
    2394 tag bits.
    2395
    2396 For layout b) instead of the User we will find a pointer (User* with LSBit set).
    2397 Following this pointer brings us to the User. A portable trick will ensure
    2398 that the first bytes of User (if interpreted as a pointer) will never have
    2399 the LSBit set.
    2400
    2401
    2402
    2403
    2404
    22262405
    22272406 The Core LLVM Class Hierarchy Reference
    22282407
    2121 #include "llvm/Value.h"
    2222
    2323 namespace llvm {
    24
    25 /*==============================================================================
    26
    27
    28 -----------------------------------------------------------------
    29 --- Interaction and relationship between User and Use objects ---
    30 -----------------------------------------------------------------
    31
    32
    33 A subclass of User can choose between incorporating its Use objects
    34 or refer to them out-of-line by means of a pointer. A mixed variant
    35 (some Uses inline others hung off) is impractical and breaks the invariant
    36 that the Use objects belonging to the same User form a contiguous array.
    37
    38 We have 2 different layouts in the User (sub)classes:
    39
    40 Layout a)
    41 The Use object(s) are inside (resp. at fixed offset) of the User
    42 object and there are a fixed number of them.
    43
    44 Layout b)
    45 The Use object(s) are referenced by a pointer to an
    46 array from the User object and there may be a variable
    47 number of them.
    48
    49 Initially each layout will possess a direct pointer to the
    50 start of the array of Uses. Though not mandatory for layout a),
    51 we stick to this redundancy for the sake of simplicity.
    52 The User object will also store the number of Use objects it
    53 has. (Theoretically this information can also be calculated
    54 given the scheme presented below.)
    55
    56 Special forms of allocation operators (operator new)
    57 will enforce the following memory layouts:
    58
    59
    60 # Layout a) will be modelled by prepending the User object
    61 # by the Use[] array.
    62 #
    63 # ...---.---.---.---.-------...
    64 # | P | P | P | P | User
    65 # '''---'---'---'---'-------'''
    66
    67
    68 # Layout b) will be modelled by pointing at the Use[] array.
    69 #
    70 # .-------...
    71 # | User
    72 # '-------'''
    73 # |
    74 # v
    75 # .---.---.---.---...
    76 # | P | P | P | P |
    77 # '---'---'---'---'''
    78
    79 (In the above figures 'P' stands for the Use** that
    80 is stored in each Use object in the member Use::Prev)
    81
    82
    83 Since the Use objects will be deprived of the direct pointer to
    84 their User objects, there must be a fast and exact method to
    85 recover it. This is accomplished by the following scheme:
    86
    87 A bit-encoding in the 2 LSBits of the Use::Prev will allow to find the
    88 start of the User object:
    89
    90 00 --> binary digit 0
    91 01 --> binary digit 1
    92 10 --> stop and calc (s)
    93 11 --> full stop (S)
    94
    95 Given a Use*, all we have to do is to walk till we get
    96 a stop and we either have a User immediately behind or
    97 we have to walk to the next stop picking up digits
    98 and calculating the offset:
    99
    100 .---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.----------------
    101 | 1 | s | 1 | 0 | 1 | 0 | s | 1 | 1 | 0 | s | 1 | 1 | s | 1 | S | User (or User*)
    102 '---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'----------------
    103 |+15 |+10 |+6 |+3 |+1
    104 | | | | |__>
    105 | | | |__________>
    106 | | |______________________>
    107 | |______________________________________>
    108 |__________________________________________________________>
    109
    110
    111 Only the significant number of bits need to be stored between the
    112 stops, so that the worst case is 20 memory accesses when there are
    113 1000 Use objects.
    114
    115 The following literate Haskell fragment demonstrates the concept:
    116
    117 > import Test.QuickCheck
    118 >
    119 > digits :: Int -> [Char] -> [Char]
    120 > digits 0 acc = '0' : acc
    121 > digits 1 acc = '1' : acc
    122 > digits n acc = digits (n `div` 2) $ digits (n `mod` 2) acc
    123 >
    124 > dist :: Int -> [Char] -> [Char]
    125 > dist 0 [] = ['S']
    126 > dist 0 acc = acc
    127 > dist 1 acc = let r = dist 0 acc in 's' : digits (length r) r
    128 > dist n acc = dist (n - 1) $ dist 1 acc
    129 >
    130 > takeLast n ss = reverse $ take n $ reverse ss
    131 >
    132 > test = takeLast 40 $ dist 20 []
    133 >
    134
    135 Printing gives: "1s100000s11010s10100s1111s1010s110s11s1S"
    136
    137 The reverse algorithm computes the
    138 length of the string just by examining
    139 a certain prefix:
    140
    141 > pref :: [Char] -> Int
    142 > pref "S" = 1
    143 > pref ('s':'1':rest) = decode 2 1 rest
    144 > pref (_:rest) = 1 + pref rest
    145 >
    146 > decode walk acc ('0':rest) = decode (walk + 1) (acc * 2) rest
    147 > decode walk acc ('1':rest) = decode (walk + 1) (acc * 2 + 1) rest
    148 > decode walk acc _ = walk + acc
    149 >
    150
    151 Now, as expected, printing gives 40.
    152
    153 We can quickCheck this with following property:
    154
    155 > testcase = dist 2000 []
    156 > testcaseLength = length testcase
    157 >
    158 > identityProp n = n > 0 && n <= testcaseLength ==> length arr == pref arr
    159 > where arr = takeLast n testcase
    160
    161 As expected gives:
    162
    163 *Main> quickCheck identityProp
    164 OK, passed 100 tests.
    165
    166 Let's be a bit more exhaustive:
    167
    168 >
    169 > deepCheck p = check (defaultConfig { configMaxTest = 500 }) p
    170 >
    171
    172 And here is the result of :
    173
    174 *Main> deepCheck identityProp
    175 OK, passed 500 tests.
    176
    177
    178 To maintain the invariant that the 2 LSBits of each Use** in Use
    179 never change after being set up, setters of Use::Prev must re-tag the
    180 new Use** on every modification. Accordingly getters must strip the
    181 tag bits.
    182
    183 For layout b) instead of the User we will find a pointer (User* with LSBit set).
    184 Following this pointer brings us to the User. A portable trick will ensure
    185 that the first bytes of User (if interpreted as a pointer) will never have
    186 the LSBit set.
    187
    188 ==============================================================================*/
    18924
    19025 /// OperandTraits - Compile-time customization of
    19126 /// operand-related allocators and accessors