diff --git a/doc/scsh-manual/miscprocs.tex b/doc/scsh-manual/miscprocs.tex index 9eb9336..6d8e0f6 100644 --- a/doc/scsh-manual/miscprocs.tex +++ b/doc/scsh-manual/miscprocs.tex @@ -67,35 +67,59 @@ may generate the lock for a given file. Here is scsh's interface to dot-locking: -\defun {obtain-dot-lock} {filename [interval retry-number]} {\boolean} +\defun {obtain-dot-lock} {filename [interval retry-number stale-time]} {\boolean} -Tries to obtain the lock for \var{filename}. If the file is already -locked, the thread sleeps for \var{interval} milliseconds (default is -1000) before it retries. If the lock cannot be obtained after -\var{retry-number} attempts, the procedure returns \sharpf, otherwise -\sharpt. The default value of \var{retry-number} is \sharpf which -corresponds to an infinite number of retires. +\begin{desc} + Tries to obtain the lock for \var{filename}. If the file is already + locked, the thread sleeps for \var{interval} seconds (default is 1) + before it retries. If the lock cannot be obtained after + \var{retry-number} attempts, the procedure returns \sharpf, + otherwise \sharpt. The default value of \var{retry-number} is + \sharpf which corresponds to an infinite number of retires. + + If \var{stale-time} is non-\sharpf, it specifies the minimum age a + lock may have (in seconds) before it is considered \textit{stale}. + \ex{Obtain-dot-lock} attempts to delete stale locks. If it was + succcessful obtaining a lock after breaking it, \ex{obtain-dot-lock} + returns \ex{broken}. If \var{stale-time} is \sharpf, + \ex{obtain-dot-lock} never considers a lock stale. The default for + \var{stale-time} is 300. + + Note that it is possible that \ex{obtain-dot-lock} breaks a lock + but nevertheless fails to obtain it otherwise. If it is necessary + to handle this case specially, use \ex{break-dot-lock} directly + (see below) rather than specifying a non-\sharpf \var{stale-time} +\end{desc} + +\defun {break-dot-lock} {filename} {undefined} + +\begin{desc} + Breaks the lock for \var{filename} if one exists. +\end{desc} \defun {release-dot-lock} {filename} {\boolean} -Releases the lock for \var{filename}. On success, -\ex{release-dot-lock} returns \sharpt, otherwise \sharpf. Note that -this procedure can also be used to break the lock for \var{filename}. +\begin{desc} + Releases the lock for \var{filename}. On success, + \ex{release-dot-lock} returns \sharpt, otherwise \sharpf. Note that + this procedure can also be used to break the lock for + \var{filename}. +\end{desc} + \defun{with-dot-lock*} {filename thunk} {value(s) of thunk} -\dfnx {with-dot-lock} {filename body \ldots} {value(s) of body}{syntax} - -This procedure obtains the requested lock, and then calls -\ex{(\var{thunk})}. When \var{thunk} returns, the lock is released. -A non-local exit (\eg, throwing to a saved continuation or raising -an exception) also causes the lock to be released. - -After a normal return from \var{thunk}, its return values are returned -by \ex{with-dot-lock*}. -The \ex{with-dot-lock} special form is equivalent syntactic sugar. - - - +\dfnx{with-dot-lock} {filename body \ldots} {value(s) of body}{syntax} + +\begin{desc} + This procedure obtains the requested lock, and then calls + \ex{(\var{thunk})}. When \var{thunk} returns, the lock is released. + A non-local exit (\eg, throwing to a saved continuation or raising + an exception) also causes the lock to be released. + + After a normal return from \var{thunk}, its return values are + returned by \ex{with-dot-lock*}. The \ex{with-dot-lock} special + form is equivalent syntactic sugar. +\end{desc} \section{Syslog facility} \label{syslog-facility}