iox_util - I/O Event Dispatcher

The functions in this file implement an I/O event dispatcher. Applications that make use of the IOX dispatcher are generally structured as follows:

    Perform any application-specific initialization activities.
    Register event handlers with the IOX event dispatcher.
    DO forever
        Wait for the next event.
        CALL the handler function bound to the event.
    ENDDO

The event processing loop is encapsulated in an IOX function, ioxMonitor(). Other IOX functions are available to:

• Register an I/O source with the dispatcher. When an I/O condition (input-pending, output-ready, OOB-input-pending) is detected on the source, the dispatcher automatically invokes an application-defined handler function to respond to the event (e.g., to read input from a network connection).
• Register a single-shot or periodic timer with the dispatcher. When the specified time interval has elapsed, the dispatcher automatically invokes an application-defined handler function to react to the timeout.
• Register an idle task (an application-defined function) with the dispatcher. When no I/O sources are active and no timers are ready to fire, the dispatcher will execute the next idle task on its queue. Idle tasks are intended to perform "background" work.

I/O sources are registered with the NIX dispatcher by ioxOnIO(), timers by ioxAfter() and ioxEvery(), and idle tasks by ioxWhenIdle(). The monitoring of I/O sources, timers, and idle tasks is initiated by calling ioxMonitor(). Control can remain in ioxMonitor() for the lifetime of the application; the dispatcher loops forever, waiting for I/O and timer events and invoking the application-specified callback functions bound to the events.

Alternatively, a time interval can be specified to limit how long ioxMonitor() monitors events. The latter capability allows a form of polling and is useful when there are multiple dispatchers in an application (e.g., if the primary event dispatcher is a non-IOX dispatcher).

Notes

The IOX package was derived, 12 years later, from my NIX (Not Including X) package. (And was influenced by my experience with my C++ Dispatcher class.) The NIX functions were patterned after the corresponding X Toolkit functions. Mimicing the X Toolkit names and function signatures was intended to make it easier to reuse X- and non-X-based event-related code (if only through "cut, paste, search, and replace"). Unfortunately, opportunities to take advantage of such reuse did not present themselves subsequently and, in the mean time, I was saddled with a klunky API. The IOX package offers a simpler, more concise API - I hope!

The IOX monitoring function is implemented using a UNIX select(2) call and it supports read, write, and exceptional I/O events. The ancestral NIX package has been tested on various operating systems (Windows, Linux, UNIX, VMS, and VxWorks). The IOX package is largely the same code and I will test it on the various platforms as time permits. If you get the header files straight, the IOX package should work under other operating systems that support select(2).

The Windows WINSOCK and VMS UCX implementations of select(2) only support socket I/O and not arbitrary device I/O as in UNIX. In particular, you can't monitor standard input as an I/O source; I usually use IOX timers to periodically poll stdin for input.

Public Procedures (for dispatchers)

ioxAfter() - registers a single-shot timer with the dispatcher.

ioxCreate() - creates an I/O event dispatcher.

ioxDestroy() - destroys an I/O event dispatcher.

ioxEvery() - registers a periodic timer with the dispatcher.

ioxMonitor() - monitors and responds to I/O events.

ioxOnIO() - registers an I/O source with the dispatcher.

ioxWhenIdle() - registers an idle task with the dispatcher.

Public Procedures (for callbacks)

ioxCancel() - cancels a registered callback.

ioxDepth() - gets the callback nesting of a callback's dispatcher.

ioxDispatcher() - gets a callback's dispatcher.

ioxExpiration() - gets a timer callback's expiration time.

ioxFd() - gets an I/O callback's I/O source.

ioxInterval() - gets a timer callback's time interval.

ioxOnCancel() - sets a callback's invoke-on-cancel flag.

Source Files

iox_util.c

iox_util.h