Abstracted event loop

## Abstracted event loop Abstracted event loop — Abstracted event loop API for customizing event loop in GCutter. |

## Synopsis

    #define             GCUT_EVENT_LOOP_ERROR
    struct              GCutEventLoop;
    struct              GCutEventLoopClass;
    GQuark              gcut_event_loop_error_quark         (void);
    void                gcut_event_loop_run                 (GCutEventLoop *loop);
    gboolean            gcut_event_loop_iterate             (GCutEventLoop *loop,
                                                             gboolean may_block);
    void                gcut_event_loop_quit                (GCutEventLoop *loop);
    guint               gcut_event_loop_watch_io            (GCutEventLoop *loop,
                                                             GIOChannel *channel,
                                                             GIOCondition condition,
                                                             GIOFunc function,
                                                             gpointer data);
    guint               gcut_event_loop_watch_child         (GCutEventLoop *loop,
                                                             GPid pid,
                                                             GChildWatchFunc function,
                                                             gpointer data);
    guint               gcut_event_loop_watch_child_full    (GCutEventLoop *loop,
                                                             gint priority,
                                                             GPid pid,
                                                             GChildWatchFunc function,
                                                             gpointer data,
                                                             GDestroyNotify notify);
    guint               gcut_event_loop_add_timeout         (GCutEventLoop *loop,
                                                             gdouble interval_in_seconds,
                                                             GSourceFunc function,
                                                             gpointer data);
    guint               gcut_event_loop_add_timeout_full    (GCutEventLoop *loop,
                                                             gint priority,
                                                             gdouble interval_in_seconds,
                                                             GSourceFunc function,
                                                             gpointer data,
                                                             GDestroyNotify notify);
    guint               gcut_event_loop_add_idle            (GCutEventLoop *loop,
                                                             GSourceFunc function,
                                                             gpointer data);
    guint               gcut_event_loop_add_idle_full       (GCutEventLoop *loop,
                                                             gint priority,
                                                             GSourceFunc function,
                                                             gpointer data,
                                                             GDestroyNotify notify);
    gboolean            gcut_event_loop_remove              (GCutEventLoop *loop,
                                                             guint tag);

## Object Hierarchy

      GObject
       +----GCutEventLoop

## Description

GCutEventLoop encapsulates event loop. For example, event loop is used in GCutProcess. It uses the GLib's default main context for it.

Normally, a custom GCutEventLoop isn't required. It is needed some special case. For example, using libev as event loop backend instead of GLib's main loop.

GCutter provides GCutEventLoop for GLib's main context and main loop, GCutGLibEventLoop.

## Details

### GCUT_EVENT_LOOP_ERROR

    #define GCUT_EVENT_LOOP_ERROR           (gcut_event_loop_error_quark())

### struct GCutEventLoop

    struct GCutEventLoop;

### struct GCutEventLoopClass

    struct GCutEventLoopClass {
        GObjectClass parent_class;

        void     (*run)              (GCutEventLoop   *loop);
        gboolean (*iterate)          (GCutEventLoop   *loop,
                                      gboolean         may_block);
        void     (*quit)             (GCutEventLoop   *loop);

        guint    (*watch_io)         (GCutEventLoop   *loop,
                                      GIOChannel      *channel,
                                      GIOCondition     condition,
                                      GIOFunc          function,
                                      gpointer         data);
        guint    (*watch_child_full) (GCutEventLoop   *loop,
                                      gint             priority,
                                      GPid             pid,
                                      GChildWatchFunc  function,
                                      gpointer         data,
                                      GDestroyNotify   notify);
        guint    (*add_timeout_full) (GCutEventLoop   *loop,
                                      gint             priority,
                                      gdouble          interval_in_seconds,
                                      GSourceFunc      function,
                                      gpointer         data,
                                      GDestroyNotify   notify);
        guint    (*add_idle_full)    (GCutEventLoop   *loop,
                                      gint             priority,
                                      GSourceFunc      function,
                                      gpointer         data,
                                      GDestroyNotify   notify);
        gboolean (*remove)           (GCutEventLoop   *loop,
                                      guint            tag);
    };

### gcut_event_loop_error_quark ()

    GQuark              gcut_event_loop_error_quark         (void);

### gcut_event_loop_run ()

    void                gcut_event_loop_run                 (GCutEventLoop *loop);

Runs the given event loop until `gcut_event_loop_quit()` is called on the loop.

`loop` : | a GCutEventLoop.

Since 1.1.6

### gcut_event_loop_iterate ()

    gboolean            gcut_event_loop_iterate             (GCutEventLoop *loop,
                                                             gboolean may_block);

Runs a single iteration for the given event loop. If no events are ready and `may_block` is `TRUE`, waiting for a event become ready. Otherwise, if `may_block` is `FALSE`, events are not waited to become ready.

