% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\section{library(rwlocks): Read/write locks}

\label{sec:rwlocks}

This library implements \textit{read/write} locks on top of \predref{with_mutex}{2}.
\textit{Read/write} locks are synchronization objects that allow for multiple
readers or a single writer to be active.\vspace{0.7cm}

\begin{description}
    \predicate{with_rwlock}{3}{+LockId, :Goal, +ModeSpec}
\nodescription
    \predicate{with_rwlock}{4}{+LockId, :Goal, +ModeSpec, +Options}
Run \arg{Goal}, synchronized with \arg{LockId} in \arg{ModeSpec}. \arg{ModeSpec} is one of
\const{read}, \const{write}, \verb$read(Priority)$ or \verb$write(Priority)$. The default
\const{read} priority is 100 and the default \const{write} priority is 200.
These values prioritize writers over readers. \arg{Goal} may start if

\begin{itemize}
    \item If there is no goal waiting with higher priority \textbf{and}

\begin{shortlist}
    \item It is a read goal and no write goal is running \textbf{or}
    \item It is a write goal and no other goal is running.
\end{shortlist}
\end{itemize}

If \arg{Goal} may not start immediately the thread waits using
\predref{thread_wait}{2}. The \arg{Options} \const{timeout} and \const{deadline} are passed to
\predref{thread_wait}{2}. If the time limit is exceeded an exception is raised.

\textit{Read/write} locks are widely critized for their poor behaviour on
several workloads. They perform well in scenarios where read
operations take long, and write operations are relatively fast and
occur only occasionally. \textit{Transactions}, as implemented by
\predref{transaction}{1},2 are often a better alternative.

This predicate uses a normal mutex and a flag with the same name. See
\predref{with_mutex}{2} and \predref{flag}{3}. Neither the mutex nor the flag should be
used directly.

\begin{tags}
    \tag{throws}
\verb$time_limit_exceeded(rwlock)$ if a timeout or deadline is
specified and this is exceeded.
    \tag{bug}
The current implementation is written in Prolog and comes with
significant overhead. It is intended to synchronize slow operations.
\end{tags}
\end{description}