ExoJob: exo Reference Manual

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

## Functions

ExoJob * | exo_job_launch ()
void | exo_job_cancel ()
gboolean | exo_job_is_cancelled ()
GCancellable * | exo_job_get_cancellable ()
gboolean | exo_job_set_error_if_cancelled ()
void | exo_job_emit ()
void | exo_job_info_message ()
void | exo_job_percent ()
gboolean | exo_job_send_to_mainloop ()

## Signals

void | error | No Hooks
void | finished | No Hooks
void | info-message | No Hooks
void | percent | No Hooks

## Types and Values

struct | ExoJob

## Object Hierarchy

        GObject
        ╰── ExoJob
            ╰── ExoSimpleJob

## Includes

    #include <exo/exo.h>

## 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.

## Functions

### 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.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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` .

#### Parameters

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

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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).

#### Parameters

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` .

## Types and Values

### struct ExoJob

    struct ExoJob;

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

## Signal Details

### The `“error”` signal

    void
    user_function (ExoJob  *job,
                   gpointer error,
                   gpointer user_data)

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()`.

#### Parameters

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

Flags: No Hooks

### The `“finished”` signal

    void
    user_function (ExoJob  *job,
                   gpointer user_data)

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.

#### Parameters

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

Flags: No Hooks

### The `“info-message”` signal

    void
    user_function (ExoJob  *job,
                   char    *message,
                   gpointer user_data)

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.

#### Parameters

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

Flags: No Hooks

### The `“percent”` signal

    void
    user_function (ExoJob  *job,
                   double   percent,
                   gpointer user_data)

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.

#### Parameters

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

Flags: No Hooks

## See Also

ExoSimpleJob