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
Prototype Functions
Tables
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
Back to Karma Home Page
Contact: Richard Gooch
Web Development: Ariel Internet Services