# The "e" Package

These routines are meant to provide a flexible, portable means to generate periodic events. NOTE: THIS PACKAGE IS WORK IN PROGRESS. THE INTERFACE MAY CHANGE IN THE NEXT RELEASE, POSSIBLY WITHOUT NOTICE.

Library: karma
Link With: -lkarma

#### Functions

e_test_supported | Test if application supports scheduled events.
e_create_list | Create a periodic event management list.
e_dispatch_events | Dispatch events for a list.
e_register_func | Register a function to be called periodically.
e_unregister_func | Unregister an event function.
e_unix_init | Initialise periodic event management support under Unix.
e_unix_dispatch_events | Dispatch events for Unix.

#### Prototype Functions

e_PROTO_event_func | Event callback.

#### Tables

e_DISPATCH_LEVELS | List of dispatch levels

## Functions

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag e_test_supported ()

This routine will determine if scheduled events have been supported by the application.

Parameters:

This function takes no parameters

Returns: TRUE if scheduled events are supported, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

KPeriodicEventList e_create_list (unsigned long interval_us, unsigned long interval_s, void *list_info)

Create a periodic event management list.

Parameters:

- interval_us : The microsecond component time between timeouts on this list.
- interval_s : The second component time between timeouts on this list.
- list_info : An arbitrary pointer passed to event functions on this list.

Returns: A KPeriodicEventList on success, else the process aborts.
Multithreading Level: Unsafe
Note:

- The specified interval may be rounded up to the system timer resolution (10ms on many systems).

#### EXPERIMENTAL FUNCTION: subject to change without notice

void e_dispatch_events (KPeriodicEventList list, unsigned int dispatch_level, flag timeout)

Dispatch events for a list.

Parameters:

- list : The event list.
- dispatch_level : The level of events that may dispatched. Event functions at the same level or higher are dispatched. See e_DISPATCH_LEVELS for a list of legal values.
- timeout : If TRUE, the perdiodic timer timed out.

Returns: Nothing.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

KPeriodicEventFunc e_register_func (KPeriodicEventList list, flag (*func) (), void *info, unsigned long interval, unsigned int dispatch_level)

Register a function to be called periodically.

Parameters:

- list : The event list to manage the function.
- func : The function to be called upon the specified timout. The prototype function is e_PROTO_event_func.
- info : An arbitrary pointer passed to func.
- interval : The interval between successive calls to func. This is measured in units of the list timeout.
- dispatch_level : The preferred method of dispatch for the function. See e_DISPATCH_LEVELS for a list of legal values. Not all implementations may support the higher levels, so events may dispatched at a lower level than desired.

Returns: A KPeriodicEventFunc on success, else the process aborts.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

void e_unregister_func (KPeriodicEventFunc func)

Unregister an event function.

Parameters:

- func : The callback function.

Returns: Nothing.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

void e_unix_init ()

Initialise periodic event management support under Unix.

Parameters:

This function takes no parameters

Returns: Nothing on success, else the process aborts.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

void e_unix_dispatch_events (unsigned int dispatch_level)

Dispatch events for Unix.

Parameters:

- dispatch_level : The level of events that may dispatched. Event functions at the same level or higher are dispatched.

Returns: Nothing.
Multithreading Level: Unsafe

## Prototype Functions

flag e_PROTO_event_func (KPeriodicEventFunc func, void *f_info, void *l_info)

This routine is called when a periodic event occurs.

Parameters:

- func : The KPeriodicEventFunc object.
- f_info : A pointer to arbitrary information for the function.
- l_info : A pointer to arbitrary information for the event list.

Returns: TRUE if the event function should be called again, else FALSE.
Multithreading Level: Unsafe

## Tables

e_DISPATCH_LEVELS List of dispatch levels

Dispatch level | Meaning
DISPATCH_SYNCHRONOUS | Dispatch synchronously with the application main thread
DISPATCH_ASYNCHRONOUS | Dispatch asynchronously (like a Unix signal handler). Use with caution, as race conditions may result

Back to Karma Home Page