TIMER(3X)

NAME
timer_create, timer_destroy, timer_start, timer_stop, timer_block, timer_unblock, timer_expirations, timer_block_type, timer_unblock_type - timer management functions

SYNOPSIS

#include "timer.h"

enum timer_types { TIMER_REAL, TIMER_VIRTUAL, TIMER_PROF } ;
enum timer_timetypes { TIMER_ABSOLUTE, TIMER_RELATIVE } ;

extern int timer_errno ;

timer_h timer_create( type, flags, errnop )
enum timer_types type ;
int flags ;
int *errnop ;

void timer_destroy( handle )
timer_h handle ;

int timer_start( handle, itvp, time_type, action )
timer_h handle ;
struct itimerval *itvp ;
enum timer_timetypes time_type ;
struct timer_action *action ;

void timer_stop( handle )
timer_h handle ;

void timer_block( handle )
timer_h handle ;

void timer_unblock( handle )
timer_h handle ;

unsigned timer_expirations( handle )
timer_h handle ;

void timer_block_type( type )
enum timer_types type ;

void timer_unblock_type( type )
enum timer_types type ;

DESCRIPTION

This library provides support for multiple timers of various types by multiplexing the timers provided by the operating system. An action is associated with each timer. The action can either be a function that will be invoked when the timer expires or it can be an integer variable that will either be set to TRUE when the timer expires or it will be increased for every expiration of the timer (it is up to the user to clear the variable after inspecting its value). If a function is used, then it is possible that while that function is running, more timers may expire and their functions be called (i.e. timer interrupts are not blocked while the function is running). The timer-action association can change through the lifetime of the timer. The timer types supported by this library depend on the operating system.

timer_create() creates a timer and returns a handle to it. When the timer is created, it is inactive. Possible values for type are:

TIMER_REAL
    timers of this type are wall-clock timers

TIMER_VIRTUAL
    timers of this type are running only when the process is running

TIMER_PROF
    timers of this type are running only when the process is running or the system is doing work on behalf of the process.

Possible values for flags are formed by ORing any of the following constants:

TIMER_RETURN_ERROR
    if an error occurs while handling this timer an error indication will be returned (the default is program termination)

You can use the constant TIMER_NOFLAGS to specify no flags at all. The argument errnop is a pointer to a variable where error values will be placed (the default, in case errnop is NULL is timer_errno).

timer_destroy() destroys the timer specified by handle. If the timer is active, it is deactivated first.

timer_start() activates the timer specified by handle. The expiration time is determined by itvp and time_type. time_type can be either TIMER_ABSOLUTE or TIMER_RELATIVE. Timers of the former type expire at the time specified by itvp->it_value (if that time is before the current time then the timer expires immediately) while the expiration time of timers of the latter type expire at current time + itvp->it_value. itvp->it_interval is the interval between subsequent expirations of the timer after the original expiration. The action argument determines the action to be taken when the timer expires.

struct timer_action is defined as follows:

    struct timer_action
    {

        int ta_flags ;

        void
            (*ta_func)() ;

        void
            *ta_arg ;

        jmp_buf
            ta_env ;
    } ;

The type of action taken when a timer expires depends on ta_func and ta_arg.

    Case 1: ta_func != NULL
        The function will be invoked with 2 arguments: the handle of the expired timer and ta_arg. Such functions should not use longjmp.

    Case 2: ta_func == NULL && ta_arg != NULL
        ta_arg is assumed to be a pointer to an integer variable. This variable will either be set to TRUE or its value will be increased.

    Case 3: ta_func == NULL && ta_arg == NULL
        nothing happens.

ta_flags is formed by ORing any of the following constants:

TIMER_INC_VAR
    When the action associated with the timer is an integer variable then the variable will be increased by the number of timer expirations (the default is for the variable to be set to 1).

TIMER_BLOCK_ALL
    When the action associated with the timer is a function, all timer interrupts will be blocked while the function is running.

TIMER_BLOCK_SAME
    When the action associated with the timer is a function, all timers of the same type will be blocked while the function is running.

TIMER_LONGJMP
    A longjmp(3) will be performed using ta_env after the action associated with the timer is performed.

You can use the constant TIMER_NOFLAGS to specify no flags at all.

timer_stop() stops the specified timer. The timer becomes inactive and it cannot be restarted.

timer_block() blocks the specified timer. The timer is still active and may expire but its action will not be executed until the timer is unblocked.

timer_unblock() unblocks the specified timer. If the timer is past its expiration time, the associated action will be executed immediately.

timer_expirations() should be used by the user-specified function to find out the number of times the timer expired until the function was called. Multiple expirations are possible for a timer that expires periodically.

timer_block_type() blocks all timers of the specified type. This also includes any timers started after this function is invoked.

timer_unblock_type() unblocks all timers of the specified type.

NOTES

Any of the timer operations can be used on any timer handle at any time. Specifically, the operations can be used from within the functions invoked when the timers expire.

The function associated with a timer is not invoked for each expiration of that timer. It is possible for a timer to expire multiple times while its function is running (because timers can be scheduled to expire periodically) or while other timer functions are running. The timer function can find out how many times its timer has expired by using the timer_expirations() operation.

It is guaranteed that the function associated with a specific timer will not be called recursively if that timer expires multiple times.

The order of execution of timer-associated functions for timers that expire at the same time is undefined.

Even if a function returns a jmp_buf pointer, it is not guaranteed that the pointer will be used. The reason is that more than one function can expire at the same time and return a jmp_buf pointer. Since there can be only one control flow, only one of those jmp_buf's can be used and the choice between them is implementation-dependent.

RETURN VALUES

Values for timer_errno will be stored in the user-specified variable if one was provided.

timer_create() returns a timer handle if successful or NULL if it fails.

timer_start() returns TIMER_OK if successful or TIMER_ERR if it fails.

timer_expirations() returns a positive (non-zero) number when invoked from a timer-associated function; otherwise its return value is undefined.

ERRORS
The following is a list of error codes which will be placed in timer_errno or the user-specified variable when a timer operation fails:

    TIMER_ENOMEM
        A memory allocation request failed.

    TIMER_EBADTYPE
        An unknown timer type was specified.

    TIMER_ESIGPROBLEM
        A signal handler could not be installed.

    TIMER_EBADSTATE
        The timer state does not allow this operation (for example, the timer is running and the operation attempted was timer_start()).

    TIMER_EBADTIME
        The time value specified was negative.

    TIMER_ENOTAVAILABLE
        The requested timer type is not available.

    TIMER_ECANTINSERT
        The insertion of this timer in the queue of timers failed.

    TIMER_SIGPROBLEM
        There was an error while trying to install a signal handler.

SEE ALSO
setitimer(2), setjmp(3), longjmp(3)