extra/coroutines/coroutines-docs.factor

   1 ! Copyright (C) 2005 Chris Double, 2007 Clemens Hofreither.
   2 USING: help.markup help.syntax coroutines ;
   3
   4 HELP: cocreate
   5 { $values { "quot" "a quotation with stack effect ( value -- )" } { "co" "a coroutine" } }
   6 { $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 } "." }
   7 ;
   8
   9 HELP: coresume
  10 { $values { "v" "an object" } { "co" "a coroutine" } { "result" "an object" } }
  11 { $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." }
  12 { $see-also *coresume coresume* }
  13 ;
  14
  15 HELP: *coresume
  16 { $values { "co" "a coroutine" } { "result" "an object" } }
  17 { $description "Variant of " { $link coresume } " that passes a default value of " { $link f } " to the coroutine." }
  18 { $see-also coresume coresume* }
  19 ;
  20
  21 HELP: coresume*
  22 { $values { "v" "an object" } { "co" "a coroutine" } }
  23 { $description "Variant of " { $link coresume } " that discards the result of the coroutine invocation." }
  24 { $see-also coresume *coresume }
  25 ;
  26
  27 HELP: coyield
  28 { $values { "v" "an object" } { "result" "an object" } }
  29 { $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 } "." }
  30 { $see-also *coyield coyield* coterminate }
  31 ;
  32
  33 HELP: *coyield
  34 { $values { "v" "an object" } }
  35 { $description "Variant of " { $link coyield } " that returns a default value of " { $link f } " to the caller." }
  36 { $see-also coyield coyield* }
  37 ;
  38
  39 HELP: coyield*
  40 { $values { "v" "an object" } }
  41 { $description "Variant of " { $link coyield } " that discards the value passed in via " { $link coresume } "." }
  42 { $see-also coyield *coyield }
  43 ;
  44
  45 HELP: coterminate
  46 { $values { "v" "an object" } }
  47 { $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." }
  48 { $see-also coyield }
  49 ;
  50
  51 HELP: current-coro
  52 { $description "Variable which contains the currently executing coroutine, or " { $link f } " if none is executing. User code should treat this variable as read-only." }
  53 { $see-also cocreate coresume coyield }
  54 ;