GskMainLoopChange

typedef struct {
  GskMainLoopEventType type;
  union
  {
    struct {
      guint number;
      gboolean add;
    } signal;
    struct {
      guint fd;
      GIOCondition old_events;
      GIOCondition events;
    } io;
    struct {
      gint pid;
      gboolean add;
      gboolean did_exit;
    } process;
  } data;
} GskMainLoopChange;

This structure is passed to the system-dependent polling mechanism to indicate a change in events we want notification of.

GskMainLoopEvent

typedef struct {
  GskMainLoopEventType type;
  union
  {
    guint signal;
    struct {
      guint fd;
      GIOCondition events;
    } io;
    GskMainLoopWaitInfo process_wait_info;
  } data;
} GskMainLoopEvent;

An event passed back from the system-dependent polling mechanism.

GskMainLoopWaitInfo

typedef struct {
  int               pid; 
  gboolean          exited;         /* exit(2) or killed by signal? */
  union {
    int             signal;         /* !exited */
    int             exit_status;    /*  exited */
  } d;           
  gboolean          dumped_core;
} GskMainLoopWaitInfo;

Information about a process's termination.

GskSource

typedef struct _GskSource GskSource;

An opaque object representing a trap of an event.

GskMainLoopContextList

typedef struct _GskMainLoopContextList GskMainLoopContextList;

Private.

enum GskMainLoopEventType

typedef enum
{
  GSK_MAIN_LOOP_EVENT_IO,
  GSK_MAIN_LOOP_EVENT_SIGNAL,
  GSK_MAIN_LOOP_EVENT_PROCESS
} GskMainLoopEventType;

Types of event that can be dealt with by this main-loop.

GskMainLoopClass

typedef struct {
  GObjectClass object_class;
  gboolean (*setup)  (GskMainLoop       *main_loop);
  void     (*change) (GskMainLoop       *main_loop,
                      GskMainLoopChange *change);
  guint    (*poll)   (GskMainLoop       *main_loop,
                      guint              max_events_out,
                      GskMainLoopEvent  *events,
                      gint               timeout);
} GskMainLoopClass;

The virtual function which must be implemented for each type of main-loop.

GskMainLoop

typedef struct {
  gint		 exit_status;

  GskMainLoopEvent *event_array_cache;
  unsigned       max_events;

  /* a list of GMainContext's */
  GskMainLoopContextList *first_context;
  GskMainLoopContextList *last_context;
} GskMainLoop;

A main-loop. This holds information about all its sources.

GskMainLoopWaitPidFunc ()

void        (*GskMainLoopWaitPidFunc)       (GskMainLoopWaitInfo *info,
                                             gpointer user_data);

A function which will be invoked when a process terminates.

GskMainLoopIdleFunc ()

gboolean    (*GskMainLoopIdleFunc)          (gpointer user_data);

Function to be called repetitively (that is, with no blocking or waiting; however, other events will continue to be processed). It will stop when gsk_main_loop_remove() is run on its source, or if it returns FALSE.

GskMainLoopSignalFunc ()

gboolean    (*GskMainLoopSignalFunc)        (int sig_no,
                                             gpointer user_data);

Function to be called whenever a UNIX signal of a particular number is raised.

It will be untrapped when gsk_main_loop_remove() is run on its source, or if it returns FALSE.

GskMainLoopTimeoutFunc ()

gboolean    (*GskMainLoopTimeoutFunc)       (gpointer user_data);

Function to invoke whenever a timeout expires.

It will be untrapped when gsk_main_loop_remove() is run on its source, or if it returns FALSE, or after it runs if it was registered as a one-shot (with milli_period==-1).

GskMainLoopIOFunc ()

gboolean    (*GskMainLoopIOFunc)            (int fd,
                                             GIOCondition condition,
                                             gpointer user_data);

Function to run whenever some subset of a set of requested events are noticed.

enum GskMainLoopCreateFlags

typedef enum
{
  GSK_MAIN_LOOP_NEEDS_THREADS = (1 << 0)
} GskMainLoopCreateFlags;

Indicate user requirements for the main-loop being constructed.

gsk_main_loop_new ()

GskMainLoop* gsk_main_loop_new              (GskMainLoopCreateFlags create_flags);

Make a new main loop.

gsk_main_loop_default ()

GskMainLoop* gsk_main_loop_default          (void);

Get the main-loop which is associated with the current thread.

gsk_main_loop_run ()

guint       gsk_main_loop_run               (GskMainLoop *main_loop,
                                             gint timeout,
                                             guint *t_waited_out);

Run the main loop once, for a specified number of milliseconds.

gsk_main_loop_add_idle ()

GskSource*  gsk_main_loop_add_idle          (GskMainLoop *main_loop,
                                             GskMainLoopIdleFunc source_func,
                                             gpointer user_data,
                                             GDestroyNotify destroy);

This adds an idle function to the main loop. An idle function is a function which gets called every time the main loop is run. Furthermore, while there are idle functions, the main loop will never block.

One popular use of idle functions is to defer an operation, usually because either something is not in a good state to call immediately, or because there may be many requests that should be handled at one time.

gsk_main_loop_add_signal ()

GskSource*  gsk_main_loop_add_signal        (GskMainLoop *main_loop,
                                             int signal_number,
                                             GskMainLoopSignalFunc signal_func,
                                             gpointer user_data,
                                             GDestroyNotify destroy);

