TABLE OF CONTENTS

1. Component Library/Event
2. Component Library: Event/cl_event_construct
3. Component Library: Event/cl_event_destroy
4. Component Library: Event/cl_event_init
5. Component Library: Event/cl_event_reset
6. Component Library: Event/cl_event_signal
7. Component Library: Event/cl_event_wait_on

Component Library/Event

    Event

    The Event provides the ability to suspend and wakeup a thread.

    The event functions operates on a cl_event_t structure which should be 
    treated as opaque and should be manipulated only through the provided 
    functions.

    Structures:
        cl_event_t

    Initialization/Destruction:
        cl_event_construct, cl_event_init, cl_event_destroy

    Manipulation:
        cl_event_signal, cl_event_reset, cl_event_wait_on

Component Library: Event/cl_event_construct

    cl_event_construct

    The cl_event_construct function constructs an event.

void
cl_event_construct( 
    IN  cl_event_t* const   p_event );

    p_event 
        [in] Pointer to an cl_event_t structure to construct.

    This function does not return a value.

    Allows calling cl_event_destroy without first calling cl_event_init.

    Calling cl_event_construct is a prerequisite to calling any other event
    function except cl_event_init.

    Event, cl_event_init, cl_event_destroy

Component Library: Event/cl_event_destroy

    cl_event_destroy

    The cl_event_destroy function performs any necessary cleanup of an event.

void
cl_event_destroy(
    IN  cl_event_t* const   p_event );

    p_event 
        [in] Pointer to an cl_event_t structure to destroy.

    This function does not return a value.

    This function should only be called after a call to cl_event_construct 
    or cl_event_init.

    Event, cl_event_construct, cl_event_init

Component Library: Event/cl_event_init

    cl_event_init

    The cl_event_init function initializes an event for use.

cl_status_t
cl_event_init( 
    IN  cl_event_t* const   p_event,
    IN  const boolean_t     manual_reset );

    p_event 
        [in] Pointer to an cl_event_t structure to initialize.

    manual_reset
        [in] If FALSE, indicates that the event resets itself after releasing 
        a single waiter.  If TRUE, the event remains in the signalled state 
        until explicitly reset by a call to cl_event_reset.

    CL_SUCCESS if event initialization succeeded.

    CL_ERROR otherwise.

    Allows calling event manipulation functions, such as cl_event_signal,
    cl_event_reset, and cl_event_wait_on.

    The event is initially in a reset state.

    Event, cl_event_construct, cl_event_destroy, cl_event_signal,
    cl_event_reset, cl_event_wait_on

Component Library: Event/cl_event_reset

    cl_event_reset

    The cl_event_reset function sets an event to the non-signalled state.

cl_status_t
cl_event_reset( 
    IN  cl_event_t* const   p_event );

    p_event 
        [in] Pointer to an cl_event_t structure to reset.

    CL_SUCCESS if the event was successfully reset.

    CL_ERROR otherwise.

    Event, cl_event_signal, cl_event_wait_on

Component Library: Event/cl_event_signal

    cl_event_signal

    The cl_event_signal function sets an event to the signalled state and
    releases at most one waiting thread.

cl_status_t
cl_event_signal(
    IN  cl_event_t* const   p_event );

    p_event 
        [in] Pointer to an cl_event_t structure to set.

    CL_SUCCESS if the event was successfully signalled.

    CL_ERROR otherwise.

    For auto-reset events, the event is reset automatically once a wait 
    operation is satisfied. 

    Triggering the event multiple times does not guarantee that the same 
    number of wait operations are satisfied. This is because events are 
    either in a signalled on non-signalled state, and triggering an event 
    that is already in the signalled state has no effect.

    Event, cl_event_reset, cl_event_wait_on 

Component Library: Event/cl_event_wait_on

    cl_event_wait_on

    The cl_event_wait_on function waits for the specified event to be 
    triggered for a minimum amount of time.

cl_status_t
cl_event_wait_on( 
    IN  cl_event_t* const   p_event,
    IN  const uint32_t      wait_us,
    IN  const boolean_t     interruptible );

    p_event 
        [in] Pointer to an cl_event_t structure on which to wait.

    wait_us 
        [in] Number of microseconds to wait.

    interruptible
        [in] Indicates whether the wait operation can be interrupted
        by external signals.

    CL_SUCCESS if the wait operation succeeded in response to the event 
    being set.

    CL_TIMEOUT if the specified time period elapses.

    CL_NOT_DONE if the wait was interrupted by an external signal.

    CL_ERROR if the wait operation failed.

    If wait_us is set to EVENT_NO_TIMEOUT, the function will wait until the 
    event is triggered and never timeout.

    If the timeout value is zero, this function simply tests the state of 
    the event.

    If the event is already on the signalled state at the time of the call
    to cl_event_wait_on, the call completes immediately with CL_SUCCESS.

    Event, cl_event_signal, cl_event_reset