NAME

multiplexor -- handle concurrent network sessions


SYNOPSIS

   #include <afblib/multiplexor.h>
   typedef struct connection {
      int fd;
      void* handle;
      void* mpx_handle;
      // additional private fields
   } connection;
   typedef void (*input_handler)(connection* link, char* buf, unsigned int len);
   typedef void (*close_handler)(connection* link);
   void run_multiplexor(int socket, input_handler ihandler,
      close_handler chandler, void* mpx_handle);
   int write_to_link(connection* link, char* buf, unsigned int len);
   void close_link(connection* link);


DESCRIPTION

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 ihandler for each incoming packet, 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 only in case of errors.

Input handlers are invoked whenever some input packet is seen from any of the network sessions. This packet is passed using the parameters buf and len. To distinguish between individual sessions, a link parameter is provided that offers following fields that might be of interest for the input handler:

fd

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.

handle

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.

mpx_handle

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 buffer specified by buf and len to the input handler must be freed by the input handler. On the opposite side, the buffer passed to write_to_link by the input handler is freed as soon its contents has been written to the network connection.

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.


AUTHOR

Andreas F. Borchert