basis/concurrency/mailboxes/mailboxes-docs.factor

   1 USING: help.markup help.syntax kernel arrays calendar ;
   2 IN: concurrency.mailboxes
   3
   4 HELP: <mailbox>
   5 { $values { "mailbox" mailbox } }
   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." } ;
   7
   8 HELP: mailbox-empty?
   9 { $values { "mailbox" mailbox }
  10           { "bool" boolean }
  11 }
  12 { $description "Return true if the mailbox is empty." } ;
  13
  14 HELP: mailbox-put
  15 { $values { "obj" object }
  16           { "mailbox" mailbox }
  17 }
  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." } ;
  19
  20 HELP: block-unless-pred
  21 { $values
  22     { "mailbox" mailbox }
  23     { "timeout" { $maybe duration } }
  24     { "pred" { $quotation ( ... message -- ... ? ) } }
  25 }
  26 { $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." } ;
  27
  28 HELP: block-if-empty
  29 { $values { "mailbox" mailbox }
  30     { "timeout" { $maybe duration } }
  31 }
  32 { $description "Block the thread if the mailbox is empty." } ;
  33
  34 HELP: mailbox-get
  35 { $values { "mailbox" mailbox } { "obj" object } }
  36 { $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." } ;
  37
  38 HELP: mailbox-get-all
  39 { $values { "mailbox" mailbox } { "array" array } }
  40 { $description "Blocks the thread if the mailbox is empty, otherwise removes all objects in the mailbox and returns an array containing the objects." } ;
  41
  42 HELP: while-mailbox-empty
  43 { $values { "mailbox" mailbox }
  44           { "quot" { $quotation ( -- ) } }
  45 }
  46 { $description "Repeatedly call the quotation while there are no items in the mailbox." } ;
  47
  48 HELP: mailbox-get?
  49 { $values { "mailbox" mailbox }
  50           { "pred" { $quotation ( obj -- ? ) } }
  51           { "obj" object }
  52 }
  53 { $description "Get the first item in the mailbox which satisfies the predicate. When the predicate returns true that item will be returned. If nothing in the mailbox satisfies the predicate then the thread will block until something does." } ;
  54
  55 ARTICLE: "concurrency.mailboxes" "Mailboxes"
  56 "A " { $emphasis "mailbox" } " is a first-in-first-out queue where the operation of removing an element blocks if the queue is empty. Mailboxes are implemented in the " { $vocab-link "concurrency.mailboxes" } " vocabulary."
  57 { $subsections
  58     mailbox
  59     <mailbox>
  60 }
  61 "Removing the first element:"
  62 { $subsections
  63     mailbox-get
  64     mailbox-get-timeout
  65 }
  66 "Removing the first element matching a predicate:"
  67 { $subsections
  68     mailbox-get?
  69     mailbox-get-timeout?
  70 }
  71 "Emptying out a mailbox:"
  72 { $subsections mailbox-get-all }
  73 "Adding an element:"
  74 { $subsections mailbox-put }
  75 "Testing if a mailbox is empty:"
  76 { $subsections
  77     mailbox-empty?
  78     while-mailbox-empty
  79 } ;
  80
  81 ABOUT: "concurrency.mailboxes"