InfIo: libinfinity-0.7 Reference Manual

## InfIo InfIo — Event loop abstraction |

## Stability Level

Unstable, unless otherwise indicated

## Functions

void | (*InfIoWatchFunc) ()
void | (*InfIoTimeoutFunc) ()
void | (*InfIoDispatchFunc) ()
InfIoWatch * | inf_io_add_watch ()
InfIoWatch * | inf_io_add_watch_from_fd ()
void | inf_io_update_watch ()
void | inf_io_remove_watch ()
InfIoTimeout * | inf_io_add_timeout ()
void | inf_io_remove_timeout ()
InfIoDispatch * | inf_io_add_dispatch ()
void | inf_io_remove_dispatch ()

## Types and Values

| InfIo
struct | InfIoInterface
enum | InfIoEvent
| InfIoWatch
| InfIoTimeout
| InfIoDispatch

## Object Hierarchy

        GFlags
        ╰── InfIoEvent
        GInterface
        ╰── InfIo

## Prerequisites

InfIo requires GObject.

## Known Implementations

InfIo is implemented by InfStandaloneIo.

## Includes

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

## 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).

## Functions

### InfIoWatchFunc ()

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

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

#### Parameters

socket | The socket on which an event occurred. | [array fixed-size=1]
event | A bitmask of the events that occurred. |
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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

[transfer none]

### inf_io_add_watch_from_fd ()

    InfIoWatch *
    inf_io_add_watch_from_fd (InfIo *io,
                              int fd,
                              InfIoEvent events,
                              InfIoWatchFunc func,
                              gpointer user_data,
                              GDestroyNotify notify);

Monitors the given file descriptor for activity and calls `func` if one of the events specified in `events` occurs. This is equivalent to `inf_io_add_watch()` for a socket that represents the given file descriptor, but takes care of the memory management of the file descriptor. This function is especially intended for language bindings. It is only available on unix-like operating systems.

#### Parameters

io | A InfIo. |
fd | The file descriptor 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.

[transfer none]

### 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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

[transfer none]

### inf_io_remove_timeout ()

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

Removes the given timeout.

#### Parameters

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.

#### Parameters

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.

[transfer none]

### 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.

#### Parameters

io | A InfIo. |
dispatch | A dispatch handle obtained from `inf_io_add_dispatch()`. |

## Types and Values

### InfIo

    typedef struct _InfIo InfIo;

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

### struct InfIoInterface

    struct InfIoInterface {
      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.

#### Members

`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. |

### enum InfIoEvent

This enumeration specifies events that can be watched.

#### Members

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 occurred, 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;

InfIoWatch represents a watch on a InfNativeSocket for events to occur. It is an opaque data type. You should only access it via the public API functions.

### InfIoTimeout

    typedef struct _InfIoTimeout InfIoTimeout;

InfIoTimeout represents a timer which will call a specified function in the future. It is an opaque data type. You should only access it via the public API functions.

### InfIoDispatch

    typedef struct _InfIoDispatch InfIoDispatch;

InfIoDispatch represents a function to be called by the thread executing the InfIo object. It is an opaque data type. You should only access it via the public API functions.

## See Also

InfStandaloneIo