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.
dm_native_clear_activity_counter	Clear the idle counter.
dm_native_get_activity_count	Get the current activity count.
dm_native_clear_idle_timer	Clear the idle timer.
dm_native_get_idle_time	Get the idle time in microseconds.
dm_native_wait_input	Block waiting for input on a file descriptor.

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.
dm_PROTO_inode_write_func	Inode write event callback.

Tables

dm_EVENTS

List of event types

Functions

EXPERIMENTAL FUNCTION: subject to change without notice

void dm_register_managers ( KManagedDescriptor (*manage_func) (int fd, void *info, flag auto_close,va_list argp), 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 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.
auto_close : If TRUE, the descriptor is automatically closed upon a closure event.
... : The optional list of parameter event-key event-function pairs must follow. This list must be terminated with the value KARMA_FD_EVENT_END. See dm_EVENTS for the list of attributes.

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).

EXPERIMENTAL FUNCTION: subject to change without notice

void dm_native_setup ()

Setup descriptor management using native implementation.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

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

EXPERIMENTAL FUNCTION: subject to change without notice

void dm_native_clear_activity_counter ()

Clear the idle counter.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

unsigned long dm_native_get_activity_count ()

This function will get the current activity count. This is the count of the number of times the OS has detected activity on one or more file descriptors.

Parameters:

Returns: The activity count.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void dm_native_clear_idle_timer ()

Clear the idle timer.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

unsigned long dm_native_get_idle_time ()

Get the idle time in microseconds.

Parameters:

Returns: The idle time.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag dm_native_wait_input (int fd, int timeout)

Block waiting for input on a file descriptor.

Parameters:

fd : The file descriptor.
timeout : The time to wait for (in milliseconds). If this is less than 0 the function waits indefinately.

Returns: TRUE on activity, else FALSE on error/timeout.
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 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).

The close_func will be called if this routine returns FALSE.

flag dm_PROTO_inode_write_func (int fd, void **info)

This routine is called when an inode is written to.

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.

Tables

dm_EVENTS List of event types

Name Function Prototype Meaning

KARMA_FD_EVENT_END End of varargs list
KARMA_FD_EVENT_INPUT dm_PROTO_input_func
KARMA_FD_EVENT_OUTPUT dm_PROTO_output_func
KARMA_FD_EVENT_EXCEPTION dm_PROTO_exception_func
KARMA_FD_EVENT_CLOSE dm_PROTO_close_func
KARMA_FD_EVENT_INODE_WRITE dm_PROTO_inode_write_func

Back to Karma Home Page

Contact: Richard Gooch
Web Development: Ariel Internet Services

Name	Function Prototype	Meaning

KARMA_FD_EVENT_END		End of varargs list
KARMA_FD_EVENT_INPUT	dm_PROTO_input_func
KARMA_FD_EVENT_OUTPUT	dm_PROTO_output_func
KARMA_FD_EVENT_EXCEPTION	dm_PROTO_exception_func
KARMA_FD_EVENT_CLOSE	dm_PROTO_close_func
KARMA_FD_EVENT_INODE_WRITE	dm_PROTO_inode_write_func