README.states

   1
   2
   3 OVERALL STATES, defining interaction with innd:
   4
   5                                                                 START
   6                                                                   |
   7      ,-->--.                                                 check F, D
   8      |     |                                                      |
   9      |     |                                                      |
  10      |     |  <----------------<---------------------------------'|
  11      |     |                                       F exists       |
  12      |     |                                       D ENOENT       |
  13      |     |  duct opens F                                        |
  14      |     V                                                      |
  15      |  Normal                                                    |
  16      |   F: innd writing, duct reading                            |
  17      |   D: ENOENT                                                |
  18      |     |                                                      |
  19      |     |  duct decides time to flush                          |
  20      |     |  duct makes hardlink                                 |
  21      |     |                                                      |
  22      |     V                            <------------------------'|
  23      |  Hardlinked                                  F==D          |
  24      |   F == D: innd writing, duct reading         both exist    |
  25      ^     |                                                      |
  26      |     |  duct unlinks F                                      |
  27      |     |                        <-----------<-------------<--'|
  28      |     |                           open D         F ENOENT    |
  29      |     |                           if exists                  |
  30      |     |                                                      |
  31      |     V                        <---------------------.       |
  32      |  Moved                                             |       |
  33      |   F: ENOENT                                        |       |
  34      |   D: innd writing, duct reading; or ENOENT         |       |
  35      |     |                                              |       |
  36      |     |  duct requests flush of feed                 |       |
  37      |     |   (others can too, harmlessly)               |       |
  38      |     V                                              |       |
  39      |  Flushing                                          |       |
  40      |   F: ENOENT                                        |       |
  41      |   D: innd flushing, duct; or ENOENT                |       |
  42      |     |                                              |       |
  43      |     |   inndcomm flush fails                       |       |
  44      |     |`-------------------------->------------------'       |
  45      |     |                                                      |
  46      |     |   inndcomm reports no such site                      |
  47      |     |`---------------------------------------------------- | -.
  48      |     |                                                      |  |
  49      |     |  innd finishes writing D, creates F                  |  |
  50      |     |  inndcomm reports flush successful                   |  |
  51      |     |                                                      |  |
  52      |     V                                                      |  |
  53      |  Separated                                <----------------'  |
  54      |   F: innd writing                            F!=D             /
  55      |   D: duct reading; or ENOENT                  both exist     /
  56      |     |                                                       /
  57      |     |  duct gets to the end of D                           /
  58      |     |  duct opens F too                                   /
  59      |     V                                                    /
  60      |  Finishing                                              /
  61      |   F: innd writing, duct reading                        |
  62      |   D: duct finishing                                    V
  63      |     |                                            Dropping
  64      |     |  duct finishes processing D                 F: ENOENT
  65      |     V  duct unlinks D                             D: duct reading
  66      |     |                                                  |
  67      `--<--'                                                  | duct finishes
  68                                                               |  processing D
  69                                                               | duct unlinks D
  70                                                               | duct exits
  71                                                               V
  72                                                         Dropped
  73                                                          F: ENOENT
  74                                                          D: ENOENT
  75                                                          duct not running
  76
  77    "duct reading" means innduct is reading the file but also
  78    overwriting processed tokens.
  79
  80 \f
  81
  82 We implement this as follows:
  83
  84             .=======.
  85             ||START||
  86             `======='
  87                 |
  88                 | open F
  89                 |
  90                 |    F ENOENT
  91                 |`---------------------------------------------------.
  92       F OPEN OK |                                                    |
  93                 |`---------------- - - -                             |
  94        D ENOENT |       D EXISTS   see OVERALL STATES diagram        |
  95                 |                  for full startup logic            |
  96      ,--------->|                                                    |
  97      |          V                                                    |
  98      |     ============                                       try to |
  99      |      NORMAL                                            open D |
 100      |     [Normal]                                                  |
 101      |      main F tail                                              |
 102      |     ============                                              V
 103      |          |                                                    |
 104      |          | F IS SO BIG WE SHOULD FLUSH, OR TIMEOUT            |
 105      ^          | hardlink F to D                                    |
 106      |     [Hardlinked]                                              |
 107      |          | unlink F                                           |
 108      |          | our handle onto F is now onto D                    |
 109      |     [Moved]                                                   |
 110      |          |                                                    |
 111      |          |<-------------------<---------------------<---------+
 112      |          |                                                    |
 113      |          | spawn inndcomm flush                               |
 114      |          V                                                    |
 115      |     ==================                                        |
 116      |      FLUSHING[-ABSENT]                                        |
 117      |     [Flushing]                                                |
 118      |     main D tail/none                                          |
 119      |     ==================                                        |
 120      |          |                                                    |
 121      |          |   INNDCOMM FLUSH FAILS                             ^
 122      |          |`----------------------->----------.                |
 123      |          |                                   |                |
 124      |          |   NO SUCH SITE                    V                |
 125      ^          |`--------------->----.         ==================== |
 126      |          |                      \        FLUSHFAILED[-ABSENT] |
 127      |          |                       \         [Moved]            |
 128      |          | FLUSH OK               \       main D tail/none    |
 129      |          | open F                  \     ==================== |
 130      |          |                          \        |                |
 131      |          |                           \       | TIME TO RETRY  |
 132      |          |`------->----.     ,---<---'\      `----------------'
 133      |          |    D NONE   |     | D NONE  `----.
 134      |          V             |     |              V
 135      |     =============      V     V             ============
 136      |      SEPARATED-1       |     |              DROPPING-1
 137      |      flsh->rd!=0       |     |              flsh->rd!=0
 138      |     [Separated]        |     |             [Dropping]
 139      |      main F idle       |     |              main none
 140      |      flsh D tail       |     |              flsh D tail
 141      |     =============      |     |             ============
 142      |          |             |     | install       |
 143      ^          | EOF ON D    |     |  defer        | EOF ON D
 144      |          V             |     |               V
 145      |     ===============    |     |             ===============
 146      |      SEPARATED-2       |     |              DROPPING-2
 147      |      flsh->rd==0       |     V              flsh->rd==0
 148      |     [Finishing]        |     |             [Dropping]
 149      |      main F tail       |     `.             main none
 150      |      flsh D closed     |       `.           flsh D closed
 151      |     ===============    V         `.        ===============
 152      |          |                         `.          |
 153      |          | ALL D PROCESSED           `.        | ALL D PROCESSED
 154      |          V install defer as backlog    `.      | install defer
 155      ^          | close D                       `.    | close D
 156      |          | unlink D                        `.  | unlink D
 157      |          |                                  |  |
 158      |          |                                  V  V
 159      `----------'                               ==============
 160                                                  DROPPED
 161                                                 [Dropped]
 162                                                  main none
 163                                                  flsh none
 164                                                  some backlog
 165                                                 ==============
 166                                                       |
 167                                                       | ALL BACKLOG DONE
 168                                                       |
 169                                                       | unlink lock
 170                                                       | exit
 171                                                       V
 172                                                   ==========
 173                                                    (ESRCH)
 174                                                   [Droppped]
 175                                                   ==========
 176
 177
 178 rune for printing diagrams:
 179   a2ps -R -B -ops README.states