Mainloop

Simple programs usually employ the main loop in a straightforward way:

The event structures (like struct main_file) are always allocated by the user, but please touch only the fields marked in this documentation with [*]. The other fields are used internally; you should initialize them to zeroes before adding the event and avoid accessing them afterwards.

In a more complex program, it can be useful to keep several sets of events and run a separate instance of the event loop for each such set. A typical example would be a multi-threaded program or a function which needs to communicate with a network server locally, ignoring all other events before the operation is finished.

For such cases, you can create multiple instances of struct main_context by calling main_new(). Each thread then keeps its own current context, which can be changed by main_switch_context(). All mainloop functions then either take an explicit pointer to a context or (more typically) they operate on the current context. When you no longer need the context, you can delete it by main_delete().

It is even possible to use nested main loops: in a hook called by the top-level instance of main_loop(), you can switch to a different context, call main_loop() recursively and when you are done, switch back and return to the top-level loop.

CAVEAT: In the present implementation, only a single context per process can handle process exit events. If you use process_add() in multiple contexts, it can happen that the current context catches the SIGCHLD signal and obtains information about a child process associated with another context, which it does not know how to handle. If you ever need this, please let us know.

Using the event loop in a multi-threaded or multi-process program is possible, but it should be done very carefully.

Multiple threads can use the main loop, but each of them must use a separate context (or contexts).

When you fork() a child process, either the parent or the child must give up use of each main loop context. The main_teardown() and main_destroy() functions can be useful for that. (The reason is that some parts of the main loop context, like file descriptors used internally, become shared between the processes, so the processes could influence each other in crazy ways. You do not want to hunt for such bugs.)

First of all, let us take a look at the basic operations with main loop contexts.

The main loop context

Create a new context.

Delete a context, assuming it does have any event handlers attached. Does nothing if m is NULL. It is allowed to call main_delete() from a hook function of the same context, but you must never return to the main loop — e.g., you can exit() the process instead.

Delete a context. If there are any event handlers attached, they are deactivated (but the responsibility to free the memory there were allocated from lies upon you). If there are any file handlers, the corresponding file descriptors are closed.

Switch the current context of the calling thread. Returns the previous current context.

Return the current context. Dies if there is none or if the context has been deleted.

Initialize the main loop module and create a top-level context.

Deinitialize the main loop module, calling main_delete() on the top-level context.

Deinitialize the main loop module, calling main_destroy() on the top-level context. This is especially useful in a freshly forked-off child process.

Start the event loop on the current context. It will watch the provided objects and call callbacks. Terminates when someone calls main_shut_down(), or when all hooks return HOOK_DONE or at last one hook returns HOOK_SHUTDOWN.

Perform a single iteration of the main loop. Check if there are any events ready and process them. If there are none, do not wait.

Ask the main loop to terminate at the nearest occasion.

Show the current state of a given context (use main_debug() for the current context). Available only if LibUCW has been compiled with CONFIG_UCW_DEBUG.

The event loop provides the current time, measured as a 64-bit number of milliseconds since the system epoch (represented in the type timestamp_t).

You can also register timers, which call a handler function at a given moment. The handler function must either call timer_del() to delete the timer, or call timer_add() with a different expiration time.

Get the current timestamp cached in the current context. It is refreshed in every iteration of the event loop, or explicitly by calling main_get_time().

This is a description of a timer. You define the handler function and possibly user-defined data you wish to pass to the handler, and then you invoke timer_add().

Add a new timer into the main loop to be watched and called when it expires. It can also be used to modify an already running timer. It is permitted (and usual) to call this function from the timer’s handler itself if you want the timer to trigger again.

The expire parameter is absolute (in the same time scale as main_get_now()), use timer_add_rel() for a relative version.

Like timer_add(), but the expiration time is relative to the current time.

Removes a timer from the active ones. It is permitted (and common) to call this function from the timer’s handler itself if you want to deactivate the timer. Removing an already removed timer does nothing.

Tells whether a timer is running.

Forces refresh of the current timestamp cached in the active context. You usually do not need to call this, since it is called every time the loop polls for events. It is here if you need extra precision or some of the hooks takes a long time.

Show current state of a timer. Available only if LibUCW has been compiled with CONFIG_UCW_DEBUG.

