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" { $maybe duration } } { "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 { $subsections\r
  30     lock\r
  31     <lock>\r
  32     <reentrant-lock>\r
  33     with-lock\r
  34     with-lock-timeout\r
  35 } ;\r
  36 \r
  37 HELP: rw-lock\r
  38 { $class-description "The class of reader/writer locks." } ;\r
  39 \r
  40 HELP: with-read-lock-timeout\r
  41 { $values { "lock" lock } { "timeout" { $maybe duration } } { "quot" quotation } }\r
  42 { $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
  43 { $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
  44 \r
  45 HELP: with-read-lock\r
  46 { $values { "lock" lock } { "quot" quotation } }\r
  47 { $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
  48 \r
  49 HELP: with-write-lock-timeout\r
  50 { $values { "lock" lock } { "timeout" { $maybe duration } } { "quot" quotation } }\r
  51 { $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
  52 { $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
  53 \r
  54 HELP: with-write-lock\r
  55 { $values { "lock" lock } { "quot" quotation } }\r
  56 { $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
  57 \r
  58 ARTICLE: "concurrency.locks.rw" "Read-write locks"\r
  59 "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
  60 $nl\r
  61 "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
  62 $nl\r
  63 "Read/write locks allow any number of threads to hold the read lock simultaneously, however attempting to acquire a write lock blocks until all other threads release read locks and write locks."\r
  64 $nl\r
  65 "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
  66 { $subsections\r
  67     rw-lock\r
  68     <rw-lock>\r
  69     with-read-lock\r
  70     with-write-lock\r
  71 }\r
  72 "Versions of the above that take a timeout duration:"\r
  73 { $subsections\r
  74     with-read-lock-timeout\r
  75     with-write-lock-timeout\r
  76 } ;\r
  77 \r
  78 ARTICLE: "concurrency.locks" "Locks"\r
  79 "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
  80 { $subsections\r
  81     "concurrency.locks.mutex"\r
  82     "concurrency.locks.rw"\r
  83 } ;\r
  84 \r
  85 ABOUT: "concurrency.locks"\r