InfIo

InfIo — Event loop abstraction

Stability Level

Unstable, unless otherwise indicated

Synopsis

#include <libinfinity/common/inf-io.h>

                    InfIo;
struct              InfIoIface;
typedef             InfNativeSocket;
enum                InfIoEvent;
                    InfIoWatch;
                    InfIoTimeout;
                    InfIoDispatch;
void                (*InfIoWatchFunc)                   (InfNativeSocket *socket,
                                                         InfIoEvent event,
                                                         gpointer user_data);
void                (*InfIoTimeoutFunc)                 (gpointer user_data);
void                (*InfIoDispatchFunc)                (gpointer user_data);
InfIoWatch *        inf_io_add_watch                    (InfIo *io,
                                                         InfNativeSocket *socket,
                                                         InfIoEvent events,
                                                         InfIoWatchFunc func,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);
void                inf_io_update_watch                 (InfIo *io,
                                                         InfIoWatch *watch,
                                                         InfIoEvent events);
void                inf_io_remove_watch                 (InfIo *io,
                                                         InfIoWatch *watch);
InfIoTimeout *      inf_io_add_timeout                  (InfIo *io,
                                                         guint msecs,
                                                         InfIoTimeoutFunc func,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);
void                inf_io_remove_timeout               (InfIo *io,
                                                         InfIoTimeout *timeout);
InfIoDispatch *     inf_io_add_dispatch                 (InfIo *io,
                                                         InfIoDispatchFunc func,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);
void                inf_io_remove_dispatch              (InfIo *io,
                                                         InfIoDispatch *dispatch);

Object Hierarchy

  GInterface
   +----InfIo
  GFlags
   +----InfIoEvent

Prerequisites

InfIo requires GObject.

Known Implementations

InfIo is implemented by InfStandaloneIo.

Description

The InfIo interface is used to schedule timeouts and to watch sockets for events to occur. An actual implementation usually integrates this into the application main loop, such as GMainLoop. There is also a standalone implementation, InfStandaloneIo, that can directly be used as the application's main loop.

Every object in Libinfinity that needs to schedule timeouts or watches sockets uses a InfIo to do so. This allows to use libinfinity with different main event loops, not only Glib's one.

InfIo is guaranteed to be thread-safe. All functions can be called from any thread at any time. However, all callback functions are always called from the same thread (normally the one running the main loop).

Details

InfIo

typedef struct _InfIo InfIo;

InfIo is an opaque data type. You should only access it via the public API functions.


struct InfIoIface

struct InfIoIface {
  InfIoWatch* (*add_watch)(InfIo* io,
                           InfNativeSocket* socket,
                           InfIoEvent events,
                           InfIoWatchFunc func,
                           gpointer user_data,
                           GDestroyNotify notify);

  void (*update_watch)(InfIo* io,
                       InfIoWatch* watch,
                       InfIoEvent events);

  void (*remove_watch)(InfIo* io,
                       InfIoWatch* watch);

  InfIoTimeout* (*add_timeout)(InfIo* io,
                               guint msecs,
                               InfIoTimeoutFunc func,
                               gpointer user_data,
                               GDestroyNotify notify);

  void (*remove_timeout)(InfIo* io,
                         InfIoTimeout* timeout);

  InfIoDispatch* (*add_dispatch)(InfIo* io,
                                 InfIoDispatchFunc func,
                                 gpointer user_data,
                                 GDestroyNotify notify);

  void (*remove_dispatch)(InfIo* io,
                          InfIoDispatch* dispatch);
};

The virtual methods of InfIo. These allow to set up socket watches, timeouts and function dispatchers. All of these functions need to be thread-safe.

add_watch ()

Watches a socket for events to occur in which case func is called.

update_watch ()

Updates a watch on a socket so that a different set of events is watched for.

remove_watch ()

Removes a watch on a socket.

add_timeout ()

Schedules func to be called at least msecs milliseconds in the future.

remove_timeout ()

Removes a scheduled timeout again. The timeout is removed automatically when it has elapsed, so there is no need to call this function in that case.

add_dispatch ()

Schedules func to be called by the thread the InfIo runs in.

remove_dispatch ()

Removes a scheduled dispatch. This can be called as long as the scheduled function has not yet been called.

InfNativeSocket

typedef SOCKET InfNativeSocket;

Native socket type on the target platform. This typedef is a simple int on Unix and a SOCKET on Windows.


enum InfIoEvent

typedef enum _InfIoEvent {
  INF_IO_INCOMING = 1 << 0,
  INF_IO_OUTGOING = 1 << 1,
  INF_IO_ERROR    = 1 << 2
} InfIoEvent;

