multiplexor -- handle concurrent network sessions
#include <afblib/multiplexor.h>
typedef struct connection {
int fd;
void* handle;
void* mpx_handle;
// additional private fields
} connection;
typedef void (*multiplexor_handler)(connection* link);
void run_multiplexor(int socket,
multiplexor_handler open_handler,
multiplexor_handler input_handler,
multiplexor_handler close_handler,
void* mpx_handle);
bool write_to_link(connection* link, char* buf, unsigned int len);
ssize_t read_from_link(connection* link, char* buf, unsigned int len);
void close_link(connection* link);
These functions allow to handle multiple network connections within one address space by one process without resorting to threads.
run_multiplexor accepts any number of incoming stream-oriented network connections coming through socket, monitors the existing connections for incoming data, invokes ohandler, if not null, for each new connection, invokes ihandler whenever the next input packet can be read using read_from_link, and allows through write_to_link to file response packets in a non-blocking way. The close handler chandler, if non-null, is invoked by run_multiplexor as soon as a session terminates. This function runs infinitely and returns in case of errors only.
All handlers get a connection handler that allows to distinguish between individual sessions. Behind link following fields are provided that might be of interest for the handlers:
This integer value represents the file descriptor of the network connection. It may be used for functions like getpeername but not for I/O operations like read or write.
This field is initially null and remains untouched by run_multiplexor. This handle allows the input handler to recognize new sessions (if the handle is null) and to assign a pointer to an object representing the associated session. If this handle is being used and points to a dynamically allocated object, it should be disposed by the close handler.
This handle points to an optional handle representing the network service that has been passed to run_multiplexor. It can be set to null if it is not needed.
Input handlers that want to generate a response packet must use the write_to_link function that works like write but takes a connection link (passed to the input handler) instead of a file descriptor. Calls to write_to_link never block. The only possible failure which can be expected from a write_to_link invocation is to run out of memory.
The input handler must not use read but read_from_link to read the next input packet. Multiple calls are not permitted, i.e. each input handler, if invoked, must call read_from_link exactly once. If read_from_link gets no more input as the connection has been closed, the close handler will be invoked, if defined.
The output buffer that is passed to write_to_link is, if write_to_link returns true, subsequently owned by this module and freed when it is no longer needed. It must not be reused or freed by the caller.
close_link allows to shutdown the reading side of a connection, i.e. the input handler will no longer be called, just the pending list of response packets will be handled.
Andreas F. Borchert