Pollcat Library

Pollcat is a lightweight library which wraps the poll() system call and makes it easy to build nonblocking applications where cooperative scheduling is adequate and threads are not warranted.

It provides an API for managing a list of pollfd structs, timeouts, and the poll() system call; millisecond-resolution oneshot timers; an embeddable struct to anchor pollable objects; and iterators and wrappers for a simple main loop.

Operations which can fail (ie due to memory allocation) return void to simplify user code; instead a fatal error triggers a callback to a user-supplied handler, or an error message and call to abort().

The library is released under LGPL v3.

Poll API

An internal sorted pollfd array is populated with functions which add, modify, and remove FDs and event bitmasks; the returned events bitmask can be queried. An internal timeout value is maintained and used inside the poll() call wrapper, it can be reduced by other code to improve latency.

As with poll() timeouts are managed in milliseconds. Pollcat maintains an internal minimum timeout, used by default by the wrapped poll() call. Interfaces using pollcat for non-blocking plumbing may optionally reduce the current timeout per loop, so the poll() call returns when appropriate.

This is used by the timer API to ensure the poll() returns at the correct idle time so the pending timer(s) can be serviced.

• void pollcat_fd_add() - Add an FD to the internal pollfd array, or change the events value on an existing entry
• void pollcat_fd_remove() - Remove an FD from the internal pollfd array
• short int pollcat_events_get() - Get the events field for an FD
• void pollcat_events_set() - Set the events field for an FD
• short int pollcat_revents() - Get the revents field for an FD, after poll()
• pollcat_time_reduce() - Reduce the current timeout if time is shorter
• int pollcat_poll() - Call poll() on the internal pollfd array and current timeout
• extern pollcat_assert_f pollcat_assert_func - Optional user-supplied function to handle fatal errors; if unset a message will be printed to stderr and abort() called to terminate the process
• extern int pollcat_time_base - The base timeout in milliseconds for poll() - the current timeout is reset to this after each wrapped poll() call. The default is set at compile time with the symbol POLLCAT_TIME_BASE
• extern int pollcat_time_minimum - The minimum timeout in milliseconds for poll() - the default is set at compile time with the symbol POLLCAT_TIME_MINIMUM
• extern size_t pollcat_size_initial - The initial size of the internal pollfd array. The default is set at compile time with the symbol POLLCAT_SIZE_INITIAL
• extern size_t pollcat_size_increment - The incremental size to grow the internal pollfd array by when necessary. The default is set at compile time with the symbol POLLCAT_SIZE_INCREMENT

Event Timers

A simple oneshot timer is provided for timed events; timers can be detached and re-attached at any time. If using the convenience functions, the due time for the poll() timeout is automatically reduced to the nearest timer.

If not using the pollcat_loop() function, the user should call the timer reduction function before poll() and the dispatch function after.

• void pollcat_timer_attach() - Attach a timer to the active list, specifying timeout in milliseconds, callback function, and argument
• void pollcat_timer_detach() - Detach a timer from the active list
• void pollcat_timer_reduce_timeout() - Calculate the deadline to the next timer due, and reduce the poll() timeout to match, if less than the current timeout
• void pollcat_timer_dispatch() - Execute timers which are due
• extern int pollcat_timer_dispatch_max - Sets the maximum number of timers executed per call to pollcat_timer_dispatch()
• extern pollcat_time_t pollcat_timer_dispatch_thresh - Sets a "grace" time for delayed timers
• typedef uint64_t pollcat_time_t - Sets the timer type, tunable for system size

Embeddable Struct and Convenience API

Pollcat implements a base struct with linked-list and operations struct pointers. This can be embedded in other structs to make them easily plugged into a polling main loop.

The pollcat_loop() function will iterate through the list, calling the supplied prepare() function before poll() and the supplied service() function after.

Pollcat objects can be added to an internal list with the pollcat_iter_add() function, and the main-loop function pollcat_loop() will iterate through them, perform the poll() call, and service timers.

• struct pollcat - Pollcat object structure, passed to the convenience API functions
• struct pollcat_ops - Operations structure, with function pointers supplied by the user or objects which wrap a Pollcat object.
• void pollcat_iter_add() - Add a Pollcat object to the iterator list
• void pollcat_iter_remove() - Remove a Pollcat object from the iterator list
• void pollcat_iter_reset() - Reset the cursor on the iterator list
• struct pollcat *pollcat_iter_next() - Return the next Pollcat object on the list
• int pollcat_loop() - Service active timers and Pollcat objects; returns true as long as main loop should continue
• void pollcat_loop_exit() - Sets a flag so pollcat_loop() will return false and main loop will stop

Example Application

An example application is provided which demonstrates use of the library. It provides a simple terminal to a serial device, with a command mode triggered by Ctrl-A. A timer shows a menu after 1 second. The only command implemented is to shut down, via the Q or X keys, with or without Ctrl.