orphan.doc

   1
   2 Orphans.
   3
   4 For various operations we need to record information in the
   5 orphans file.  How to we prepare and commit that?
   6
   7 The relevant block of the file needs to be locked
   8 so that we can be sure a write will succeed.
   9
  10 Can we just update the block at any time?
  11 Yes: orphan information is just a hint - this might
  12 be an orphan on some sense.  So if an orphan record
  13 slips into the previous checkpoint that isn't a problem.
  14
  15 So to 'prepare' we find a free slot, or at least make sure
  16 there is one.
  17 To 'lock' we return a block+offset where that orphan info
  18 can be written.  The block will be locked.
  19 To 'commit' we update the slot in the block and mark it dirty.
  20
  21 We only write out the data on a checkpoint (When we write all
  22 dirty metadata).  Anything that needs orphan handling after the
  23 checkpoint will be detected as a transaction during roll-forward
  24 (unlink, truncate).
  25
  26 --------------
  27 Orphan actions:
  28
  29  - truncate
  30     This can apply to a TypeFile inode.  It must completely
  31     before further blocks are allocated.  statfs should
  32     also flush it.
  33     Once truncate has finished, the inode might get
  34     deleted if there are no further references.
  35  - directory clear chain
  36     This can apply to blocks in a directory.  It cleans up
  37     remnants of hash chains and may remove blocks from the
  38     file.  It must complete before we attempt to delete
  39     the directory
  40
  41 Orphan actions can happen:
  42  - synchronously with certain actions that require them to
  43    be complete
  44  - incrementally by the thread that manages checkpoints.
  45    Before an async checkpoint, we flush all orphans.
  46    Note that sync checkpoints needed to free space
  47    to not flush out orphans.
  48
  49 Then again.... maybe async is pointless.  Just drive it to completion
  50   straight away.  So 'truncate' doesn't complete until it is all done.
  51  'mount' has to run all orphans before the mount is complete.
  52  They can always be delayed later if it seems to be a problem.
  53 (much later)
  54 I don't know who wrote the above note.  Async is *good*.  Fast truncate
  55 is nice and not hard.  Allowing a checkpoint in the middle of a large
  56 truncate is vital, and is easy when it is async.
  57
  58 So generally async, but when needed, can be driven to completion.
  59 We need clear locking rules on who is allowed to do what, when.
  60
  61 Both 'truncate' and 'directory clean' require the i_mutex on the
  62 relevant file/dir, so we use that.
  63
  64 An operation that needs to drive orphans to completion must already
  65 hold i_mutex (though I guess it can take it if really necessary).
  66 The checkpoint thread must take the i_mutex, but if it cannot, don't block.
  67
  68 The orphan handler can return:
  69   0 - nothing more to do.  Don't retry until told to
  70   1 - did something, but there is more to do.  Try again whenever you
  71       are ready.
  72   2 - I cannot proceed until the checkpoint passes, so retry then
  73   3 - blocked waiting on IO.  When IO completes the thread will awake???
  74