basis/concurrency/locks/locks-docs.factor

   1 USING: help.markup help.syntax sequences kernel quotations\r
   2 calendar ;\r
   3 IN: concurrency.locks\r
   4 \r
   5 HELP: lock\r
   6 { $class-description "The class of mutual exclusion locks." } ;\r
   7 \r
   8 HELP: <lock>\r
   9 { $values { "lock" lock } }\r
  10 { $description "Creates a non-reentrant lock." } ;\r
  11 \r
  12 HELP: <reentrant-lock>\r
  13 { $values { "lock" lock } }\r
  14 { $description "Creates a reentrant lock." } ;\r
  15 \r
  16 HELP: with-lock-timeout\r
  17 { $values { "lock" lock } { "timeout" "a " { $link duration } " or " { $link f } } { "quot" quotation } }\r
  18 { $description "Calls the quotation, ensuring that only one thread executes with the lock held at a time. If another thread is holding the lock, blocks until the thread releases the lock." }\r
  19 { $errors "Throws an error if the lock could not be acquired before the timeout expires. A timeout value of " { $link f } " means the thread is willing to wait indefinitely." } ;\r
  20 \r
  21 HELP: with-lock\r
  22 { $values { "lock" lock } { "quot" quotation } }\r
  23 { $description "Calls the quotation, ensuring that only one thread executes with the lock held at a time. If another thread is holding the lock, blocks until the thread releases the lock." } ;\r
  24 \r
  25 ARTICLE: "concurrency.locks.mutex" "Mutual-exclusion locks"\r
  26 "A mutual-exclusion lock ensures that only one thread executes with the lock held at a time. They are used to protect critical sections so that certain operations appear to be atomic to other threads."\r
  27 $nl\r
  28 "There are two varieties of locks: non-reentrant and reentrant. The latter may be acquired recursively by the same thread. Attempting to do so with the former will deadlock."\r
  29 { $subsection lock }\r
  30 { $subsection <lock> }\r
  31 { $subsection <reentrant-lock> }\r
  32 { $subsection with-lock }\r
  33 { $subsection with-lock-timeout } ;\r
  34 \r
  35 HELP: rw-lock\r
  36 { $class-description "The class of reader/writer locks." } ;\r
  37 \r
  38 HELP: with-read-lock-timeout\r
  39 { $values { "lock" lock } { "timeout" "a " { $link duration } " or " { $link f } } { "quot" quotation } }\r
  40 { $description "Calls the quotation, ensuring that no other thread is holding a write lock at the same time. If another thread is holding a write lock, blocks until the thread releases the lock." }\r
  41 { $errors "Throws an error if the lock could not be acquired before the timeout expires. A timeout value of " { $link f } " means the thread is willing to wait indefinitely." } ;\r
  42 \r
  43 HELP: with-read-lock\r
  44 { $values { "lock" lock } { "quot" quotation } }\r
  45 { $description "Calls the quotation, ensuring that no other thread is holding a write lock at the same time. If another thread is holding a write lock, blocks until the thread releases the lock." } ;\r
  46 \r
  47 HELP: with-write-lock-timeout\r
  48 { $values { "lock" lock } { "timeout" "a " { $link duration } " or " { $link f } } { "quot" quotation } }\r
  49 { $description "Calls the quotation, ensuring that no other thread is holding a read or write lock at the same time. If another thread is holding a read or write lock, blocks until the thread releases the lock." }\r
  50 { $errors "Throws an error if the lock could not be acquired before the timeout expires. A timeout value of " { $link f } " means the thread is willing to wait indefinitely." } ;\r
  51 \r
  52 HELP: with-write-lock\r
  53 { $values { "lock" lock } { "quot" quotation } }\r
  54 { $description "Calls the quotation, ensuring that no other thread is holding a read or write lock at the same time. If another thread is holding a read or write lock, blocks until the thread releases the lock." } ;\r
  55 \r
  56 ARTICLE: "concurrency.locks.rw" "Read-write locks"\r
  57 "A read-write lock encapsulates a common pattern in the implementation of concurrent data structures, where one wishes to ensure that a thread is able to see a consistent view of the structure for a period of time, during which no other thread modifies the structure."\r
  58 $nl\r
  59 "While this can be achieved with a simple " { $link "concurrency.locks.mutex" } ", performance will suffer, since in fact multiple threads can view the structure at the same time; serialization must only be enforced for writes."\r
  60 $nl\r
  61 "Read/write locks allow any number of threads to hold the read lock simulateneously, however attempting to acquire a write lock blocks until all other threads release read locks and write locks."\r
  62 $nl\r
  63 "Read/write locks are reentrant. A thread holding a write lock may acquire a read lock or a write lock without blocking. However a thread holding a read lock may not acquire a write lock recursively since that could break invariants assumed by the code executing with the read lock held."\r
  64 { $subsection rw-lock }\r
  65 { $subsection <rw-lock> }\r
  66 { $subsection with-read-lock }\r
  67 { $subsection with-write-lock }\r
  68 "Versions of the above that take a timeout duration:"\r
  69 { $subsection with-read-lock-timeout }\r
  70 { $subsection with-write-lock-timeout } ;\r
  71 \r
  72 ARTICLE: "concurrency.locks" "Locks"\r
  73 "A " { $emphasis "lock" } " is an object protecting a critical region of code, enforcing a particular mutual-exclusion policy. The " { $vocab-link "concurrency.locks" } " vocabulary implements two types of locks:"\r
  74 { $subsection "concurrency.locks.mutex" }\r
  75 { $subsection "concurrency.locks.rw" } ;\r
  76 \r
  77 ABOUT: "concurrency.locks"\r