| Updated: April 19, 2023 |
Set a sigevent to deliver when a new mm-renderer event becomes available
#include <mm/renderer/events.h>
int mmr_event_arm(mmr_context_t *ctxt,
struct sigevent const *sev)
Set a sigevent to deliver when a new mm-renderer event becomes available. This function is helpful if your program already has an event-processing loop that uses signals or pulses as notifications and you simply want to add code that processes mm-renderer events. To do this, you must call mmr_event_arm() to request notification of the next such event. Then, in the new event-handling code, you must call mmr_event_get() to retrieve the event information.
This function is thread-safe only when using different context handles in each call. It's neither interrupt handler-safe nor signal-handler safe.
Because mmr_event_arm() enables notification of only one event, you must call this function repeatedly if you want to receive a sigevent for each mm-renderer event. The function is non-blocking because it enables notification of an event but doesn't wait for it to occur. If there's already an event waiting, the function doesn't arm a sigevent but immediately returns a value greater than zero.
You can provide a registered or an unregistered sigevent. In the registered case, mmr_event_arm() doesn't modify the sigevent structure. If the calling thread wants to be the recipient of the event, it must specify -1 as the connection ID (coid) in its earlier call to a SIGEV_*_INIT() macro.
In the unregistered case, mmr_event_arm() internally registers the event, modifying the sigevent structure, and uses this internal event. If you keep calling the function with an identical unregistered event, the function keeps using its internal event. But if you call it with a different event (registered or not), or you call mmr_event_wait(), the internal event is unregistered before the new one is registered.
To avoid this overhead at every mmr_event_arm() call, you should ensure that the sigevents you provide are bitwise identical. Don't use automatic stack variables initialized with a SIGEV_*_INIT() macro (which may leave parts of the structure with uninitialized and hence, random memory). Instead, use the same static or allocated variable every time, without modifying its contents between calls.
For information about the signal event structure, see the sigevent entry in the C Library Reference.
A positive number if there's already an event waiting, 0 on success, or -1 on failure (check errno).