6.4 KiB
srw_lock_linux requirements
Overview
srw_lock_linux is an implementation of slim reader-writer lock for linux.
Design
srw_lock_linux can be used for synchronizing resources across threads. It has on exclusive mode for write lock and shared mode for read lock. Acquire APIs will apply the required type of lock to pthread_rwlock_t and get blocked if the operation can not be done. Try acquire APIs will fail if the equivalent acquire APIs get blocked.
Exposed API
typedef struct SRW_LOCK_HANDLE_DATA_TAG* SRW_LOCK_HANDLE;
#define SRW_LOCK_TRY_ACQUIRE_RESULT_VALUES \
SRW_LOCK_TRY_ACQUIRE_OK, \
SRW_LOCK_TRY_ACQUIRE_COULD_NOT_ACQUIRE, \
SRW_LOCK_TRY_ACQUIRE_INVALID_ARGS
MU_DEFINE_ENUM(SRW_LOCK_TRY_ACQUIRE_RESULT, SRW_LOCK_TRY_ACQUIRE_RESULT_VALUES)
MOCKABLE_FUNCTION(, SRW_LOCK_HANDLE, srw_lock_create, bool, do_statistics, const char*, lock_name);
/*writer APIs*/
MOCKABLE_FUNCTION(, void, srw_lock_acquire_exclusive, SRW_LOCK_HANDLE, handle);
MOCKABLE_FUNCTION(, SRW_LOCK_TRY_ACQUIRE_RESULT, srw_lock_try_acquire_exclusive, SRW_LOCK_HANDLE, handle);
MOCKABLE_FUNCTION(, void, srw_lock_release_exclusive, SRW_LOCK_HANDLE, handle);
/*reader APIs*/
MOCKABLE_FUNCTION(, void, srw_lock_acquire_shared, SRW_LOCK_HANDLE, handle);
MOCKABLE_FUNCTION(, SRW_LOCK_TRY_ACQUIRE_RESULT, srw_lock_try_acquire_shared, SRW_LOCK_HANDLE, handle);
MOCKABLE_FUNCTION(, void, srw_lock_release_shared, SRW_LOCK_HANDLE, handle);
MOCKABLE_FUNCTION(, void, srw_lock_destroy, SRW_LOCK_HANDLE, handle);
srw_lock_create
MOCKABLE_FUNCTION(, SRW_LOCK_HANDLE, srw_lock_create, bool, do_statistics, const char*, lock_name);
srw_lock_create creates a new SRW_LOCK_HANDLE.
SRS_SRW_LOCK_LINUX_07_001: [ srw_lock_create shall allocate memory for SRW_LOCK_HANDLE_DATA. ]
SRS_SRW_LOCK_LINUX_07_002: [ srw_lock_create shall copy the lock_name. ]
SRS_SRW_LOCK_LINUX_07_003: [ srw_lock_create shall initialized the pthread_rwlock_t by calling pthread_rwlock_init. ]
SRS_SRW_LOCK_LINUX_07_006: [ If initializing the lock failed, srw_lock_create shall fail and return NULL. ]
SRS_SRW_LOCK_LINUX_07_004: [ srw_lock_create shall succeed and return a non-NULL value. ]
SRS_SRW_LOCK_LINUX_07_005: [ If there are any failures, srw_lock_create shall fail and return NULL. ]
srw_lock_acquire_exclusive
MOCKABLE_FUNCTION(, void, srw_lock_acquire_exclusive, SRW_LOCK_HANDLE, handle);
srw_lock_acquire_exclusive acquires the lock in exclusive (writer) mode.
SRS_SRW_LOCK_LINUX_07_007: [ If handle is NULL, srw_lock_acquire_exclusive shall return. ]
SRS_SRW_LOCK_LINUX_07_008: [ srw_lock_acquire_exclusive shall lock the pthread_rwlock_t for writing by calling pthread_rwlock_wrlock. ]
srw_lock_try_acquire_exclusive
MOCKABLE_FUNCTION(, SRW_LOCK_TRY_ACQUIRE_RESULT, srw_lock_try_acquire_exclusive, SRW_LOCK_HANDLE, handle);
srw_lock_try_acquire_exclusive attempts to acquire the lock in exclusive (writer) mode.
SRS_SRW_LOCK_LINUX_07_009: [ If handle is NULL, srw_lock_try_acquire_exclusive shall fail and return SRW_LOCK_TRY_ACQUIRE_INVALID_ARGS. ]
SRS_SRW_LOCK_LINUX_07_010: [ Otherwise srw_lock_acquire_exclusive shall apply a write lock on pthread_rwlock_t only if no other threads are currently holding the pthread_rwlock_t by calling pthread_rwlock_trywrlock. ]
SRS_SRW_LOCK_LINUX_07_011: [ If pthread_rwlock_trywrlock returns 0, srw_lock_acquire_exclusive shall return SRW_LOCK_TRY_ACQUIRE_OK. ]
SRS_SRW_LOCK_LINUX_07_012: [ Otherwise, srw_lock_acquire_exclusive shall return SRW_LOCK_TRY_ACQUIRE_COULD_NOT_ACQUIRE. ]
srw_lock_release_exclusive
MOCKABLE_FUNCTION(, void, srw_lock_release_exclusive, SRW_LOCK_HANDLE, handle);
srw_lock_release_exclusive releases the underlying pthread_rwlock_t from exclusive (write) mode.
SRS_SRW_LOCK_LINUX_07_013: [ If handle is NULL, srw_lock_release_exclusive shall return. ]
SRS_SRW_LOCK_LINUX_07_014: [ srw_lock_release_exclusive shall release the write lock by calling pthread_rwlock_unlock. ]
srw_lock_acquire_shared
MOCKABLE_FUNCTION(, void, srw_lock_acquire_shared, SRW_LOCK_HANDLE, handle);
srw_lock_acquire_shared acquires the pthread_rwlock_t in shared (read) mode.
SRS_SRW_LOCK_LINUX_07_015: [ If handle is NULL, srw_lock_acquire_shared shall return. ]
SRS_SRW_LOCK_LINUX_07_016: [ srw_lock_acquire_shared shall apply a read lock to pthread_rwlock_t by calling pthread_rwlock_rdlock. ]
srw_lock_try_acquire_shared
MOCKABLE_FUNCTION(, SRW_LOCK_TRY_ACQUIRE_RESULT, srw_lock_try_acquire_shared, SRW_LOCK_HANDLE, handle);
srw_lock_try_acquire_shared attempts to acquire the pthread_rwlock_t in shared (read) mode.
SRS_SRW_LOCK_LINUX_07_017: [ If handle is NULL then srw_lock_try_acquire_shared shall fail and return SRW_LOCK_TRY_ACQUIRE_INVALID_ARGS. ]
SRS_SRW_LOCK_LINUX_07_018: [ Otherwise srw_lock_try_acquire_shared shall apply a read lock on pthread_rwlock_t if there's no writers hold the lock and no writers blocked on the lock by calling pthread_rwlock_tryrdlock. ]
SRS_SRW_LOCK_LINUX_07_019: [ If pthread_rwlock_tryrdlock returns 0, srw_lock_try_acquire_shared shall return SRW_LOCK_TRY_ACQUIRE_OK. ]
SRS_SRW_LOCK_LINUX_07_020: [ Otherwise, srw_lock_try_acquire_shared shall return SRW_LOCK_TRY_ACQUIRE_COULD_NOT_ACQUIRE. ]
srw_lock_release_shared
MOCKABLE_FUNCTION(, void, srw_lock_release_shared, SRW_LOCK_HANDLE, handle);
srw_lock_release_exclusive releases the underlying pthread_rwlock_t from shared (read) mode.
SRS_SRW_LOCK_LINUX_07_021: [ If handle is NULL, srw_lock_release_shared shall return. ]
SRS_SRW_LOCK_LINUX_07_022: [ srw_lock_release_shared shall release the read lock by calling pthread_rwlock_unlock. ]
srw_lock_destroy
MOCKABLE_FUNCTION(, void, srw_lock_destroy, SRW_LOCK_HANDLE, handle);
srw_lock_destroy frees all used resources.
SRS_SRW_LOCK_LINUX_07_023: [ If handle is NULL then srw_lock_destroy shall return. ]
SRS_SRW_LOCK_LINUX_07_024: [ srw_lock_destroy shall free the stored lock name. ]
SRS_SRW_LOCK_LINUX_07_025: [ srw_lock_destroy shall destroy the pthread_rwlock_t by calling pthread_rwlock_destroy. ]
SRS_SRW_LOCK_LINUX_07_026: [ srw_lock_destroy shall free the lock handle. ]