(index ("obtain-dot-lock" 0) ("release-dot-lock" 1179) ("break-dot-lock" 1480) ("with-dot-lock" 1820) ("with-dot-lock*" 1820))
(def (sig (procedure "(obtain-dot-lock file-name [interval retry-number stale-time])" (id obtain-dot-lock))) (p "Tries to obtain the lock for file-name. If the file is already locked, the thread sleeps for interval seconds (default is 1) before it retries. If the lock cannot be obtained after retry-number attempts, the procedure returns " (tt "#f") ", otherwise " (tt "#t") ". The default value of retry-number is " (tt "#f") " which corresponds to an infinite number of retries.") (p "If stale-time is non-" (tt "#f") ", it specifies the minimum age a lock may have (in seconds) before it is considered stale. Obtain-dot-lock attempts to delete stale locks. If it was successful obtaining a lock after breaking it, " (tt "obtain-dot-lock") " returns " (tt "'broken") ". If stale-time is " (tt "#f") ", " (tt "obtain-dot-lock") " never considers a lock stale. The default for stale-time is " (tt "300") ".") (p "Note that it is possible that obtain-dot-lock breaks a lock but nevertheless fails to obtain it otherwise. If it is necessary to handle this case specially, use " (tt "break-dot-lock") " directly (see below) rather than specifying a non-" (tt "#f") " stale-time"))
(def (sig (procedure "(release-dot-lock file-name)" (id release-dot-lock))) (p "Releases the lock for " (tt "file-name") ". On success, " (tt "release-dot-lock") " returns " (tt "#t") ", otherwise " (tt "#f") ". Note that this procedure can also be used to break the lock for " (tt "file-name") "."))
(def (sig (procedure "(break-dot-lock file-name)" (id break-dot-lock))) (p "Breaks the lock for " (tt "file-name") " if one exists. Note that breaking a lock does not imply a subsequent " (tt "obtain-dot-lock") " will succeed, as another party may have acquired the lock between " (tt "break-dot-lock") " and " (tt "obtain-dot-lock") "."))
(def (sig (syntax "(with-dot-lock file-name body ...)" (id with-dot-lock)) (procedure "(with-dot-lock* file-name thunk)" (id with-dot-lock*))) (p "The procedure " (tt "with-dot-lock*") " obtains the requested lock, and then calls " (tt "(thunk)") ". When " (tt "thunk") " returns, the lock is released. A non-local exit (e.g., throwing to a saved continuation or raising an exception) also causes the lock to be released.") (p "After a normal return from " (tt "thunk") ", its return values are returned by " (tt "with-dot-lock*") ". The " (tt "with-dot-lock") " special form is equivalent syntactic sugar."))
