The API is defined in the header file sysroot-*-kos/include/kos/event.h from the KasperskyOS SDK. The KasperskyOS SDK also provides the header file sysroot-*-kos/include/kos/sync_api.h, which lets you transitively include the header file event.h and the header files for using other synchronization primitives into the application source code.
The API facilitates using events to synchronize threads. An event is a synchronization primitive that is used to notify one or more threads about the fulfillment of a condition required by these threads. The notified thread waits for the event to switch from a non-signaling state to a signaling state, and the notifying thread changes the state of this event.
Information about API functions is provided in the table below.
Using the API
The standard scenario for API usage includes the following steps:
An event is initialized via the KosEventInit() function call.
The event is used by threads:
The notified threads wait for the event to switch from non-signaling state to signaling state via the KosEventWait() or KosEventWaitTimeout() function call.
The notifying threads change the state of the event via the KosEventSet() and KosEventReset() function calls.
Information about API functions
event.h functions
Function
Information about the function
KosEventInit()
Purpose
Initializes an event.
The event is in a non-signaling state after it is initialized.
Parameters
[out] event – pointer to the event. The event type is defined in the sysroot-*-kos/include/kos/sync_types.h header file from the KasperskyOS SDK.
Returned values
N/A
KosEventSet()
Purpose
Sets the event state to signaling.
Parameters
[out] event – pointer to the event. The event type is defined in the sysroot-*-kos/include/kos/sync_types.h header file from the KasperskyOS SDK.
Returned values
N/A
KosEventReset()
Purpose
Sets the event state to non-signaling.
Parameters
[out] event – pointer to the event. The event type is defined in the sysroot-*-kos/include/kos/sync_types.h header file from the KasperskyOS SDK.
Returned values
N/A
KosEventWait()
Purpose
Waits for the event to change its state from non-signaling to signaling.
Parameters
[in,out] event – pointer to the event. The event type is defined in the sysroot-*-kos/include/kos/sync_types.h header file from the KasperskyOS SDK.
[in] reset – boolean value that defines whether the event state should be changed set to non-signaling after the time-out has elapsed (rtl_true – yes, rtl_false – no). The parameter type is defined in the sysroot-*-kos/include/rtl/stdbool.h header file from the KasperskyOS SDK.
Returned values
N/A
KosEventWaitTimeout()
Purpose
Waits on the event to change its state from non-signaling to signaling for a period that does not exceed the specified time.
Parameters
[in,out] event – pointer to the event. The event type is defined in the sysroot-*-kos/include/kos/sync_types.h header file from the KasperskyOS SDK.
[in] reset – Boolean value that specifies whether the event state should be set to non-signaling if the wait was terminated due to a transition to the signaling state(rtl_true means yes, rtl_false means no). The parameter type is defined in the sysroot-*-kos/include/rtl/stdbool.h header file from the KasperskyOS SDK.
[in] mdelay – timeout (in milliseconds) or INFINITE_TIMEOUT to set an unlimited timeout. The constant INFINITE_TIMEOUT is defined in the header file sysroot-*-kos/include/rtl/rtc.h from the KasperskyOS SDK.
Returned values
If successful, the function returns rcOk, otherwise it returns an error code.
Returns rcTimeout if the timeout has elapsed.
Additional information
Non-blocking call if the mdelay parameter is set to 0.