basis/concurrency/flags/flags-docs.factor

   1 ! Copyright (C) 2008 Slava Pestov.
   2 ! See https://factorcode.org/license.txt for BSD license.
   3 USING: calendar concurrency.conditions help.markup help.syntax ;
   4 IN: concurrency.flags
   5
   6 HELP: flag
   7 { $class-description "A flag allows one thread to notify another when a condition is satisfied." } ;
   8
   9 HELP: <flag>
  10 { $values { "flag" flag } }
  11 { $description "Creates a new flag." } ;
  12
  13 HELP: lower-flag
  14 { $values { "flag" flag } }
  15 { $description "Attempts to lower a flag. If the flag has been raised previously, returns immediately, otherwise waits for it to be raised first." } ;
  16
  17 HELP: raise-flag
  18 { $values { "flag" flag } }
  19 { $description "Raises a flag, notifying any threads waiting on it. Does nothing if the flag has already been raised." } ;
  20
  21 HELP: wait-for-flag
  22 { $values { "flag" flag } }
  23 { $description "Waits for a flag to be raised. If the flag has already been raised, returns immediately." } ;
  24
  25 HELP: wait-for-flag-timeout
  26 { $values { "flag" flag } { "timeout" duration } }
  27 { $description "Waits for a flag to be raised or throws a " { $link timed-out-error } " if the flag wasn't raised in time." } ;
  28
  29 ARTICLE: "concurrency.flags" "Flags"
  30 "A " { $emphasis "flag" } " is a condition notification device which can be in one of two states: " { $emphasis "lowered" } " (the initial state) or " { $emphasis "raised" } "."
  31 $nl
  32 "The flag can be raised at any time; raising a raised flag does nothing. Lowering a flag if it has not been raised yet will wait for another thread to raise the flag."
  33 $nl
  34 "Essentially, a flag can be thought of as a counting semaphore where the count never goes above one."
  35 { $subsections
  36     flag
  37     flag?
  38 }
  39 "Waiting for a flag to be raised:"
  40 { $subsections
  41     raise-flag
  42     wait-for-flag
  43     lower-flag
  44 } ;
  45
  46 ABOUT: "concurrency.flags"