basis/concurrency/exchangers/exchangers-docs.factor

   1 USING: help.markup help.syntax sequences kernel ;\r
   2 IN: concurrency.exchangers\r
   3 \r
   4 HELP: exchanger\r
   5 { $class-description "The class of object exchange points." } ;\r
   6 \r
   7 HELP: <exchanger>\r
   8 { $values { "exchanger" exchanger } }\r
   9 { $description "Creates a new object exchange point." } ;\r
  10 \r
  11 HELP: exchange\r
  12 { $values { "obj" object } { "exchanger" exchanger } { "newobj" object } }\r
  13 { $description "Waits for another thread to call " { $link exchange } " on the same exchanger. The thread's call to " { $link exchange } " returns with " { $snippet "obj" } " on the stack, and the object passed to " { $link exchange } " by the other thread is left on the current's thread stack as " { $snippet "newobj" } "." } ;\r
  14 \r
  15 ARTICLE: "concurrency.exchangers" "Object exchange points"\r
  16 "The " { $vocab-link "concurrency.exchangers" } " vocabulary implements " { $emphasis "object exchange points" } ", which are rendezvous points where two threads can exchange objects."\r
  17 { $subsections\r
  18     exchanger\r
  19     <exchanger>\r
  20     exchange\r
  21 }\r
  22 "One use-case is two threads, where one thread reads data into a buffer and another thread processes the data. The reader thread can begin by reading the data, then passing the buffer through an exchanger, then recursing. The processing thread can begin by creating an empty buffer, and exchanging it through the exchanger. It then processes the result and recurses."\r
  23 $nl\r
  24 "The vocabulary was modelled after a similar feature in Java's " { $snippet "java.util.concurrent" } " library." ;\r
  25 \r
  26 ABOUT: "concurrency.exchangers"\r