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                                       if (!status)   // EOS
 104                                         unset SPINNING flag
 105                                     }
 106                                     signal TH
 107                                  !  wait for commands (release lock)
 108
 109
 110 PLAYING->PAUSED
 111 ---------------
 112
 113 precondition:
 114   1. either:
 115     BH is spinning
 116     flag GST_THREAD_ACTIVE is set
 117     flag GST_THREAD_SPINNING is set
 118   2. or:
 119     BH is waiting for commands.
 120     flag GST_THREAD_ACTIVE is set
 121     flag GST_THREAD_SPINNING is unset
 122
 123 flow:
 124
 125 case 1.
 126
 127                                  !  while (flag SPINNING is set) {
 128                                  !    signal TH
 129                                  !    unlock mutex
 130   get mutex                      !
 131   set command for BH (PAUSED)    !
 132   unset SPINNING flag            !    status = iterate ()
 133   signal for new command         !
 134   wait for ACK (release lock)    !
 135                                       lock mutex (reacquired after iteration)
 136                                       if (!status)   // EOS
 137                                         unset SPINNING flag
 138                                     }
 139                                     if (status)
 140                                       change state of children to READY (*) (!EOS)
 141                                     signal TH
 142                                  !  wait for commands (release lock)
 143   (lock reacquired after wait)
 144   unlock (release lock)
 145
 146 case 2.
 147
 148   get mutex
 149   set command for BH (PAUSED)
 150   unset SPINNING flag (nop)
 151   signal for new command
 152   wait for ACK (release lock)    !
 153                                     (lock reacquired after wait for cmd)
 154                                     change state of children to READY (*)
 155                                     signal TH
 156                                  !  wait for commands (release lock)
 157   (lock reacquired after wait)
 158   unlock (release lock)
 159
 160
 161 PAUSED->READY
 162 -------------
 163
 164 similar to READY->PAUSED
 165
 166 TODO
 167 ----
 168
 169 - review
 170 - figure all all state change scenarios occuring in code marked with (*)
 171