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

Register the managers.

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:

This function takes no 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:

This function takes no 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:

This function takes no 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:

This function takes no 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:

This function takes no 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).

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.

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

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.

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

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.

## 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