basis/concurrency/mailboxes/mailboxes-docs.factor

   1 USING: help.markup help.syntax kernel arrays ;\r
   2 IN: concurrency.mailboxes\r
   3 \r
   4 HELP: <mailbox>\r
   5 { $values { "mailbox" mailbox } }\r
   6 { $description "A mailbox is an object that can be used for safe thread communication. Items can be put in the mailbox and retrieved in a FIFO order. If the mailbox is empty when a get operation is performed then the thread will block until another thread places something in the mailbox. If multiple threads are waiting on the same mailbox, only one of the waiting threads will be unblocked to thread the get operation." } ;\r
   7 \r
   8 HELP: mailbox-empty?\r
   9 { $values { "mailbox" mailbox } \r
  10           { "bool" "a boolean" }\r
  11 }\r
  12 { $description "Return true if the mailbox is empty." } ;\r
  13 \r
  14 HELP: mailbox-put\r
  15 { $values { "obj" object } \r
  16           { "mailbox" mailbox } \r
  17 }\r
  18 { $description "Put the object into the mailbox. Any threads that have a blocking get on the mailbox are resumed. Only one of those threads will successfully get the object, the rest will immediately block waiting for the next item in the mailbox." } ;\r
  19 \r
  20 HELP: block-unless-pred\r
  21 { $values { "pred" "a quotation with stack effect " { $snippet "( X -- bool )" } } \r
  22           { "mailbox" mailbox }\r
  23           { "timeout" "a timeout in milliseconds, or " { $link f } }\r
  24 }\r
  25 { $description "Block the thread if there are no items in the mailbox that return true when the predicate is called with the item on the stack." } ;\r
  26 \r
  27 HELP: block-if-empty\r
  28 { $values { "mailbox" mailbox } \r
  29       { "timeout" "a timeout in milliseconds, or " { $link f } }\r
  30 }\r
  31 { $description "Block the thread if the mailbox is empty." } ;\r
  32 \r
  33 HELP: mailbox-get\r
  34 { $values { "mailbox" mailbox } \r
  35           { "obj" object }\r
  36 }\r
  37 { $description "Get the first item put into the mailbox. If it is empty the thread blocks until an item is put into it. The thread then resumes, leaving the item on the stack." } ;\r
  38 \r
  39 HELP: mailbox-get-all\r
  40 { $values { "mailbox" mailbox } \r
  41           { "array" array }\r
  42 }\r
  43 { $description "Blocks the thread if the mailbox is empty, otherwise removes all objects in the mailbox and returns an array containing the objects." } ;\r
  44 \r
  45 HELP: while-mailbox-empty\r
  46 { $values { "mailbox" mailbox } \r
  47           { "quot" "a quotation with stack effect " { $snippet "( -- )" } }\r
  48 }\r
  49 { $description "Repeatedly call the quotation while there are no items in the mailbox." } ;\r
  50 \r
  51 HELP: mailbox-get?\r
  52 { $values { "mailbox" mailbox } \r
  53           { "pred" "a quotation with stack effect " { $snippet "( X -- bool )" } }\r
  54           { "obj" object }\r
  55 }\r
  56 { $description "Get the first item in the mailbox which satisfies the predicate. 'pred' will be called repeatedly for each item in the mailbox. When 'pred' returns true that item will be returned. If nothing in the mailbox satisfies the predicate then the thread will block until something does." } ;\r
  57 \r
  58 \r
  59 ARTICLE: "concurrency.mailboxes" "Mailboxes"\r
  60 "A " { $emphasis "mailbox" } " is a first-in-first-out queue where the operation of removing an element blocks if the queue is empty, instead of throwing an error. Mailboxes are implemented in the " { $vocab-link "concurrency.mailboxes" } " vocabulary."\r
  61 { $subsection mailbox }\r
  62 { $subsection <mailbox> }\r
  63 "Removing the first element:"\r
  64 { $subsection mailbox-get }\r
  65 { $subsection mailbox-get-timeout }\r
  66 "Removing the first element matching a predicate:"\r
  67 { $subsection mailbox-get? }\r
  68 { $subsection mailbox-get-timeout? }\r
  69 "Emptying out a mailbox:"\r
  70 { $subsection mailbox-get-all }\r
  71 "Adding an element:"\r
  72 { $subsection mailbox-put }\r
  73 "Testing if a mailbox is empty:"\r
  74 { $subsection mailbox-empty? }\r
  75 { $subsection while-mailbox-empty } ;\r
  76 \r
  77 ABOUT: "concurrency.mailboxes"\r