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:

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)

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:

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

Contact: Richard Gooch
Web Development: Ariel Internet Services

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