This enumeration specifies events that can be watched.

INF_IO_INCOMING

Data can be read from the socket without blocking, or the connection has been closed (which is the case when recv() returns 0).

INF_IO_OUTGOING

Data can be sent without blocking.

INF_IO_ERROR

An error with the socket occured, or the connection has been closed. Use getsockopt() to read the SO_ERROR option to find out what the problem is.

InfIoWatch

typedef struct _InfIoWatch InfIoWatch;


InfIoTimeout

typedef struct _InfIoTimeout InfIoTimeout;


InfIoDispatch

typedef struct _InfIoDispatch InfIoDispatch;


InfIoWatchFunc ()

void                (*InfIoWatchFunc)                   (InfNativeSocket *socket,
                                                         InfIoEvent event,
                                                         gpointer user_data);

Callback function that is called when an event occurs on a watched socket.

socket :

The socket on which an event occured.

event :

A bitmask of the events that occured.

user_data :

User-defined data specified in inf_io_add_watch().

InfIoTimeoutFunc ()

void                (*InfIoTimeoutFunc)                 (gpointer user_data);

Callback function that is called when a timeout has elapsed.

user_data :

User-defined data specified in inf_io_add_timeout().

InfIoDispatchFunc ()

void                (*InfIoDispatchFunc)                (gpointer user_data);

Callback function that is called when a dispatch is executed by the thread that runs InfIo.

user_data :

User-defined data specified in inf_io_add_dispatch().

inf_io_add_watch ()

InfIoWatch *        inf_io_add_watch                    (InfIo *io,
                                                         InfNativeSocket *socket,
                                                         InfIoEvent events,
                                                         InfIoWatchFunc func,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);

Monitors the given socket for activity and calls func if one of the events specified in events occurs.

io :

A InfIo.

socket :

The socket to watch.

events :

Events to watch for.

func :

Function to be called when one of the events occurs.

user_data :

Extra data to pass to func.

notify :

A GDestroyNotify that is called when user_data is no longer needed, or NULL.

Returns :

A InfIoWatch that can be used to update or remove the watch.

inf_io_update_watch ()

void                inf_io_update_watch                 (InfIo *io,
                                                         InfIoWatch *watch,
                                                         InfIoEvent events);

Changes the events that the socket bound to watch is being watched for. The callback of watch will only be called if one of the newly watched for events occurs.

io :

A InfIo.

watch :

The watch to update, as returned by inf_io_add_watch().

events :

The new events to watch for.

inf_io_remove_watch ()

void                inf_io_remove_watch                 (InfIo *io,
                                                         InfIoWatch *watch);

Removes watch from io and releases all resources allocated for the watch. Events are no longer looked for on the socket.

io :

A InfIo.

watch :

The watch to remove, as returned by inf_io_add_watch().

inf_io_add_timeout ()

InfIoTimeout *      inf_io_add_timeout                  (InfIo *io,
                                                         guint msecs,
                                                         InfIoTimeoutFunc func,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);

Calls func after at least msecs milliseconds have elapsed. The timeout is removed after it has elapsed.

io :

A InfIo.

msecs :

Number of milliseconds after which the timeout should be elapsed.

func :

Function to be called when the timeout elapsed.

user_data :

Extra data to pass to func.

notify :

A GDestroyNotify that is called when user_data is no longer needed, or NULL.

Returns :

A timeout handle that can be used to remove the timeout.

inf_io_remove_timeout ()

void                inf_io_remove_timeout               (InfIo *io,
                                                         InfIoTimeout *timeout);

Removes the given timeout.

io :

A InfIo.

timeout :

A timeout handle obtained from inf_io_add_timeout().

inf_io_add_dispatch ()

InfIoDispatch *     inf_io_add_dispatch                 (InfIo *io,
                                                         InfIoDispatchFunc func,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);

Schedules func to be called by the thread io runs in. This function can be used from a different thread to communicate to io's thread.

io :

A InfIo.

func :

Function to be called when the function is dispatched.

user_data :

Extra data to pass to func.

notify :

A GDestroyNotify that is called when user_data is no longer needed, or NULL.

Returns :

A dispatch handle that can be used to stop the dispatched function from being called as long as it has not yet been called.

inf_io_remove_dispatch ()

void                inf_io_remove_dispatch              (InfIo *io,
                                                         InfIoDispatch *dispatch);

Removes the given dispatch from io so that it is not called.

io :

A InfIo.

dispatch :

A dispatch handle obtained from inf_io_add_dispatch().

See Also

InfStandaloneIo