GIOScheduler

GIOScheduler — I/O Scheduler

Synopsis


#include <gio/gio.h>

                    GIOSchedulerJob;
gboolean            (*GIOSchedulerJobFunc)              (GIOSchedulerJob *job,
                                                         GCancellable *cancellable,
                                                         gpointer user_data);
void                g_io_scheduler_push_job             (GIOSchedulerJobFunc job_func,
                                                         gpointer user_data,
                                                         GDestroyNotify notify,
                                                         gint io_priority,
                                                         GCancellable *cancellable);
void                g_io_scheduler_cancel_all_jobs      (void);
gboolean            g_io_scheduler_job_send_to_mainloop (GIOSchedulerJob *job,
                                                         GSourceFunc func,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);
void                g_io_scheduler_job_send_to_mainloop_async
                                                        (GIOSchedulerJob *job,
                                                         GSourceFunc func,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);

Description

Schedules asynchronous I/O operations. GIOScheduler integrates into the main event loop (GMainLoop) and may use threads if they are available.

Each I/O operation has a priority, and the scheduler uses the priorities to determine the order in which operations are executed. They are not used to determine system-wide I/O scheduling. Priorities are integers, with lower numbers indicating higher priority. It is recommended to choose priorities between G_PRIORITY_LOW and G_PRIORITY_HIGH, with G_PRIORITY_DEFAULT as a default.

Details

GIOSchedulerJob

typedef struct _GIOSchedulerJob GIOSchedulerJob;

Opaque class for definining and scheduling IO jobs.

GIOSchedulerJobFunc ()

gboolean            (*GIOSchedulerJobFunc)              (GIOSchedulerJob *job,
                                                         GCancellable *cancellable,
                                                         gpointer user_data);

I/O Job function.

Note that depending on whether threads are available, the GIOScheduler may run jobs in separate threads or in an idle in the mainloop.

Long-running jobs should periodically check the cancellable to see if they have been cancelled.

job : a GIOSchedulerJob.
cancellable : optional GCancellable object, NULL to ignore.
user_data : the data to pass to callback function
Returns : TRUE if this function should be called again to complete the job, FALSE if the job is complete (or cancelled)

g_io_scheduler_push_job ()

void                g_io_scheduler_push_job             (GIOSchedulerJobFunc job_func,
                                                         gpointer user_data,
                                                         GDestroyNotify notify,
                                                         gint io_priority,
                                                         GCancellable *cancellable);

Schedules the I/O job to run.

notify will be called on user_data after job_func has returned, regardless whether the job was cancelled or has run to completion.

If cancellable is not NULL, it can be used to cancel the I/O job by calling g_cancellable_cancel() or by calling g_io_scheduler_cancel_all_jobs().

job_func : a GIOSchedulerJobFunc.
user_data : data to pass to job_func
notify : a GDestroyNotify for user_data, or NULL
io_priority : the I/O priority of the request.
cancellable : optional GCancellable object, NULL to ignore.

g_io_scheduler_cancel_all_jobs ()

void                g_io_scheduler_cancel_all_jobs      (void);

Cancels all cancellable I/O jobs.

A job is cancellable if a GCancellable was passed into g_io_scheduler_push_job().

g_io_scheduler_job_send_to_mainloop ()

gboolean            g_io_scheduler_job_send_to_mainloop (GIOSchedulerJob *job,
                                                         GSourceFunc func,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);

Used from an I/O job to send a callback to be run in the main loop (main thread), waiting for the result (and thus blocking the I/O job).

job : a GIOSchedulerJob
func : a GSourceFunc callback that will be called in the main thread
user_data : data to pass to func
notify : a GDestroyNotify for user_data, or NULL
Returns : The return value of func

g_io_scheduler_job_send_to_mainloop_async ()

void                g_io_scheduler_job_send_to_mainloop_async
                                                        (GIOSchedulerJob *job,
                                                         GSourceFunc func,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);

Used from an I/O job to send a callback to be run asynchronously in the main loop (main thread). The callback will be run when the main loop is available, but at that time the I/O job might have finished. The return value from the callback is ignored.

Note that if you are passing the user_data from g_io_scheduler_push_job() on to this function you have to ensure that it is not freed before func is called, either by passing NULL as notify to g_io_scheduler_push_job() or by using refcounting for user_data.

job : a GIOSchedulerJob
func : a GSourceFunc callback that will be called in the main thread
user_data : data to pass to func
notify : a GDestroyNotify for user_data, or NULL