basis/concurrency/promises/promises-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.messaging kernel arrays\r
   4 continuations help.markup help.syntax quotations calendar ;\r
   5 IN: concurrency.promises\r
   6 \r
   7 HELP: promise\r
   8 { $class-description "The class of write-once promises." } ;\r
   9 \r
  10 HELP: promise-fulfilled?\r
  11 { $values { "promise" promise } { "?" "a boolean" } }\r
  12 { $description "Tests if " { $link fulfill } " has previously been called on the promise, in which case " { $link ?promise } " will return immediately without blocking." } ;\r
  13 \r
  14 HELP: ?promise-timeout\r
  15 { $values { "promise" promise } { "timeout" "a " { $link duration } " or " { $link f } } { "result" object } }\r
  16 { $description "Waits for another thread to fulfill a promise, returning immediately if the promise has already been fulfilled. A timeout of " { $link f } " indicates that the thread may block indefinitely, otherwise it will wait up to " { $snippet "timeout" } " milliseconds." }\r
  17 { $errors "Throws an error if the timeout expires before the promise has been fulfilled." } ;\r
  18 \r
  19 HELP: ?promise\r
  20 { $values { "promise" promise } { "result" object } }\r
  21 { $description "Waits for another thread to fulfill a promise, returning immediately if the promise has already been fulfilled." } ;\r
  22 \r
  23 HELP: fulfill\r
  24 { $values { "value" object } { "promise" promise } }\r
  25 { $description "Fulfills a promise by writing a value to it. Any threads waiting for the value are notified." }\r
  26 { $errors "Throws an error if the promise has already been fulfilled." } ;\r
  27 \r
  28 ARTICLE: "concurrency.promises" "Promises"\r
  29 "The " { $vocab-link "concurrency.promises" } " vocabulary implements " { $emphasis "promises" } ", which are thread-safe write-once variables. Once a promise is created, threads may block waiting for it to be " { $emphasis "fulfilled" } "; at some point in the future, another thread may provide a value at which point all waiting threads are notified."\r
  30 { $subsection promise }\r
  31 { $subsection <promise> }\r
  32 { $subsection fulfill }\r
  33 { $subsection ?promise }\r
  34 { $subsection ?promise-timeout } ;\r
  35 \r
  36 ABOUT: "concurrency.promises"\r