The hooks are called whenever the main loop performs an iteration. You can shutdown the main loop from within them or request an iteration to happen without sleeping (just poll, no waiting for events).

A hook. It contains the function to call and some user data.

The handler() must return one value from main_hook_return.

Fill with the hook and data and pass it to hook_add().

Return value of the hook handler(). Specifies what should happen next.

The HOOK_IDLE and HOOK_RETRY constants are also used as return values of file handlers.

Inserts a new hook into the loop. The hook will be scheduled at least once before next sleep. May be called from inside a hook handler too. Adding an already added hook is permitted and if the hook has been run, it will be run again before next sleep.

Removes an existing hook from the loop. May be called from inside a hook handler (to delete itself or another hook). Removing an already removed hook does nothing.

Tells if a hook is active (i.e., added).

Show current state of a hook. Available only if LibUCW has been compiled with CONFIG_UCW_DEBUG.

You can ask the main loop to watch a set of file descriptors for activity. (This is a generalization of the select() and poll() system calls. Internally, it uses either poll() or the more efficient epoll().)

You create a struct main_file, fill in a file descriptor and pointers to handler functions to be called when the descriptor becomes ready for reading and/or writing, and call file_add(). When you need to modify the handlers (e.g., to set them to NULL if you are no longer interested in a given event), you should call file_chg() to notify the main loop about the changes.

From within the handler functions, you are allowed to call file_chg() and even file_del().

The return value of a handler function should be either HOOK_RETRY or HOOK_IDLE. HOOK_RETRY signals that the function would like to consume more data immediately (i.e., it wants to be called again soon, but the event loop can postpone it after processing other events to avoid starvation). HOOK_IDLE tells that the handler wants to be called when the descriptor becomes ready again.

For backward compatibility, 0 can be used instead of HOOK_IDLE and 1 for HOOK_RETRY.

If you want to read/write fixed-size blocks of data asynchronously, the Asynchronous block I/O interface could be more convenient.

This structure describes a file descriptor to be watched and the handlers to be called when the descriptor is ready for reading and/or writing.

Insert a main_file structure into the main loop to be watched for activity. You can call this at any time, even inside a handler (of course for a different file descriptor than the one of the handler).

The file descriptor is automatically set to the non-blocking mode.

Tell the main loop that the file structure has changed. Call it whenever you change any of the handlers.

Can be called only on active files (only the ones added by file_add()).

Removes a file from the watched set. If you want to close a descriptor, please use this function first.

Can be called from a handler. Removing an already removed file does nothing.

Tells if a file is active (i.e., added).

Show current state of a file. Available only if LibUCW has been compiled with CONFIG_UCW_DEBUG.

If you are reading or writing fixed-size blocks of data, you can let the block I/O interface handle the boring routine of handling partial reads and writes for you.

You just create struct main_block_io and call block_io_add() on it, which sets up some main_files internally. Then you can just call block_io_read() or block_io_write() to ask for reading or writing of a given block. When the operation is finished, your handler function is called.

Additionally, the block I/O is equipped with a timer, which can be used to detect communication timeouts. The timer is not touched internally (except that it gets added and deleted at the right places), feel free to adjust it from your handler functions by block_io_set_timeout(). When the timer expires, the error handler is automatically called with BIO_ERR_TIMEOUT.

The block I/O structure.

Activate a block I/O structure.

Deactivate a block I/O structure. Calling twice is safe.

Specifies when or why an error happened. This is passed to the error handler. errno is still set to the original source of error. The only exception is BIO_ERR_TIMEOUT, in which case errno is not set and the only possible cause of it is timeout of the timer associated with the block_io (see block_io_set_timeout()).

Ask the main loop to read len bytes of data from bio into buf. It cancels any previous unfinished read requested in this way.

When the read is done, the read_done() handler is called. If an EOF occurred, rpos < rlen (eg. not all data were read).

Can be called from a handler.

You can use a call with zero len to cancel the current read, but all read data will be thrown away.

Request that the main loop writes len bytes of data from buf to bio. Cancels any previous unfinished write and overwrites write_handler.

When it is written, the write_done() handler is called.

Can be called from a handler.

If you call it with zero len, it will cancel the previous write, but note that some data may already be written.

Sets a timer for a file bio. If the timer is not overwritten or disabled until expires_delta milliseconds, the file timeouts and error_handler() is called with BIO_ERR_TIMEOUT. A value of 0 stops the timer.

