doc/doc.texi

   1 @node Project Documentation
   2 @appendix Project Documentation
   3
   4 This chapter presents a sample assignment and a filled-in design
   5 document for one possible implementation.  Its purpose is to give you an
   6 idea of what we expect to see in your own design documents.
   7
   8 @menu
   9 * Sample Assignment::
  10 * Sample Design Document::
  11 @end menu
  12
  13 @node Sample Assignment
  14 @section Sample Assignment
  15
  16 Implement @func{thread_join}.
  17
  18 @deftypefun void thread_join (tid_t @var{tid})
  19 Blocks the current thread until thread @var{tid} exits.  If @var{A} is
  20 the running thread and @var{B} is the argument, then we say that
  21 ``@var{A} joins @var{B}.''
  22
  23 Incidentally, the argument is a thread id, instead of a thread pointer,
  24 because a thread pointer is not unique over time.  That is, when a
  25 thread dies, its memory may be, whether immediately or much later,
  26 reused for another thread.  If thread @var{A} over time had two children
  27 @var{B} and @var{C} that were stored at the same address, then
  28 @code{thread_join(@var{B})} and @code{thread_join(@var{C})} would be
  29 ambiguous.
  30
  31 A thread may only join its immediate children.  Calling
  32 @func{thread_join} on a thread that is not the caller's child should
  33 cause the caller to return immediately.  Children are not ``inherited,''
  34 that is, if @var{A} has child @var{B} and @var{B} has child @var{C},
  35 then @var{A} always returns immediately should it try to join @var{C},
  36 even if @var{B} is dead.
  37
  38 A thread need not ever be joined.  Your solution should properly free
  39 all of a thread's resources, including its @struct{thread},
  40 whether it is ever joined or not, and regardless of whether the child
  41 exits before or after its parent.  That is, a thread should be freed
  42 exactly once in all cases.
  43
  44 Joining a given thread is idempotent.  That is, joining a thread
  45 multiple times is equivalent to joining it once, because it has already
  46 exited at the time of the later joins.  Thus, joins on a given thread
  47 after the first should return immediately.
  48
  49 You must handle all the ways a join can occur: nested joins (@var{A}
  50 joins @var{B}, then @var{B} joins @var{C}), multiple joins (@var{A}
  51 joins @var{B}, then @var{A} joins @var{C}), and so on.
  52 @end deftypefun
  53
  54 @node Sample Design Document
  55 @section Sample Design Document
  56
  57 @example
  58 @include sample.tmpl.texi
  59 @end example