docs/random/wtay/threads_hilevel

   1 1) terms
   2 --------
   3
   4 - the managing container (top half). This is the main thread that
   5   will create and control the main_loop.
   6
   7 - the main_loop (bottom half), this is the thread that actually does
   8   the work.
   9
  10
  11
  12 2) state changes
  13 ================
  14
  15
  16 NULL->READY
  17 -----------
  18
  19 precondition:
  20   At this point only the top half exists.
  21   flag GST_THREAD_ACTIVE is unset
  22
  23 flow: (TH column 1, BH column 2, ! denotes (possible) thread switch)
  24   get mutex
  25   pthread create BH
  26   wait for spin up (release lock) !
  27                                     get mutex
  28                                     set flag GST_THREAD_ACTIVE
  29                                     change state of children to READY (*)
  30                                     signal TH
  31                                   ! wait for commands (release lock)
  32   (lock reacquired after wait)
  33   unlock mutex
  34
  35 (*) marks a spot that could potentially induce another state change.
  36
  37
  38 READY->NULL
  39 -----------
  40
  41 precondition:
  42   BH is waiting for commands.
  43   flag GST_THREAD_ACTIVE is set
  44
  45 flow:
  46   get mutex
  47   set command for BH (NULL)
  48   signal for new command
  49   wait for ACK (release lock)    !
  50                                     (lock reacquired after wait for cmd)
  51                                     change state of children to NULL (*)
  52                                     signal TH
  53                                     unset flag GST_THREAD_ACTIVE
  54                                  !  unlock (release lock)
  55                                  !  exit
  56   (lock reacquired after wait)
  57   join
  58   unlock (release lock)
  59
  60
  61 READY->PAUSED
  62 -------------
  63
  64 precondition:
  65   BH is waiting for commands.
  66   flag GST_THREAD_ACTIVE is set
  67
  68 flow:
  69   get mutex
  70   set command for BH (PAUSED)
  71   signal for new command
  72   wait for ACK (release lock)    !
  73                                     (lock reacquired after wait for cmd)
  74                                     change state of children to READY (*)
  75                                     signal TH
  76                                  !  wait for commands (release lock)
  77   (lock reacquired after wait)
  78   unlock (release lock)
  79
  80
  81 PAUSED->PLAYING
  82 ---------------
  83
  84 precondition:
  85   BH is waiting for commands.
  86   flag GST_THREAD_ACTIVE is set
  87
  88 flow:
  89   get mutex
  90   set command for BH (PLAYING)
  91   signal for new command
  92   wait for ACK (release lock)    !
  93                                     (lock reacquired after wait for cmd)
  94                                     change state of children to PLAYING (*)
  95                                     set flag GST_THREAD_SPINNING
  96                                     while (flag SPINNING is set) {
  97                                       signal TH
  98                                  !    unlock mutex
  99   (lock reacquired after wait)   !
 100   unlock (release lock)          !
 101                                  !    status = iterate()  (*)
 102                                       lock mutex
 103                                       signal TH
 104                                       if (!status)   // EOS
 105                                         unset SPINNING flag
 106                                     }
 107                                     signal TH
 108                                  !  wait for commands (release lock)
 109
 110
 111 PLAYING->PAUSED
 112 ---------------
 113
 114 precondition:
 115   1. either:
 116     BH is spinning
 117     flag GST_THREAD_ACTIVE is set
 118     flag GST_THREAD_SPINNING is set
 119   2. or:
 120     BH is waiting for commands.
 121     flag GST_THREAD_ACTIVE is set
 122     flag GST_THREAD_SPINNING is unset
 123
 124 flow:
 125
 126 case 1.
 127
 128                                  !  while (flag SPINNING is set) {
 129                                  !    signal TH
 130                                  !    unlock mutex
 131   get mutex                      !
 132   set command for BH (PAUSED)    !
 133   unset SPINNING flag            !    status = iterate ()
 134   signal for new command         !
 135   wait for ACK (release lock)    !
 136                                       lock mutex (reacquired after iteration)
 137                                       if (!status)   // EOS
 138                                         unset SPINNING flag
 139                                     }
 140                                     if (status)
 141                                       change state of children to READY (*) (!EOS)
 142                                     signal TH
 143                                  !  wait for commands (release lock)
 144   (lock reacquired after wait)
 145   unlock (release lock)
 146
 147 case 2.
 148
 149   get mutex
 150   set command for BH (PAUSED)
 151   unset SPINNING flag (nop)
 152   signal for new command
 153   wait for ACK (release lock)    !
 154                                     (lock reacquired after wait for cmd)
 155                                     change state of children to READY (*)
 156                                     signal TH
 157                                  !  wait for commands (release lock)
 158   (lock reacquired after wait)
 159   unlock (release lock)
 160
 161
 162 PAUSED->READY
 163 -------------
 164
 165 similar to READY->PAUSED
 166
 167 TODO
 168 ----
 169
 170 - review
 171 - figure all all state change scenarios occuring in code marked with (*)
 172