## 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 thread that the job was started from, waiting for the result (and thus blocking the I/O job).

`job` : | a GIOSchedulerJob
`func` : | a GSourceFunc callback that will be called in the original 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 thread that the job was started from. 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 original thread
`user_data` : | data to pass to `func`
`notify` : | a GDestroyNotify for `user_data`, or `NULL`