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

1
2
3
4
5
6