Updated documentation for dot-locking.

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}