The "dm" Package

These routines are meant to provide a generic and simple to use descriptor management facility (ie. event processing on pipes, connections and terminals). NOTE: THIS PACKAGE IS WORK IN PROGRESS. THE INTERFACE MAY CHANGE IN THE NEXT RELEASE, POSSIBLY WITHOUT NOTICE.

Library: karma
Link With: -lkarma

Functions

dm_register_managers	Register the managers.
dm_manage	Manage a file descriptor for events.
dm_unmanage	Terminate the management of a file descriptor for activity.
dm_native_setup	Setup descriptor management using native implementation.
dm_native_poll	Poll all managed descriptors for any activity.

Prototype Functions

dm_PROTO_input_func	Input event callback.
dm_PROTO_close_func	Close event callback.
dm_PROTO_output_func	Output event callback.
dm_PROTO_exception_func	Exception event callback.

Functions

EXPERIMENTAL FUNCTION: subject to change without notice

void dm_register_managers ( KManagedDescriptor (*manage_func) (int fd, void *info, flag (*input_func) (), void (*close_func) (), flag (*output_func) (), flag (*exception_func) (), flag auto_close), void *(*unmanage_func) (int fd, KManagedDescriptor md) )

Parameters:

manage_func : The function which will be called to manage descriptors. The interface to this function is the same as dm_manage.
unmanage_func : The function which will be called to manage descriptors. The interface to this function is the same as dm_unmanage.

Returns: Nothing. On failure the process aborts.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

KManagedDescriptor dm_manage (int fd, void *info, flag (*input_func) (), void (*close_func) (), flag (*output_func) (), flag (*exception_func) (), flag auto_close)

This routine will manage a file descriptor for activity by registering callback routines. Only one set of callbacks may be registered per file descriptor.

Parameters:

fd : The file descriptor to manage.
info : The initial value of the arbitrary pointer associated with the managed descriptor. This pointer may be modified by the callback routines.
input_func : The routine which is called when new input occurrs on the descriptor. If this is NULL, no callback routine is installed. The prototype function is dm_PROTO_input_func.
close_func : The routine which is called when the descriptor closes. If this is NULL, no callback routine is installed. The prototype function is dm_PROTO_close_func.
output_func : The routine which is called when the descriptor becomes ready for output. If this is NULL, no callback routine is installed. The prototype function is dm_PROTO_output_func.
exception_func : The routine which is called when exceptions occurr on the descriptor. If this is NULL, no callback routine is installed. The prototype function is dm_PROTO_exception_func.
auto_close : If TRUE, the descriptor is automatically closed upon a closure event.

Returns: A KManagedDescriptor object on success, else NULL.
Multithreading Level: Unsafe

void * dm_unmanage (int fd, KManagedDescriptor md)

Terminate the management of a file descriptor for activity.

Parameters:

fd : The descriptor to unmanage. This must always be valid.
md : The entry to unmanage. If this is NULL then fd is used.

Returns: The arbitrary pointer passed when the descriptor was managed.
Multithreading Level: Unsafe
Note:

The routine will NOT close the descriptor (nor does it assume the descriptor is open).

void dm_native_setup ()

Setup descriptor management using native implementation.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe

void dm_native_poll (long timeout_ms)

Poll all managed descriptors for any activity.

Parameters:

timeout_ms : The time (in milliseconds) to poll. If this is less than 0 the routine will poll forever (until some activity occurs or a signal is caught).

Returns: Nothing.
Multithreading Level: Unsafe

Prototype Functions

flag dm_PROTO_input_func (int fd, void **info)

This routine is called when new input occurs on a descriptor.

Parameters:

fd : The file descriptor.
info : A pointer to the arbitrary information pointer. The pointer written here will persist until the descriptor is unmanaged (or a subsequent callback routine changes it).

Returns: TRUE if the descriptor is to remain managed and open, else it returns FALSE (indicating that the descriptor is to be unmanaged and closed). This routine MUST NOT unmanage or close the descriptor.
Multithreading Level: Unsafe
Note:

The close_func will be called if this routine returns FALSE.

void dm_PROTO_close_func (int fd, void *info)

This routine is called when a descriptor closes.

Parameters:

fd : The file descriptor. The descriptor MUST be capable of detecting closure if this routine is supplied (i.e. this routine cannot be supplied for docks).
info : The arbitrary pointer for the managed descriptor.

Returns: Nothing.
Multithreading Level: Unsafe
Note:

This routine MUST NOT unmanage the descriptor. The descriptor will be automatically unmanaged and deleted upon closure (even if no close_func is specified).
Any unread data in the descriptor will be lost upon closure. The call to this function is the last chance to read this data.

flag dm_PROTO_output_func (int fd, void **info)

This routine is called when a descriptor becomes ready for writing.

Parameters:

fd : The file descriptor.
info : A pointer to the arbitrary information pointer. The pointer written here will persist until the descriptor is unmanaged (or a subsequent callback routine changes it).

The close_func will be called if this routine returns FALSE.

flag dm_PROTO_exception_func (int fd, void **info)

This routine is called when an exception occurrs on a descriptor.

Parameters:

fd : The file descriptor.
info : A pointer to the arbitrary information pointer. The pointer written here will persist until the descriptor is unmanaged (or a subsequent callback routine changes it).

The close_func will be called if this routine returns FALSE.

Back to Karma Home Page

Contact: Richard Gooch
Web Development: Ariel Internet Services