Condition Requirements ================ ## Overview Condition is a module which allows thread synchronization to occur in a cross-platform manner. It provides a mechanism for signalling events between threads and for waiting on events in a platform-independent manner. ## References [lock](lock_requirements.md) ## Exposed API ```C /** * @brief This API creates and returns a valid condition handle. * * @return A valid @c COND_HANDLE when successful or @c NULL otherwise. */ extern COND_HANDLE Condition_Init(void); /** * @brief unblock all currently working condition. * * @param handle A valid handle to the lock. * * @return Returns @c COND_OK when the condition object has been * destroyed and @c COND_ERROR when an error occurs * and @c COND_TIMEOUT when the handle times out. */ extern COND_RESULT Condition_Post(COND_HANDLE handle); /** * @brief block on the condition handle unti the thread is signalled * or until the timeout_milliseconds is reached. * * @param handle A valid handle to the lock. * * @return Returns @c COND_OK when the condition object has been * destroyed and @c COND_ERROR when an error occurs * and @c COND_TIMEOUT when the handle times out. */ extern COND_RESULT Condition_Wait(COND_HANDLE handle, LOCK_HANDLE lock, int timeout_milliseconds); /** * @brief The condition instance is deinitialized. * * @param handle A valid handle to the condition. * * @return Returns @c COND_OK when the condition object has been * destroyed and @c COND_ERROR when an error occurs. */ extern void Condition_Deinit(COND_HANDLE handle); ``` ### Condition_Init ```C extern COND_HANDLE Condition_Init(void); ``` **SRS_CONDITION_18_002: [** `Condition_Init` shall create and return a `CONDITION_HANDLE` **]** **SRS_CONDITION_18_008: [** `Condition_Init` shall return `NULL` if it fails to allocate the `CONDITION_HANDLE` **]** ### Condition_Post ```C extern COND_RESULT Condition_Post(COND_HANDLE handle); ``` **SRS_CONDITION_18_003: [** `Condition_Post` shall return `COND_OK` if it succcessfully posts the condition **]** **SRS_CONDITION_18_001: [** `Condition_Post` shall return `COND_INVALID_ARG` if `handle` is `NULL` **]** ### Condition_Wait ```C extern COND_RESULT Condition_Wait(COND_HANDLE handle, LOCK_HANDLE lock, int timeout_milliseconds); ``` **SRS_CONDITION_18_004: [** `Condition_Wait` shall return `COND_INVALID_ARG` if `handle` is `NULL` **]** **SRS_CONDITION_18_005: [** `Condition_Wait` shall return `COND_INVALID_ARG` if `lock` is `NULL` and `timeout_milliseconds` is `0` **]** **SRS_CONDITION_18_006: [** `Condition_Wait` shall return `COND_INVALID_ARG` if `lock` is `NULL` and `timeout_milliseconds` is not `0` **]** **SRS_CONDITION_18_010: [** `Condition_Wait` shall return `COND_OK` if the condition is triggered and `timeout_milliseconds` is `0` **]** **SRS_CONDITION_18_011: [** `Condition_Wait` shall return `COND_TIMEOUT` if the condition is NOT triggered and `timeout_milliseconds` is not `0` **]** **SRS_CONDITION_18_012: [** `Condition_Wait` shall return `COND_OK` if the condition is triggered and `timeout_milliseconds` is not `0` **]** **SRS_CONDITION_18_013: [** `Condition_Wait` shall accept relative timeouts **]** ### Condition_Deinit ```C extern void Condition_Deinit(COND_HANDLE handle); ``` **SRS_CONDITION_18_007: [** `Condition_Deinit` will not fail if `handle` is `NULL` **]** **SRS_CONDITION_18_009: [** `Condition_Deinit` will deallocate `handle` if it is not `NULL` **]**