113 lines
3.7 KiB
C
113 lines
3.7 KiB
C
/**
|
|
* @file kLock.h
|
|
* @brief Declares the kLock class.
|
|
*
|
|
* @internal
|
|
* Copyright (C) 2005-2021 by LMI Technologies Inc.
|
|
* Licensed under the MIT License.
|
|
* Redistributed files must retain the above copyright notice.
|
|
*/
|
|
#ifndef K_API_LOCK_H
|
|
#define K_API_LOCK_H
|
|
|
|
#include <kApi/kApiDef.h>
|
|
|
|
/**
|
|
* @class kLockOption
|
|
* @extends kValue
|
|
* @ingroup kApi-Threads
|
|
* @brief Represents a lock construction option.
|
|
*/
|
|
typedef k32s kLockOption;
|
|
|
|
/** @relates kLockOption @{ */
|
|
#define kLOCK_OPTION_NONE (0x0) ///< No options
|
|
#define kLOCK_OPTION_TIMEOUT (0x1) ///< Can wait with timeout.
|
|
/** @} */
|
|
|
|
#include <kApi/Threads/kLock.x.h>
|
|
|
|
/**
|
|
* @class kLock
|
|
* @extends kObject
|
|
* @ingroup kApi-Threads
|
|
* @brief Represents a recursive, mutual exclusion lock.
|
|
*
|
|
* The kLock class optionally supports lock timeouts. Use the kLock_ConstructEx
|
|
* method with kLOCK_OPTION_TIMEOUT to construct a lock that can support the use of finite
|
|
* timeout values in the kLock_EnterEx method.
|
|
*/
|
|
|
|
/**
|
|
* Constructs a lock object.
|
|
*
|
|
* The constructed object does not support timeouts. When used with the kLock_EnterEx method,
|
|
* kINFINITE is the only supported timeout value.
|
|
*
|
|
* @public @memberof kLock
|
|
* @param lock Destination for the constructed object handle.
|
|
* @param allocator Memory allocator (or kNULL for default).
|
|
* @return Operation status.
|
|
*/
|
|
kFx(kStatus) kLock_Construct(kLock* lock, kAlloc allocator);
|
|
|
|
/**
|
|
* Constructs a lock object with support for behavioral options.
|
|
*
|
|
* If kLOCK_OPTION_TIMEOUT is specified, a finite timeout value can be used with kLock_EnterEx.
|
|
*
|
|
* @public @memberof kLock
|
|
* @param lock Destination for the constructed object handle.
|
|
* @param options Bitset of lock options.
|
|
* @param allocator Memory allocator (or kNULL for default).
|
|
* @return Operation status.
|
|
*/
|
|
kFx(kStatus) kLock_ConstructEx(kLock* lock, kLockOption options, kAlloc allocator);
|
|
|
|
/**
|
|
* Blocks until exclusive ownership of the lock is acquired.
|
|
*
|
|
* kLock ownership is recursive; the same thread can acquire the lock multiple
|
|
* times without blocking. The lock will be relinquished when the number of
|
|
* calls to kLock_Exit balances the number of successful calls to kLockEnter/kLockEnterEx.
|
|
*
|
|
* @public @memberof kLock
|
|
* @param lock Lock object.
|
|
* @return Operation status.
|
|
*/
|
|
kFx(kStatus) kLock_Enter(kLock lock);
|
|
|
|
/**
|
|
* Blocks until exclusive ownership of the lock is acquired or the timeout interval has elapsed.
|
|
*
|
|
* kLock ownership is recursive; the same thread can acquire the lock multiple
|
|
* times without blocking. The lock will be relinquished when the number of
|
|
* calls to kLock_Exit balances the number of successful calls to kLockEnter/kLockEnterEx.
|
|
*
|
|
* kERROR_TIMEOUT is returned if the timeout elapses before the lock can be acquired.
|
|
*
|
|
* A debug assertion may be raised if a finite timeout is specified and the lock does not support
|
|
* timeouts.
|
|
*
|
|
* @public @memberof kLock
|
|
* @param lock Lock object.
|
|
* @param timeout Timeout in microseconds.
|
|
* @return Operation status.
|
|
*/
|
|
kFx(kStatus) kLock_EnterEx(kLock lock, k64u timeout);
|
|
|
|
/**
|
|
* Relinquishes ownership of the lock.
|
|
*
|
|
* kLock ownership is recursive; the same thread can acquire the lock multiple
|
|
* times without blocking. The lock will be relinquished when the number of
|
|
* calls to kLock_Exit balances the number of successful calls to kLockEnter/kLockEnterEx.
|
|
*
|
|
* @public @memberof kLock
|
|
* @param lock Lock object.
|
|
* @return Operation status.
|
|
*/
|
|
kFx(kStatus) kLock_Exit(kLock lock);
|
|
|
|
#endif
|