Debian Codegraph @

src/vendor/azure-uamqp-c/deps/azure-c-shared-utility/devdoc/srw_lock_requirements.md

raw
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