basis/concurrency/futures/futures-docs.factor

   1 ! Copyright (C) 2005, 2008 Chris Double, Slava Pestov.\r
   2 ! See http://factorcode.org/license.txt for BSD license.\r
   3 USING: concurrency.promises concurrency.messaging kernel arrays\r
   4 continuations help.markup help.syntax quotations calendar ;\r
   5 IN: concurrency.futures\r
   6 \r
   7 HELP: future\r
   8 { $values { "quot" { $quotation ( -- value ) } } { "future" future } }\r
   9 { $description "Creates a deferred computation."\r
  10 $nl\r
  11 "The quotation begins with an empty data stack, an empty catch stack, and a name stack containing the global namespace only. This means that the only way to pass data to the quotation is to partially apply the data, for example using " { $link curry } " or " { $link compose } "." } ;\r
  12 \r
  13 HELP: ?future-timeout\r
  14 { $values { "future" future } { "timeout" { $maybe duration } } { "value" object } }\r
  15 { $description "Waits for a deferred computation to complete, blocking indefinitely if " { $snippet "timeout" } " is " { $link f } ", otherwise waiting up to the " { $snippet "timeout" } " before throwing an error." }\r
  16 { $errors "Throws an error if the timeout expires before the computation completes. Also throws an error if the future quotation threw an error." } ;\r
  17 \r
  18 HELP: ?future\r
  19 { $values { "future" future } { "value" object } }\r
  20 { $description "Waits for a deferred computation to complete, blocking indefinitely." }\r
  21 { $errors "Throws an error if future quotation threw an error." } ;\r
  22 \r
  23 ARTICLE: "concurrency.futures" "Futures"\r
  24 "The " { $vocab-link "concurrency.futures" } " vocabulary implements " { $emphasis "futures" } ", which are deferred computations performed in a background thread. A thread may create a future, then proceed to perform other tasks, then later wait for the future to complete."\r
  25 { $subsections\r
  26     future\r
  27     ?future\r
  28     ?future-timeout\r
  29 } ;\r
  30 \r
  31 ABOUT: "concurrency.futures"\r