Previous setting of the timeout on the same file will be overwritten.

The use-cases for this are mainly sockets or pipes, when:

Tells if a bio is active (i.e., added).

Record-based I/O is another front-end to the main loop file operations. Unlike its older cousin main_block_io, it is able to process records of variable length.

To set it up, you create struct main_rec_io and call rec_io_add() on it, which sets up some main_files internally.

To read data from the file, call rec_io_start_read() first. Whenever any data arrive from the file, they are appended to an internal buffer and the read_handler hook is called. The hook checks if the buffer already contains a complete record. If it is so, it processes the record and returns the number of bytes consumed. Otherwise, it returns 0 to tell the buffering machinery that more data are needed. When the read handler decides to destroy the main_rec_io, it must return ~0U.

On the write side, main_rec_io maintains a buffer keeping all data that should be written to the file. The rec_io_write() function appends data to this buffer and it is written on background. A simple flow-control mechanism can be asked for: when more than write_throttle_read data are buffered for writing, reading is temporarily suspended.

Additionally, the record I/O is equipped with a timer, which can be used to detect communication timeouts. The timer is not touched internally (except that it gets added and deleted at the right places), feel free to adjust it from your handler functions by rec_io_set_timeout().

All important events are passed to the notify_handler: errors when reading or writing, timeouts, the write buffer becoming empty, … See enum rec_io_notify_status for a complete list.

The record I/O structure.

Activate a record I/O structure.

Deactivate a record I/O structure. Calling twice is safe.

Start reading.

When there were some data in the buffer (e.g., because rec_io_stop_read() was called from the read_handler), it is processed as if it were read from the file once again. That is, read_prev_avail is reset to 0 and the read_handler is called to process all buffered data.

Stop reading.

Analogous to block_io_set_timeout().

An auxiliary function used for parsing of lines. When called in the read_handler, it searches for the end of line character. When a complete line is found, the length of the line (including the end of line character) is returned. Otherwise, it returns zero.

Specifies what kind of error or other event happened, when the notify_handler is called. In case of I/O errors, errno is still set.

Upon RIO_ERR_READ, RIO_ERR_RECORD_TOO_LARGE and RIO_EVENT_EOF, reading is stopped automatically. Upon RIO_ERR_WRITE, writing is stopped. Upon RIO_ERR_TIMEOUT, only the timer is deactivated.

In all cases, the notification handler is allowed to call rec_io_del(), but it must return HOOK_IDLE in such cases.

Tells if a rio is active (i.e., added).

The main loop can watch child processes and notify you, when some of them terminates.

Description of a watched process. You fill in the handler() and data. The rest is set with process_fork().

Asks the main loop to watch this process. As it is done automatically in process_fork(), you need this only if you removed the process previously by process_del().

Removes the process from the watched set. This is done automatically, when the process terminates, so you need it only when you do not want to watch a running process any more. Removing an already removed process does nothing.

Forks and fills the mp with information about the new process.

If the fork() succeeds, it:

In the case of unsuccessful fork(), it:

Tells if a process is active (i.e., added).

Show current state of a process. Available only if LibUCW has been compiled with CONFIG_UCW_DEBUG.

UNIX signals are delivered to processes in an asynchronous way: when a signal arrives (and it is not blocked), the process is interrupted and the corresponding signal handler function is called. However, most data structures and even most system library calls are not safe with respect to interrupts, so most program using signals contain subtle race conditions and may fail once in a long while.

To avoid this problem, the event loop can be asked for synchronous delivery of signals. When a signal registered with signal_add() arrives, it wakes up the loop (if it is not already awake) and it is processed in the same way as all other events.

When used in a multi-threaded program, the signals are delivered to the thread which is currently using the particular main loop context. If the context is not current in any thread, the signals are blocked.

As usually with UNIX signals, multiple instances of a single signal can be merged and delivered only once. (Some implementations of the main loop can even drop a signal completely during very intensive signal traffic, when an internal signal queue overflows.)

Description of a signal to catch.

Request a signal to be caught and delivered synchronously.

Cancel a request for signal catching. Calling twice is safe.

Tells if a signal catcher is active (i.e., added).

Show current state of a signal catcher. Available only if LibUCW has been compiled with CONFIG_UCW_DEBUG.