mirror of https://github.com/dzavalishin/oskit/
257 lines
7.7 KiB
TeX
Executable File
257 lines
7.7 KiB
TeX
Executable File
%
|
|
% Copyright (c) 1997-1999 University of Utah and the Flux Group.
|
|
% All rights reserved.
|
|
%
|
|
% The University of Utah grants you the right to copy and reproduce this
|
|
% document or portions thereof for academic, research, evaluation, and
|
|
% personal use only, provided that (1) the title page appears prominently,
|
|
% and (2) these copyright and permission notices are retained in all copies.
|
|
% To arrange for alternate terms, contact the University of Utah at
|
|
% csl-dist@cs.utah.edu or +1-801-585-3271.
|
|
%
|
|
\label{synch}
|
|
|
|
\apiintf{oskit_lock}{Thread-safe lock interface}
|
|
|
|
The {\tt oskit_lock} COM interface allows components to protect data
|
|
structures from concurrent access by multiple threads. The interface is
|
|
intended to be generic so that components do not need to know the specifics
|
|
of any particular thread system. The user of a lock should be prepared for
|
|
the possibility that the thread will be put to sleep if the lock cannot be
|
|
granted. There are two variants supported; a regular lock and a critical
|
|
lock. A critical lock differs only in that interrupts are blocked while the
|
|
lock is held. The {\tt oskit_lock} COM interface inherits from {\tt
|
|
oskit_iunknown}, and has the following additional methods:
|
|
|
|
\begin{icsymlist}
|
|
\item[lock]
|
|
Lock a lock.
|
|
\item[unlock]
|
|
Unlock a lock.
|
|
\end{icsymlist}
|
|
|
|
\api{lock}{Lock a lock}
|
|
\begin{apisyn}
|
|
\cinclude{oskit/com/lock.h}
|
|
|
|
\funcproto OSKIT_COMDECL
|
|
oskit_lock_lock(oskit_lock_t *lock);
|
|
\end{apisyn}
|
|
\begin{apidesc}
|
|
This method attempts to lock {\tt lock}. If the lock cannot be
|
|
immediately granted, the current thread is put to sleep until the
|
|
lock can be granted.
|
|
\end{apidesc}
|
|
\begin{apiparm}
|
|
\item[lock]
|
|
The {\tt oskit_lock} COM interface for the lock.
|
|
\end{apiparm}
|
|
\begin{apiret}
|
|
Returns 0 on success, or an error code specified in
|
|
{\tt <oskit/error.h>}, on error.
|
|
\end{apiret}
|
|
|
|
|
|
\api{lock}{Unlock a lock}
|
|
\begin{apisyn}
|
|
\cinclude{oskit/com/lock.h}
|
|
|
|
\funcproto OSKIT_COMDECL
|
|
oskit_lock_unlock(oskit_lock_t *lock);
|
|
\end{apisyn}
|
|
\begin{apidesc}
|
|
This method unlocks {\tt lock}. If there are any threads waiting for
|
|
the lock, one will be woken up and granted the lock.
|
|
\end{apidesc}
|
|
\begin{apiparm}
|
|
\item[lock]
|
|
The {\tt oskit_lock} COM interface for the lock.
|
|
\end{apiparm}
|
|
\begin{apiret}
|
|
Returns 0 on success, or an error code specified in
|
|
{\tt <oskit/error.h>}, on error.
|
|
\end{apiret}
|
|
|
|
|
|
\apiintf{oskit_condvar}{Condition variable interface}
|
|
|
|
The {\tt oskit_condvar} COM interface allows components to wait for
|
|
conditions. The interface is intended to be generic so that components do
|
|
not need to know the specifics of any particular thread system. A condition
|
|
is typically combined with an {\tt oskit_lock} object to facilitate building
|
|
monitor type objects. Attempting to wait on a condition without supplying a
|
|
locked {\tt oskit_lock} object results in undefined behavior. The {\tt
|
|
oskit_lock} COM interface inherits from {\tt oskit_iunknown}, and has the
|
|
following additional methods:
|
|
|
|
\begin{icsymlist}
|
|
\item[wait]
|
|
Wait on a condition variable.
|
|
\item[signal]
|
|
Signal a condition variable.
|
|
\item[broadcast]
|
|
Broadcast a condition variable.
|
|
\end{icsymlist}
|
|
|
|
\api{wait}{Wait on a condition variable}
|
|
\begin{apisyn}
|
|
\cinclude{oskit/com/condvar.h}
|
|
|
|
\funcproto OSKIT_COMDECL
|
|
oskit_condvar_wait(oskit_condvar_t *condvar, oskit_lock_t *lock);
|
|
\end{apisyn}
|
|
\begin{apidesc}
|
|
This method causes the current thread is to wait until the
|
|
condition variable is signaled or broadcast. The {\tt oskit_lock}
|
|
object must be locked when called. The lock is released prior to
|
|
waiting, and reacquired before returning.
|
|
\end{apidesc}
|
|
\begin{apiparm}
|
|
\item[condvar]
|
|
The {\tt oskit_condvar} COM interface for the condition
|
|
variable.
|
|
\item[lock]
|
|
The {\tt oskit_lock} COM interface for the lock.
|
|
\end{apiparm}
|
|
\begin{apiret}
|
|
Returns 0 on success, or an error code specified in
|
|
{\tt <oskit/error.h>}, on error.
|
|
\end{apiret}
|
|
|
|
\api{signal}{Signal a condition variable}
|
|
\begin{apisyn}
|
|
\cinclude{oskit/com/condvar.h}
|
|
|
|
\funcproto OSKIT_COMDECL
|
|
oskit_condvar_signal(oskit_condvar_t *condvar);
|
|
\end{apisyn}
|
|
\begin{apidesc}
|
|
Wake up exactly one thread waiting on the condition variable object
|
|
{\tt condvar}.
|
|
\end{apidesc}
|
|
\begin{apiparm}
|
|
\item[condvar]
|
|
The {\tt oskit_condvar} COM interface for the condition
|
|
variable.
|
|
\end{apiparm}
|
|
\begin{apiret}
|
|
Returns 0 on success, or an error code specified in
|
|
{\tt <oskit/error.h>}, on error.
|
|
\end{apiret}
|
|
|
|
\api{broadcast}{Broadcast a condition variable}
|
|
\begin{apisyn}
|
|
\cinclude{oskit/com/condvar.h}
|
|
|
|
\funcproto OSKIT_COMDECL
|
|
oskit_condvar_broadcast(oskit_condvar_t *condvar);
|
|
\end{apisyn}
|
|
\begin{apidesc}
|
|
Wake up all threads waiting on the condition variable object
|
|
{\tt condvar}.
|
|
\end{apidesc}
|
|
\begin{apiparm}
|
|
\item[condvar]
|
|
The {\tt oskit_condvar} COM interface for the condition
|
|
variable.
|
|
\end{apiparm}
|
|
\begin{apiret}
|
|
Returns 0 on success, or an error code specified in
|
|
{\tt <oskit/error.h>}, on error.
|
|
\end{apiret}
|
|
|
|
|
|
\apiintf{oskit_lock_mgr}{Lock manager: Interface for creating locks and
|
|
condition variables}
|
|
\label{lock-mgr}
|
|
|
|
The lock manager is registered in the services registry (See
|
|
Section~\ref{oskit-services}) when the threading system (if it is included)
|
|
is initialized. Components that need to protect data structures can query
|
|
the services registry for the lock manager. Since the lock manager will
|
|
only be registered by the threading system, the client can assume that the
|
|
absence of a lock manager implies a single threaded system (locks are
|
|
unnecessary). The {\tt oskit_lock_mgr} COM interface inherits from {\tt
|
|
oskit_iunknown}, and has the following additional methods:
|
|
|
|
\begin{csymlist}
|
|
\item[allocate_lock]
|
|
Allocate a lock object.
|
|
\item[allocate_critical_lock]
|
|
Allocate a critical lock object.
|
|
\end{csymlist}
|
|
|
|
\api{allocate_lock}{Allocate a thread-safe lock}
|
|
\begin{apisyn}
|
|
\cinclude{oskit/com/lock_mgr.h}
|
|
|
|
\funcproto OSKIT_COMDECL
|
|
oskit_lock_mgr_allocate_lock(oskit_lock_mgr_t *lmgr,
|
|
\outparam oskit_lock_t *out_lock);
|
|
\end{apisyn}
|
|
\begin{apidesc}
|
|
This method returns an {\tt oskit_lock_t} COM interface in {\tt
|
|
out_lock}.
|
|
\end{apidesc}
|
|
\begin{apiparm}
|
|
\item[lmgr]
|
|
The lock manager COM interface.
|
|
\item[out_lock]
|
|
The {\tt oskit_lock} COM interface for the new lock.
|
|
\end{apiparm}
|
|
\begin{apiret}
|
|
Returns 0 on success, or an error code specified in
|
|
{\tt <oskit/error.h>}, on error.
|
|
\end{apiret}
|
|
|
|
|
|
\api{allocate_critical_lock}{Allocate a critical thread-safe lock}
|
|
\begin{apisyn}
|
|
\cinclude{oskit/com/lock_mgr.h}
|
|
|
|
\funcproto OSKIT_COMDECL
|
|
oskit_lock_mgr_allocate_critical_lock(oskit_lock_mgr_t *lmgr,
|
|
\outparam oskit_lock_t *out_lock);
|
|
\end{apisyn}
|
|
\begin{apidesc}
|
|
This method returns an {\tt oskit_lock_t} COM interface in {\tt
|
|
out_lock}. The lock is flagged as critical so that interrupts are
|
|
blocked while the lock is held.
|
|
\end{apidesc}
|
|
\begin{apiparm}
|
|
\item[lmgr]
|
|
The lock manager COM interface.
|
|
\item[out_lock]
|
|
The {\tt oskit_lock} COM interface for the new lock.
|
|
\end{apiparm}
|
|
\begin{apiret}
|
|
Returns 0 on success, or an error code specified in
|
|
{\tt <oskit/error.h>}, on error.
|
|
\end{apiret}
|
|
|
|
\api{allocate_condvar}{Allocate a condition variable}
|
|
\begin{apisyn}
|
|
\cinclude{oskit/com/lock_mgr.h}
|
|
|
|
\funcproto OSKIT_COMDECL
|
|
oskit_lock_mgr_allocate_condvar(oskit_lock_mgr_t *lmgr,
|
|
\outparam oskit_condvar_t *out_condvar);
|
|
\end{apisyn}
|
|
\begin{apidesc}
|
|
This method returns an {\tt oskit_condvar_t} COM interface in {\tt
|
|
out_condvar}. Condition variables may be used in conjunction with locks
|
|
to form monitors.
|
|
\end{apidesc}
|
|
\begin{apiparm}
|
|
\item[lmgr]
|
|
The lock manager COM interface.
|
|
\item[out_condvar]
|
|
The {\tt oskit_condvar} COM interface for the new condition
|
|
variable.
|
|
\end{apiparm}
|
|
\begin{apiret}
|
|
Returns 0 on success, or an error code specified in
|
|
{\tt <oskit/error.h>}, on error.
|
|
\end{apiret}
|
|
|