extra/coroutines/coroutines-docs.factor

   1 ! Copyright (C) 2005 Chris Double, 2007 Clemens Hofreither, 2008 James Cash.
   2 USING: help.markup help.syntax ;
   3 IN: coroutines
   4
   5 HELP: cocreate
   6 { $values { "quot" "a quotation with stack effect ( value -- )" } { "co" "a coroutine" } }
   7 { $description "Create a new coroutine which will execute the quotation when resumed. The quotation will have an initial value (received from " { $link coresume } ") on the stack when first resumed.\n\nCoroutines should never terminate normally by \"falling off\" the end of the quotation; instead, they should call " { $link coterminate } "." }
   8 ;
   9
  10 HELP: coresume
  11 { $values { "v" "an object" } { "co" "a coroutine" } { "result" "an object" } }
  12 { $description "Resume a coroutine with v as the first item on the stack. The result placed on the stack is the value of the topmost argument on the stack when " { $link coyield } " is called within the coroutine." }
  13 { $see-also *coresume coresume* }
  14 ;
  15
  16 HELP: *coresume
  17 { $values { "co" "a coroutine" } { "result" "an object" } }
  18 { $description "Variant of " { $link coresume } " that passes a default value of " { $link f } " to the coroutine." }
  19 { $see-also coresume coresume* }
  20 ;
  21
  22 HELP: coresume*
  23 { $values { "v" "an object" } { "co" "a coroutine" } }
  24 { $description "Variant of " { $link coresume } " that discards the result of the coroutine invocation." }
  25 { $see-also coresume *coresume }
  26 ;
  27
  28 HELP: coyield
  29 { $values { "v" "an object" } { "result" "an object" } }
  30 { $description "Suspend the current coroutine, leaving the value v on the stack when control is passed to the " { $link coresume } " caller. When this coroutine is later resumed, result will contain the value passed to " { $link coyield } "." }
  31 { $see-also *coyield coyield* coterminate }
  32 ;
  33
  34 HELP: *coyield
  35 { $values { "v" "an object" } }
  36 { $description "Variant of " { $link coyield } " that returns a default value of " { $link f } " to the caller." }
  37 { $see-also coyield coyield* }
  38 ;
  39
  40 HELP: coyield*
  41 { $values { "v" "an object" } }
  42 { $description "Variant of " { $link coyield } " that discards the value passed in via " { $link coresume } "." }
  43 { $see-also coyield *coyield }
  44 ;
  45
  46 HELP: coterminate
  47 { $values { "v" "an object" } }
  48 { $description "Terminate the current coroutine, leaving the value v on the stack when control is passed to the " { $link coresume } " caller. Resuming a terminated coroutine is a no-op." }
  49 { $see-also coyield coreset }
  50 ;
  51
  52 HELP: coreset
  53 { $values { "v" "an object" } }
  54 { $description "Reset the current coroutine, leaving the value v on the stack when control is passed to the " { $link coresume } " caller. When the coroutine is resumed, it will continue at the beginning of the coroutine." }
  55 { $see-also coyield coterminate }
  56 ;
  57
  58 HELP: current-coro
  59 { $description "Variable which contains the currently executing coroutine, or " { $link f } " if none is executing. User code should treat this variable as read-only." }
  60 { $see-also cocreate coresume coyield }
  61 ;