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.

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.

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

exo_job_get_cancellable ()

GCancellable *      exo_job_get_cancellable             (const ExoJob *job);

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

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

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.

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.

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.

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

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

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.

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.

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.