TABLE OF CONTENTS

1. Component Library/Timer
2. Component Library: Time Stamp/cl_get_time_stamp
3. Component Library: Time Stamp/cl_get_time_stamp_sec
4. Component Library: Timer/cl_pfn_timer_callback_t
5. Component Library: Timer/cl_timer_construct
6. Component Library: Timer/cl_timer_destroy
7. Component Library: Timer/cl_timer_init
8. Component Library: Timer/cl_timer_start
9. Component Library: Timer/cl_timer_stop
10. Component Library: Timer/cl_timer_trim

Component Library/Timer

    Timer

    The Timer provides the ability to schedule a function to be invoked at 
    a given time in the future.

    The timer callback function must not perform any blocking operations.

    The timer functions operate on a cl_timer_t structure which should be 
    treated as opaque and should be manipulated only through the provided 
    functions.

    Structures:
        cl_timer_t

    Callbacks:
        cl_pfn_timer_callback_t

    Initialization:
        cl_timer_construct, cl_timer_init, cl_timer_destroy

    Manipulation:
        cl_timer_start, cl_timer_stop

Component Library: Time Stamp/cl_get_time_stamp

    cl_get_time_stamp

    The cl_get_time_stamp function returns the current time stamp in 
    microseconds since the system was booted.

uint64_t
cl_get_time_stamp( void );

    Time elapsed, in microseconds, since the system was booted.

    Timer, cl_get_time_stamp_sec 

Component Library: Time Stamp/cl_get_time_stamp_sec

    cl_get_time_stamp_sec

    The cl_get_time_stamp_sec function returns the current time stamp in 
    seconds since the system was booted.

uint32_t
cl_get_time_stamp_sec( void );

    Time elapsed, in seconds, since the system was booted.

    Timer, cl_get_time_stamp

Component Library: Timer/cl_pfn_timer_callback_t

    cl_pfn_timer_callback_t

    The cl_pfn_timer_callback_t function type defines the prototype for 
    functions used to notify users of a timer expiration.

typedef void 
(*cl_pfn_timer_callback_t)( 
    IN void*    context );

    context 
        [in] Value specified in a previous call to cl_timer_init.

    This function does not return a value.

    This function type is provided as function prototype reference for the 
    function provided by users as a parameter to the cl_timer_init function.

    Timer, cl_timer_init

Component Library: Timer/cl_timer_construct

    cl_timer_construct

    The cl_timer_construct function initializes the state of a timer.

void
cl_timer_construct(
    IN  cl_timer_t* const   p_timer );

    p_timer 
        [in] Pointer to a cl_timer_t structure whose state to initialize.

    This function does not return a value.

    Allows calling cl_timer_destroy without first calling cl_timer_init.

    Calling cl_timer_construct is a prerequisite to calling any other
    timer function except cl_timer_init.

    Timer, cl_timer_init, cl_timer_destroy

Component Library: Timer/cl_timer_destroy

    cl_timer_destroy

    The cl_timer_destroy function performs any necessary cleanup of a timer.

void
cl_timer_destroy( 
    IN  cl_timer_t* const   p_timer );

    p_timer 
        [in] Pointer to a cl_timer_t structure to destroy.

    This function does not return a value.

    cl_timer_destroy cancels any pending callbacks.

    This function should only be called after a call to cl_timer_construct 
    or cl_timer_init.

    Timer, cl_timer_construct, cl_timer_init 

Component Library: Timer/cl_timer_init

    cl_timer_init

    The cl_timer_init function initializes a timer for use.

cl_status_t
cl_timer_init( 
    IN  cl_timer_t* const       p_timer, 
    IN  cl_pfn_timer_callback_t pfn_callback, 
    IN  const void* const       context );

    p_timer 
        [in] Pointer to a cl_timer_t structure to initialize.

    pfn_callback 
        [in] Address of a callback function to be invoked when a timer expires.
        See the cl_pfn_timer_callback_t function type definition for details 
        about the callback function. 

    context 
        [in] Value to pass to the callback function.

    CL_SUCCESS if the timer was successfully initialized. 

    CL_ERROR otherwise.

    Allows calling cl_timer_start and cl_timer_stop.

    Timer, cl_timer_construct, cl_timer_destroy, cl_timer_start, 
    cl_timer_stop, cl_pfn_timer_callback_t 

Component Library: Timer/cl_timer_start

    cl_timer_start

    The cl_timer_start function sets a timer to expire after a given interval.

cl_status_t
cl_timer_start( 
    IN  cl_timer_t* const   p_timer, 
    IN  const uint32_t      time_ms );

    p_timer 
        [in] Pointer to a cl_timer_t structure to schedule.

    time_ms 
        [in] Time, in milliseconds, before the timer should expire.

    CL_SUCCESS if the timer was successfully scheduled.

    CL_ERROR otherwise.

    cl_timer_start implicitly stops the timer before being scheduled.

    The interval specified by the time_ms parameter is a minimum interval.  
    The timer is guaranteed to expire no sooner than the desired interval, but
    may take longer to expire.

    Timer, cl_timer_stop, cl_timer_trim

Component Library: Timer/cl_timer_stop

    cl_timer_stop

    The cl_timer_stop function stops a pending timer from expiring.

void
cl_timer_stop( 
    IN  cl_timer_t* const   p_timer );

    p_timer 
        [in] Pointer to a cl_timer_t structure.

    This function does not return a value.

    Timer, cl_timer_start, cl_timer_trim

Component Library: Timer/cl_timer_trim

    cl_timer_trim

    The cl_timer_trim function pulls in the absolute expiration 
    time of a timer if the current expiration time exceeds the specified
    interval.

    sets a timer to expire after a given 
    interval if that interval is less than the current timer expiration.

cl_status_t
cl_timer_trim(  
    IN  cl_timer_t* const   p_timer, 
    IN  const uint32_t      time_ms );

    p_timer 
        [in] Pointer to a cl_timer_t structure to schedule.

    time_ms 
        [in] Maximum time, in milliseconds, before the timer should expire.

    CL_SUCCESS if the timer was successfully scheduled.

    CL_ERROR otherwise.

    cl_timer_trim has no effect if the time interval is greater than the
    remaining time when the timer is set.

    If the new interval time is less than the remaining time, cl_timer_trim
    implicitly stops the timer before reseting it.

    If the timer is reset, it is guaranteed to expire no sooner than the 
    new interval, but may take longer to expire.

    Timer, cl_timer_start, cl_timer_stop