| 1 |
`srw_lock` requirements |
| 2 |
============ |
| 3 |
|
| 4 |
## Overview |
| 5 |
|
| 6 |
`srw_lock` is a wrapper over a `SRWLOCK` with the additional benefit of having some statistics printed. |
| 7 |
|
| 8 |
## Exposed API |
| 9 |
|
| 10 |
```c |
| 11 |
|
| 12 |
typedef struct SRW_LOCK_HANDLE_DATA_TAG* SRW_LOCK_HANDLE; |
| 13 |
|
| 14 |
MOCKABLE_FUNCTION(, SRW_LOCK_HANDLE, srw_lock_create, bool, do_statistics, const char*, lock_name); |
| 15 |
|
| 16 |
/*writer APIs*/ |
| 17 |
MOCKABLE_FUNCTION(, void, srw_lock_acquire_exclusive, SRW_LOCK_HANDLE, handle); |
| 18 |
MOCKABLE_FUNCTION(, void, srw_lock_release_exclusive, SRW_LOCK_HANDLE, handle); |
| 19 |
|
| 20 |
/*reader APIs*/ |
| 21 |
MOCKABLE_FUNCTION(, void, srw_lock_acquire_shared, SRW_LOCK_HANDLE, handle); |
| 22 |
MOCKABLE_FUNCTION(, void, srw_lock_release_shared, SRW_LOCK_HANDLE, handle); |
| 23 |
|
| 24 |
MOCKABLE_FUNCTION(, void, srw_lock_destroy, SRW_LOCK_HANDLE, handle); |
| 25 |
|
| 26 |
``` |
| 27 |
|
| 28 |
### srw_lock_create |
| 29 |
```c |
| 30 |
MOCKABLE_FUNCTION(, SRW_LOCK_HANDLE, srw_lock_create, bool, do_statistics, const char*, lock_name); |
| 31 |
``` |
| 32 |
|
| 33 |
`srw_lock_create` creates a new `SRW_LOCK_HANDLE`. |
| 34 |
|
| 35 |
**SRS_SRW_LOCK_02_001: [** `srw_lock_create` shall allocate memory for `SRW_LOCK_HANDLE`. **]** |
| 36 |
|
| 37 |
**SRS_SRW_LOCK_02_015: [** `srw_lock_create` shall call `InitializeSRWLock`. **]** |
| 38 |
|
| 39 |
**SRS_SRW_LOCK_02_023: [** If `do_statistics` is `true` then `srw_lock_create` shall copy `lock_name`. **]** |
| 40 |
|
| 41 |
**SRS_SRW_LOCK_02_024: [** If `do_statistics` is `true` then `srw_lock_create` shall create a new `TIMER_HANDLE` by calling `timer_create`. **]** |
| 42 |
|
| 43 |
**SRS_SRW_LOCK_02_003: [** `srw_lock_create` shall succeed and return a non-`NULL` value. **]** |
| 44 |
|
| 45 |
**SRS_SRW_LOCK_02_004: [** If there are any failures then `srw_lock_create` shall fail and return `NULL`. **]** |
| 46 |
|
| 47 |
### srw_lock_acquire_exclusive |
| 48 |
```c |
| 49 |
MOCKABLE_FUNCTION(, void, srw_lock_acquire_exclusive, SRW_LOCK_HANDLE, handle); |
| 50 |
``` |
| 51 |
|
| 52 |
`srw_lock_acquire_exclusive` acquires the lock in exclusive (writer) mode. |
| 53 |
|
| 54 |
**SRS_SRW_LOCK_02_022: [** If `handle` is `NULL` then `srw_lock_acquire_exclusive` shall return. **]** |
| 55 |
|
| 56 |
**SRS_SRW_LOCK_02_006: [** `srw_lock_acquire_exclusive` shall call `AcquireSRWLockExclusive`. **]** |
| 57 |
|
| 58 |
**SRS_SRW_LOCK_02_025: [** If `do_statistics` is `true` and if the timer created has recorded more than `TIME_BETWEEN_STATISTICS_LOG` seconds then statistics will be logged and the timer shall be started again. **]** |
| 59 |
|
| 60 |
|
| 61 |
### srw_lock_release_exclusive |
| 62 |
```c |
| 63 |
MOCKABLE_FUNCTION(, void, srw_lock_release_exclusive, SRW_LOCK_HANDLE, handle); |
| 64 |
``` |
| 65 |
|
| 66 |
`srw_lock_release_exclusive` releases the underlying `SRWLOCK` from exclusive (write) mode. |
| 67 |
|
| 68 |
**SRS_SRW_LOCK_02_009: [** If `handle` is `NULL` then `srw_lock_release_exclusive` shall return. **]** |
| 69 |
|
| 70 |
**SRS_SRW_LOCK_02_010: [** `srw_lock_release_exclusive` shall call `ReleaseSRWLockExclusive`. **]** |
| 71 |
|
| 72 |
|
| 73 |
### srw_lock_acquire_shared |
| 74 |
```c |
| 75 |
MOCKABLE_FUNCTION(, void, srw_lock_acquire_shared, SRW_LOCK_HANDLE, handle); |
| 76 |
``` |
| 77 |
|
| 78 |
`srw_lock_acquire_shared` acquires the SRWLOCK in shared (read) mode. |
| 79 |
|
| 80 |
**SRS_SRW_LOCK_02_017: [** If `handle` is `NULL` then `srw_lock_acquire_shared` shall return. **]** |
| 81 |
|
| 82 |
**SRS_SRW_LOCK_02_018: [** `srw_lock_acquire_shared` shall call `AcquireSRWLockShared`. **]** |
| 83 |
|
| 84 |
**SRS_SRW_LOCK_02_026: [** If `do_statistics` is `true` and the timer created has recorded more than `TIME_BETWEEN_STATISTICS_LOG` seconds then statistics will be logged and the timer shall be started again. **]** |
| 85 |
|
| 86 |
|
| 87 |
### srw_lock_release_shared |
| 88 |
```c |
| 89 |
MOCKABLE_FUNCTION(, void, srw_lock_release_shared, SRW_LOCK_HANDLE, handle); |
| 90 |
``` |
| 91 |
|
| 92 |
**SRS_SRW_LOCK_02_020: [** If `handle` is `NULL` then `srw_lock_release_shared` shall return. **]** |
| 93 |
|
| 94 |
**SRS_SRW_LOCK_02_021: [** `srw_lock_release_shared` shall call `ReleaseSRWLockShared`. **]** |
| 95 |
|
| 96 |
|
| 97 |
### srw_lock_destroy |
| 98 |
```c |
| 99 |
MOCKABLE_FUNCTION(, void, srw_lock_destroy, SRW_LOCK_HANDLE, handle); |
| 100 |
``` |
| 101 |
|
| 102 |
`srw_lock_destroy` frees all used resources. |
| 103 |
|
| 104 |
**SRS_SRW_LOCK_02_011: [** If `handle` is `NULL` then `srw_lock_destroy` shall return. **]** |
| 105 |
|
| 106 |
**SRS_SRW_LOCK_02_012: [** `srw_lock_destroy` shall free all used resources. **]** |
| 107 |
|