Debian Codegraph @

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

raw
1 Condition Requirements
2 ================
3
4
5 ## Overview
6
7 Condition is a module which allows thread synchronization to occur in a cross-platform manner.
8 It provides a mechanism for signalling events between threads and for waiting on events in a platform-independent manner.
9
10 ## References
11
12 [lock](lock_requirements.md)
13
14 ## Exposed API
15 ```C
16 /**
17 * @brief This API creates and returns a valid condition handle.
18 *
19 * @return A valid @c COND_HANDLE when successful or @c NULL otherwise.
20 */
21 extern COND_HANDLE Condition_Init(void);
22
23 /**
24 * @brief unblock all currently working condition.
25 *
26 * @param handle A valid handle to the lock.
27 *
28 * @return Returns @c COND_OK when the condition object has been
29 * destroyed and @c COND_ERROR when an error occurs
30 * and @c COND_TIMEOUT when the handle times out.
31 */
32 extern COND_RESULT Condition_Post(COND_HANDLE handle);
33
34 /**
35 * @brief block on the condition handle unti the thread is signalled
36 * or until the timeout_milliseconds is reached.
37 *
38 * @param handle A valid handle to the lock.
39 *
40 * @return Returns @c COND_OK when the condition object has been
41 * destroyed and @c COND_ERROR when an error occurs
42 * and @c COND_TIMEOUT when the handle times out.
43 */
44 extern COND_RESULT Condition_Wait(COND_HANDLE handle, LOCK_HANDLE lock, int timeout_milliseconds);
45
46 /**
47 * @brief The condition instance is deinitialized.
48 *
49 * @param handle A valid handle to the condition.
50 *
51 * @return Returns @c COND_OK when the condition object has been
52 * destroyed and @c COND_ERROR when an error occurs.
53 */
54 extern void Condition_Deinit(COND_HANDLE handle);
55 ```
56
57 ### Condition_Init
58 ```C
59 extern COND_HANDLE Condition_Init(void);
60 ```
61
62 **SRS_CONDITION_18_002: [** `Condition_Init` shall create and return a `CONDITION_HANDLE` **]**
63
64 **SRS_CONDITION_18_008: [** `Condition_Init` shall return `NULL` if it fails to allocate the `CONDITION_HANDLE` **]**
65
66
67 ### Condition_Post
68 ```C
69 extern COND_RESULT Condition_Post(COND_HANDLE handle);
70 ```
71
72 **SRS_CONDITION_18_003: [** `Condition_Post` shall return `COND_OK` if it succcessfully posts the condition **]**
73
74 **SRS_CONDITION_18_001: [** `Condition_Post` shall return `COND_INVALID_ARG` if `handle` is `NULL` **]**
75
76
77 ### Condition_Wait
78 ```C
79 extern COND_RESULT Condition_Wait(COND_HANDLE handle, LOCK_HANDLE lock, int timeout_milliseconds);
80 ```
81
82 **SRS_CONDITION_18_004: [** `Condition_Wait` shall return `COND_INVALID_ARG` if `handle` is `NULL` **]**
83
84 **SRS_CONDITION_18_005: [** `Condition_Wait` shall return `COND_INVALID_ARG` if `lock` is `NULL` and `timeout_milliseconds` is `0` **]**
85
86 **SRS_CONDITION_18_006: [** `Condition_Wait` shall return `COND_INVALID_ARG` if `lock` is `NULL` and `timeout_milliseconds` is not `0` **]**
87
88 **SRS_CONDITION_18_010: [** `Condition_Wait` shall return `COND_OK` if the condition is triggered and `timeout_milliseconds` is `0` **]**
89
90 **SRS_CONDITION_18_011: [** `Condition_Wait` shall return `COND_TIMEOUT` if the condition is NOT triggered and `timeout_milliseconds` is not `0` **]**
91
92 **SRS_CONDITION_18_012: [** `Condition_Wait` shall return `COND_OK` if the condition is triggered and `timeout_milliseconds` is not `0` **]**
93
94 **SRS_CONDITION_18_013: [** `Condition_Wait` shall accept relative timeouts **]**
95
96
97 ### Condition_Deinit
98 ```C
99 extern void Condition_Deinit(COND_HANDLE handle);
100 ```
101
102 **SRS_CONDITION_18_007: [** `Condition_Deinit` will not fail if `handle` is `NULL` **]**
103
104 **SRS_CONDITION_18_009: [** `Condition_Deinit` will deallocate `handle` if it is not `NULL` **]**