`loop` : | a GCutEventLoop.
`may_block` : | whether the call may block.
Returns : | `TRUE` if a event was dispatched.

Since 1.1.6

### gcut_event_loop_quit ()

    void                gcut_event_loop_quit                (GCutEventLoop *loop);

Stops the `loop` from running.

`loop` : | a GCutEventLoop.

Since 1.1.6

### gcut_event_loop_watch_io ()

    guint               gcut_event_loop_watch_io            (GCutEventLoop *loop,
                                                             GIOChannel *channel,
                                                             GIOCondition condition,
                                                             GIOFunc function,
                                                             gpointer data);

Adds the `channel` into `loop` with the default priority. `function` is called when `condition` is met for the given `channel`.

`loop` : | a GCutEventLoop.
`channel` : | a GIOChannel
`condition` : | conditions to watch for
`function` : | function to call
`data` : | data to pass to `function`
Returns : | the event ID.

Since 1.1.6

### gcut_event_loop_watch_child ()

    guint               gcut_event_loop_watch_child         (GCutEventLoop *loop,
                                                             GPid pid,
                                                             GChildWatchFunc function,
                                                             gpointer data);

Adds the `function` to be called when the child indicated by `pid` exits into `loop` with the default priority.

`loop` : | a GCutEventLoop.
`pid` : | process ID to watch
`function` : | function to call
`data` : | data to pass to `function`
Returns : | the event ID.

Since 1.1.6

### gcut_event_loop_watch_child_full ()

    guint               gcut_event_loop_watch_child_full    (GCutEventLoop *loop,
                                                             gint priority,
                                                             GPid pid,
                                                             GChildWatchFunc function,
                                                             gpointer data,
                                                             GDestroyNotify notify);

Adds the `function` to be called when the child indicated by `pid` exits into `loop` with the `priority`.

`loop` : | a GCutEventLoop.
`priority` : | the priority of the event.
`pid` : | process ID to watch
`function` : | function to call
`data` : | data to pass to `function`
`notify` : | function to call when the event is removed, or `NULL`
Returns : | the event ID.

Since 1.1.6

### gcut_event_loop_add_timeout ()

    guint               gcut_event_loop_add_timeout         (GCutEventLoop *loop,
                                                             gdouble interval_in_seconds,
                                                             GSourceFunc function,
                                                             gpointer data);

Adds the `function` to be called at regular intervals, with the default priority.

`loop` : | a GCutEventLoop.
`interval_in_seconds` : | the time between calls to the `function`, in seconds.
`function` : | function to call
`data` : | data to pass to `function`
Returns : | the event ID.

Since 1.1.6

### gcut_event_loop_add_timeout_full ()

    guint               gcut_event_loop_add_timeout_full    (GCutEventLoop *loop,
                                                             gint priority,
                                                             gdouble interval_in_seconds,
                                                             GSourceFunc function,
                                                             gpointer data,
                                                             GDestroyNotify notify);

Adds the `function` to be called at regular intervals, with the `priority`.

`loop` : | a GCutEventLoop.
`priority` : | the priority of the event.
`interval_in_seconds` : | the time between calls to the `function`, in seconds.
`function` : | function to call
`data` : | data to pass to `function`
`notify` : | function to call when the event is removed, or `NULL`
Returns : | the event ID.

Since 1.1.6

### gcut_event_loop_add_idle ()

    guint               gcut_event_loop_add_idle            (GCutEventLoop *loop,
                                                             GSourceFunc function,
                                                             gpointer data);

Adds the `function` to be called whenever there are no higher priority events pending with the default priority.

`loop` : | a GCutEventLoop.
`function` : | function to call
`data` : | data to pass to `function`
Returns : | the event ID.

Since 1.1.6

### gcut_event_loop_add_idle_full ()

    guint               gcut_event_loop_add_idle_full       (GCutEventLoop *loop,
                                                             gint priority,
                                                             GSourceFunc function,
                                                             gpointer data,
                                                             GDestroyNotify notify);

Adds the `function` to be called whenever there are no higher priority events pending with the `priority`.

`loop` : | a GCutEventLoop.
`priority` : | the priority of the event.
`function` : | function to call
`data` : | data to pass to `function`
`notify` : | function to call when the event is removed, or `NULL`
Returns : | the event ID.

Since 1.1.6

### gcut_event_loop_remove ()

    gboolean            gcut_event_loop_remove              (GCutEventLoop *loop,
                                                             guint tag);

Removes the event with the given ID, `tag`.

`loop` : | a GCutEventLoop.
`tag` : | the ID of the source to remove
Returns : | `TRUE` if the source was found and removed.

Since 1.1.6