doc/native_threads.txt

   1 CACAO Native Threads Implementation
   2 ===================================
   3
   4 Author:  Edwin Steiner
   5 Changes:
   6
   7
   8 Lock Records
   9 ------------
  10
  11 XXX to write
  12
  13 Lock Records Pools
  14 ------------------
  15
  16 Each threadobject has zero or more `lockRecordPool`s. The first pool contains
  17 INITIALLOCKRECORDS records. Each successive pool contains twice as many
  18 records as the thread owned before, except it is a pool recycled from the global
  19 free list (see below).
  20
  21     threadobject      +---------+     +---------+
  22         ee.lrpool --> | next    | --> | next    | --> (nil)
  23                       | size=16 |     | size=8  |
  24         ee.numlr=24   +---------+     +---------+
  25                       |         |     |         |
  26                       |         |     |         |
  27                       |         |     |         |
  28                       |         |     |         |
  29                       |         |     +---------+
  30                       |         |
  31                       |         |
  32                       |         |
  33                       |         |
  34                       |         |
  35                       +---------+
  36
  37 All the records owned by a threadobject t have ownerThread == t.
  38
  39 The global pool
  40 ---------------
  41
  42 The pools themselves are recycled in a global free list, the `global_pool`.
  43 There is a lock protecting it, the `pool_lock`.
  44
  45 When a thread is discarded, its lock record pools are inserted into the
  46 global_pool to be reused.
  47
  48 Recycling lock records
  49 ----------------------
  50
  51 The individual lock records are recycled using a per-thread free list
  52 dangling from ee.firstLR.
  53
  54 The list is chained using the `nextfree` field in the lock records.
  55
  56 When a pool is allocated, the `nextfree` fields of the records in the
  57 pool are chained together, with the last record having nextfree == NULL.
  58 This linked list becomes the new free list (except for the first record)
  59 when a new pool has been allocated.
  60
  61 Lock records are never destroyed, because there may always be references
  62 to them somewhere.
  63
  64 The dummyLR
  65 -----------
  66
  67 There is one special lock record that does not have an ownerThread: the
  68 `dummyLR`. It is always unlocked and is used instead of a NULL pointer
  69 to signal that an object has no lock record.
  70
  71 Freeing a lock record
  72 ---------------------
  73
  74 Freeing a lock record means releasing the lock it represents. This is
  75 done by setting the object reference `o` of the record to NULL and then
  76 doing `sem_post` on the semaphore of the record (once for each queuer
  77 on the record).
  78
  79 Recursive locks
  80 ---------------
  81
  82 Recursive locks are enabled by the `lockCounter` in the lock record.
  83 When a thread enters a monitor it already owns, the lock counter is
  84 simply incremented.
  85
  86 # vim: et sts=4 ts=4 sw=4