basis/concurrency/messaging/messaging-docs.factor

   1 ! Copyright (C) 2006 Chris Double.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.syntax help.markup concurrency.messaging.private
   4 threads kernel arrays quotations threads strings ;
   5 IN: concurrency.messaging
   6
   7 HELP: send
   8 { $values { "message" object }
   9           { "thread" thread }
  10 }
  11 { $description "Send the message to the thread by placing it in the threades mailbox. This is an asynchronous operation and will return immediately. The receving thread will act on the message the next time it retrieves that item from its mailbox (usually using the " { $link receive } " word. The message can be any Factor object. For destinations that are instances of remote-thread the message must be a serializable Factor type." }
  12 { $see-also receive receive-if } ;
  13
  14 HELP: receive
  15 { $values { "message" object }
  16 }
  17 { $description "Return a message from the current threades mailbox. If the box is empty, suspend the thread until another thread places an item in the mailbox (usually via the " { $link send } " word." }
  18 { $see-also send receive-if } ;
  19
  20 HELP: receive-if
  21 { $values { "pred" "a predicate with stack effect " { $snippet "( obj -- ? )" } }
  22           { "message" object }
  23 }
  24 { $description "Return the first message from the current threades mailbox that satisfies the predicate. To satisfy the predicate, " { $snippet "pred" } " is called with the item on the stack and the predicate should leave a boolean indicating whether it was satisfied or not. If nothing in the mailbox satisfies the predicate then the thread will block until something does." }
  25 { $see-also send receive } ;
  26
  27 HELP: spawn-linked
  28 { $values { "quot" quotation }
  29           { "name" string }
  30           { "thread" thread }
  31 }
  32 { $description "Start a thread which runs the given quotation. If that quotation throws an error which is not caught then the error will get propagated to the thread that spawned it. This can be used to set up 'supervisor' threades that restart child threades that crash due to uncaught errors.\n" }
  33 { $see-also spawn } ;
  34
  35 ARTICLE: { "concurrency" "messaging" } "Sending and receiving messages"
  36 "Each thread has an associated mailbox. Other threads can place items on this queue by sending the thread a message. A thread can check its mailbox for messages, blocking if none are pending, and thread them as they are queued."
  37 $nl
  38 "The messages that are sent from thread to thread are any Factor value. Factor tuples are ideal for this sort of thing as you can send a tuple to a thread and the generic word dispatch mechanism can be used to perform actions depending on what the type of the tuple is."
  39 $nl
  40 "The " { $link spawn } " word pushes the newly-created thread on the calling thread's stack; this thread object can then be sent messages:"
  41 { $subsection send }
  42 "A thread can get a message from its queue:"
  43 { $subsection receive }
  44 { $subsection receive-timeout }
  45 { $subsection receive-if }
  46 { $subsection receive-if-timeout }
  47 { $see-also "concurrency.mailboxes" } ;
  48
  49 ARTICLE: { "concurrency" "synchronous-sends" } "Synchronous sends"
  50 "The " { $link send } " word sends a message asynchronously, and the sending thread continues immediately. It is also possible to send a message to a thread and block until a response is received:"
  51 { $subsection send-synchronous }
  52 "To reply to a synchronous message:"
  53 { $subsection reply-synchronous }
  54 "An example:"
  55 { $example
  56     "USING: concurrency.messaging kernel threads ;"
  57     ": pong-server ( -- )"
  58     "    receive >r \"pong\" r> reply-synchronous ;"
  59     "[ pong-server t ] \"pong-server\" spawn-server"
  60     "\"ping\" swap send-synchronous ."
  61     "\"pong\""
  62 } ;
  63
  64 ARTICLE: { "concurrency" "exceptions" } "Linked exceptions"
  65 "A thread can handle exceptions using the standard Factor exception handling mechanism. If an exception is uncaught the thread will terminate. For example:"
  66 { $code "[ 1 0 / \"This will not print\" print ] \"division-by-zero\" spawn" }
  67 "Processes can be linked so that a parent thread can receive the exception that caused the child thread to terminate. In this way 'supervisor' threades can be created that are notified when child threades terminate and possibly restart them."
  68 { $subsection spawn-linked }
  69 "This will create a unidirectional link, such that if an uncaught exception causes the child to terminate, the parent thread can catch it:"
  70 { $code "["
  71 "  [ 1 0 / \"This will not print\" print ] \"linked-division\" spawn-linked drop"
  72 "  receive"
  73 "] [ \"Exception caught.\" print ] recover" }
  74 "Exceptions are only raised in the parent when the parent does a " { $link receive } " or " { $link receive-if } ". This is because the exception is sent from the child to the parent as a message." ;
  75
  76 ARTICLE: "concurrency.messaging" "Message-passing concurrency"
  77 "The " { $vocab-link "concurrency.messaging" } " vocabulary is based upon the style of concurrency used in systems like Erlang and Termite. It is built on top of the standard Factor lightweight thread system."
  78 $nl
  79 "A concurrency oriented program is one in which multiple threades run simultaneously in a single Factor image or across multiple running Factor instances. The threades can communicate with each other by asynchronous message sends."
  80 $nl
  81 "Although threades can share data via Factor's mutable data structures it is not recommended to mix shared state with message passing as it can lead to confusing code."
  82 { $subsection { "concurrency" "messaging" } }
  83 { $subsection { "concurrency" "synchronous-sends" } }
  84 { $subsection { "concurrency" "exceptions" } } ;
  85
  86 ABOUT: "concurrency.messaging"