ExoJob

ExoJob — Base class for threaded/asynchronous jobs

Functions

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,
               gchar   *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,
               gdouble  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