| 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` **]** |