The 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 oskit_lock COM interface inherits from oskit_iunknown, and has the following additional methods:
This method attempts to lock lock. If the lock cannot be immediately granted, the current thread is put to sleep until the lock can be granted.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
This method unlocks lock. If there are any threads waiting for the lock, one will be woken up and granted the lock.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
The 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 oskit_lock object to facilitate building monitor type objects. Attempting to wait on a condition without supplying a locked oskit_lock object results in undefined behavior. The oskit_lock COM interface inherits from oskit_iunknown, and has the following additional methods:
#include <oskit/com/condvar.h>
OSKIT_COMDECL oskit_condvar_wait(oskit_condvar_t *condvar, oskit_lock_t *lock);
This method causes the current thread is to wait until the condition variable is signaled or broadcast. The oskit_lock object must be locked when called. The lock is released prior to waiting, and reacquired before returning.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
Wake up exactly one thread waiting on the condition variable object condvar.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
Wake up all threads waiting on the condition variable object condvar.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
The lock manager is registered in the services registry (See Section 5.1) 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 oskit_lock_mgr COM interface inherits from oskit_iunknown, and has the following additional methods:
#include <oskit/com/lock_mgr.h>
OSKIT_COMDECL oskit_lock_mgr_allocate_lock(oskit_lock_mgr_t *lmgr, [out] oskit_lock_t *out_lock);
This method returns an oskit_lock_t COM interface in out_lock.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
#include <oskit/com/lock_mgr.h>
OSKIT_COMDECL oskit_lock_mgr_allocate_critical_lock(oskit_lock_mgr_t *lmgr, [out] oskit_lock_t *out_lock);
This method returns an oskit_lock_t COM interface in out_lock. The lock is flagged as critical so that interrupts are blocked while the lock is held.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.
#include <oskit/com/lock_mgr.h>
OSKIT_COMDECL oskit_lock_mgr_allocate_condvar(oskit_lock_mgr_t *lmgr, [out] oskit_condvar_t *out_condvar);
This method returns an oskit_condvar_t COM interface in out_condvar. Condition variables may be used in conjunction with locks to form monitors.
Returns 0 on success, or an error code specified in <oskit/error.h>, on error.