ExoJob

## ExoJob ExoJob — Base class for threaded/asynchronous jobs |

## Synopsis

    #include <exo/exo.h>

                        ExoJob;
    ExoJob *            exo_job_launch                      (ExoJob *job);
    void                exo_job_cancel                      (ExoJob *job);
    gboolean            exo_job_is_cancelled                (const ExoJob *job);
    GCancellable *      exo_job_get_cancellable             (const ExoJob *job);
    gboolean            exo_job_set_error_if_cancelled      (ExoJob *job,
                                                             GError **error);
    void                exo_job_emit                        (ExoJob *job,
                                                             guint signal_id,
                                                             GQuark signal_detail,
                                                             ...);
    void                exo_job_info_message                (ExoJob *job,
                                                             const gchar *format,
                                                             ...);
    void                exo_job_percent                     (ExoJob *job,
                                                             gdouble percent);
    gboolean            exo_job_send_to_mainloop            (ExoJob *job,
                                                             GSourceFunc func,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy_notify);

## Object Hierarchy

      GObject
       +----ExoJob
             +----ExoSimpleJob

## Signals

      "error"                                          : No Hooks
      "finished"                                       : No Hooks
      "info-message"                                   : No Hooks
      "percent"                                        : No Hooks

## Description

ExoJob is an abstract base class intended to wrap threaded/asynchronous operations (called jobs here). It was written because the ways of dealing with threads provided by GLib are not exactly object-oriented.

It can be used to wrap any kind of long-running or possibly-blocking operation like file operations or communication with web services. The benefit of using ExoJob is that one gets an object associated with each operation. After creating the job the caller can connect to signals like "error" or "percent". This design integrates very well with the usual object-oriented design of applications based on GObject.

## Details

### ExoJob

    typedef struct _ExoJob ExoJob;

The ExoJob struct contains only private fields and should not be directly accessed.

### exo_job_launch ()

    ExoJob *            exo_job_launch                      (ExoJob *job);

This functions schedules the `job` to be run as soon as possible, in a separate thread. The caller can connect to signals of the `job` prior or after this call in order to be notified on errors, progress updates and the end of the operation.

`job` : | an ExoJob.
Returns : | the `job` itself.

### exo_job_cancel ()

    void                exo_job_cancel                      (ExoJob *job);

Attempts to cancel the operation currently performed by `job`. Even after the cancellation of `job`, it may still emit signals, so you must take care of disconnecting all handlers appropriately if you cannot handle signals after cancellation.

Calling this function when the `job` has not been launched yet or when it has already finished will have no effect.

`job` : | a ExoJob.

### exo_job_is_cancelled ()

    gboolean            exo_job_is_cancelled                (const ExoJob *job);

Checks whether `job` was previously cancelled by a call to `exo_job_cancel()`.

`job` : | a ExoJob.
Returns : | `TRUE` if `job` is cancelled.

### exo_job_get_cancellable ()

    GCancellable *      exo_job_get_cancellable             (const ExoJob *job);

Returns the GCancellable that can be used to cancel the `job`.

`job` : | an ExoJob.
Returns : | the GCancellable associated with the `job`. It is owned by the `job` and must not be released.

### exo_job_set_error_if_cancelled ()

    gboolean            exo_job_set_error_if_cancelled      (ExoJob *job,
                                                             GError **error);

Sets the `error` if the `job` was cancelled. This is a convenience function that is equivalent to

    GCancellable *cancellable;
    cancellable = exo_job_get_cancllable (job);
    g_cancellable_set_error_if_cancelled (cancellable, error);

`job` : | an ExoJob.
`error` : | error to be set if the `job` was cancelled.
Returns : | `TRUE` if the job was cancelled and `error` is now set, `FALSE` otherwise.

### exo_job_emit ()

    void                exo_job_emit                        (ExoJob *job,
                                                             guint signal_id,
                                                             GQuark signal_detail,
                                                             ...);

Sends the signal with `signal_id` and `signal_detail` to the application's main loop and waits for listeners to handle it.

`job` : | an ExoJob.
`signal_id` : | the signal id.
`signal_detail` : | the signal detail.
`...` : | a list of parameters to be passed to the signal, followed by a location for the return value. If the return type of the signal is G_TYPE_NONE, the return value location can be omitted.

### exo_job_info_message ()

    void                exo_job_info_message                (ExoJob *job,
                                                             const gchar *format,
                                                             ...);

Generates and emits an "info-message" signal and sends it to the application's main loop.

`job` : | an ExoJob.
`format` : | a format string.
`...` : | parameters for the format string.

### exo_job_percent ()

    void                exo_job_percent                     (ExoJob *job,
                                                             gdouble percent);

Emits a "percent" signal and sends it to the application's main loop. Also makes sure that `percent` is between 0.0 and 100.0.

`job` : | an ExoJob.
`percent` : | percentage of completeness of the operation.

### exo_job_send_to_mainloop ()

    gboolean            exo_job_send_to_mainloop            (ExoJob *job,
                                                             GSourceFunc func,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy_notify);

This functions schedules `func` to be run in the main loop (main thread), waiting for the result (and blocking the job in the meantime).

`job` : | an ExoJob.
`func` : | a GSourceFunc callback that will be called in the main thread.
`user_data` : | data to pass to `func`.
`destroy_notify` : | a GDestroyNotify for `user_data`, or `NULL`.
Returns : | The return value of `func`.

## Signal Details

### The `"error"` signal

    void                user_function                      (ExoJob  *job,
                                                            gpointer error,
                                                            gpointer user_data)      : No Hooks

Emitted whenever an error occurs while executing the `job`. This signal may not be emitted from within ExoJob subclasses. If a subclass wants to emit an "error" signal (and thereby terminate the operation), it has to fill the GError structure and abort from its `execute()` method. ExoJob will automatically emit the "error" signal when the GError is filled after the `execute()` method has finished.

Callers interested in whether the `job` was cancelled can connect to the "cancelled" signal of the GCancellable returned from `exo_job_get_cancellable()`.

`job` : | an ExoJob.
`error` : | a GError describing the cause.
`user_data` : | user data set when the signal handler was connected.

### The `"finished"` signal

    void                user_function                      (ExoJob  *job,
                                                            gpointer user_data)      : No Hooks

This signal will be automatically emitted once the `job` finishes its execution, no matter whether `job` completed successfully or was cancelled by the user. It may not be emitted by subclasses of ExoJob as it is automatically emitted by ExoJob after the `execute()` method has finished.

`job` : | an ExoJob.
`user_data` : | user data set when the signal handler was connected.

### The `"info-message"` signal

    void                user_function                      (ExoJob  *job,
                                                            gchar   *message,
                                                            gpointer user_data)      : No Hooks

This signal is emitted to display information about the status of the `job`. Examples of messages are "Preparing..." or "Cleaning up...".

The `message` is garanteed to contain valid UTF-8, so it can be displayed by GtkWidgets out of the box.

`job` : | an ExoJob.
`message` : | information to be displayed about `job`.
`user_data` : | user data set when the signal handler was connected.

### The `"percent"` signal

    void                user_function                      (ExoJob  *job,
                                                            gdouble  percent,
                                                            gpointer user_data)      : No Hooks

This signal is emitted to present the overall progress of the operation. The `percent` value is garantied to be a value between 0.0 and 100.0.

`job` : | an ExoJob.
`percent` : | the percentage of completeness.
`user_data` : | user data set when the signal handler was connected.

## See Also

ExoSimpleJob