Add a signal handler to the main loop.

Please note that unlike a normal unix signal handler (as provided by signal(2) or sigaction(2)), this handler will be run synchronously, so you can call non-reentrant methods.

Also, because unix signal delivery is unreliable, if the signal is raised a few times in rapid succession, you may miss some callbacks.

It is ok to connect multiple times to a single signal simulataneously.

gsk_main_loop_add_waitpid ()

GskSource*  gsk_main_loop_add_waitpid       (GskMainLoop *main_loop,
                                             int process_id,
                                             GskMainLoopWaitPidFunc waitpid_func,
                                             gpointer user_data,
                                             GDestroyNotify destroy);

Add a handler to trap process termination.

Only one handler is allowed per child process.

The handler will be invoked synchronously.

gsk_main_loop_add_io ()

GskSource*  gsk_main_loop_add_io            (GskMainLoop *main_loop,
                                             int fd,
                                             guint events,
                                             GskMainLoopIOFunc io_func,
                                             gpointer user_data,
                                             GDestroyNotify destroy);

Add a handler to input or output on a file-descriptor (a socket or a pipe, usually).

Only one handler trap is allowed per file-descriptor.

The handler will be re-invoked until the event subsides. For example, if you read only part of the data when a input event is raised, the io_func will be invoked again at every iteration of the main-loop until there is no data available.

gsk_source_adjust_io ()

void        gsk_source_adjust_io            (GskSource *source,
                                             guint events);

This changes the types of events being watched by the main-loop.

Note: each new file-descriptor needs a new GskSource. You must reuse this GskSource for a new file-descriptor even if it happens to have the same numeric value as a file-descriptor you closed. (The reason why: GSK automatically coagulates multiple adjust_io calls. This is fine with all main-loops. However, kqueue(2) on BSD, and possibly others, automatically unregister all interest in an event if the file-descriptor closes. Hence, if the file-descriptor is re-opened and re-used with the same GskSource, GSK will not be able to determine that anything has changed, and will not issue a new GskMainLoopChange. This will break main-loops that are sensitive to exact which file-descriptor (not just the number) was registered.)

gsk_source_remove_io_events ()

void        gsk_source_remove_io_events     (GskSource *source,
                                             guint events);

Cause this source to stop being notified if any of the events in the events parameter are set.

gsk_source_add_io_events ()

void        gsk_source_add_io_events        (GskSource *source,
                                             guint events);

Cause this source to be notified if any of the events in the events parameter are set, in addition to the events which already caused this source to be woken up.

gsk_main_loop_add_timer ()

GskSource*  gsk_main_loop_add_timer         (GskMainLoop *main_loop,
                                             GskMainLoopTimeoutFunc timer_func,
                                             gpointer timer_data,
                                             GDestroyNotify timer_destroy,
                                             gint64 millis_expire,
                                             gint64 milli_period);

Add a timeout function to the main-loop. This is a function that will be called after a fixed amount of time passes, and then may be called at a regular interval thereafter.

gsk_main_loop_add_timer_absolute ()

GskSource*  gsk_main_loop_add_timer_absolute
                                            (GskMainLoop *main_loop,
                                             GskMainLoopTimeoutFunc timer_func,
                                             gpointer timer_data,
                                             GDestroyNotify timer_destroy,
                                             int unixtime,
                                             int unixtime_micro);

Add a timeout function to the main-loop. The timer_func will be called as soon as we detect that the specified time has passed.

The time to wait until is (unixtime + unixtime_micro * 10^{-6}) seconds after New Years, Jan 1, 1970 GMT.

gsk_source_adjust_timer ()

void        gsk_source_adjust_timer         (GskSource *timer_source,
                                             gint64 millis_expire,
                                             gint64 milli_period);

Adjust the timeout and period for an already existing timer source. (You may only call this on timer sources.)

gsk_source_remove ()

void        gsk_source_remove               (GskSource *source);

Destroy a main loop's source.

If the source is currently running, it's destroy method will not be called until the source's callback returns. (This way, important data won't be deleted unexpectedly in the middle of the user's callback.)

gsk_main_loop_add_context ()

void        gsk_main_loop_add_context       (GskMainLoop *main_loop,
                                             GMainContext *context);

Indicate that a particular GskMainLoop will take care of invoking the necessary methods of context.

gsk_main_loop_quit ()

void        gsk_main_loop_quit              (GskMainLoop *main_loop);

Set the main-loop flag that indicates that it should really stop running.

If you are executing a GskMainLoop using gsk_main_loop_run(), then you should probably check gsk_main_loop_should_continue() at every iteration to ensure that you should not have quit by now.

gsk_main_loop_should_continue ()

gboolean    gsk_main_loop_should_continue   (GskMainLoop *main_loop);

Query whether the main-loop should keep running or not.

gsk_source_peek_main_loop ()

GskMainLoop* gsk_source_peek_main_loop      (GskSource *source);

Get the main-loop where the source was created.

gsk_main_loop_destroy_all_sources ()

void        gsk_main_loop_destroy_all_sources
                                            (GskMainLoop *main_loop);

gsk_main_loop_do_waitpid ()

gboolean    gsk_main_loop_do_waitpid        (int pid,
                                             GskMainLoopWaitInfo *wait_info);

Do a waitpid system call on the process and munge the data into wait_info for the caller to use.