GsdAsyncOperation

GsdAsyncOperation — An asynchronous process spawner, with support for progression and success report.

Functions

Properties

gboolean busy Read
gchar * path Read / Write

Signals

Types and Values

Object Hierarchy

    GObject
    ╰── GsdAsyncOperation
        ╰── GsdSecureDeleteOperation

Description

This is a base class designed to be subclassed by actual spawners, with as less efforts as possible.

To subclass this class, the only thing you need to implement is the argument builder, that gives the arguments of the spawned command; and you need to set the AsyncOperation::path property to the command to spawn in your constructor too (hence it is not required, it is slightly better to set it since it must be set before calling run() or run_sync() - or getting it). This said, you may want to override get_max_progress() and get_progress() to add actual progress support; and build_env() to provide a specific environment to your command.

Important note

As this class uses a timeout function to watch the child, you need a GLib MainLoop for the watching process to work for the asynchronous method.

Simple usage of an hypothetical FooOperation subclass

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
var foo = new FooOperation();

// Connect the finish callback
foo.finished.connect ((success, error) => {
                        if (success) {
                          stdout.printf ("success!\n");
                        } else {
                          stderr.printf ("failure: %s\n", error);
                        }
                      });
// and the progress callback
foo.progress.connect ((progress) => {
                        stdout.printf ("\r%.0f%%", progress * 100);
                      });
foo.run ();

var loop = GLib.MainLoop (null, false);
loop.run ();

Functions

gsd_async_operation_cancel ()

gboolean
gsd_async_operation_cancel (GsdAsyncOperation *self);

Tries to cancel the operation.

Parameters

self

the GsdAsyncOperation instance

 

Returns

true if successfully canceled, false otherwise.


gsd_async_operation_pause ()

gboolean
gsd_async_operation_pause (GsdAsyncOperation *self);

Tries to pause the operation.

Parameters

self

the GsdAsyncOperation instance

 

Returns

true if successfully paused, false otherwise.


gsd_async_operation_resume ()

gboolean
gsd_async_operation_resume (GsdAsyncOperation *self);

Tries to resume the operation.

Parameters

self

the GsdAsyncOperation instance

 

Returns

true if successfully resumed, false otherwise.


gsd_async_operation_run ()

gboolean
gsd_async_operation_run (GsdAsyncOperation *self,
                         const gchar *working_directory,
                         GSpawnFlags spawn_flags,
                         GError **error);

Launches an operation asynchronously.

Parameters

self

the GsdAsyncOperation instance

 

working_directory

 .

the working directory of the child process, or null to use the parent's one.

.

[in][allow-none]

spawn_flags

 .

SpawnFlags. You may only use the SEARCH_PATH and CHILD_INHERITS_STDIN flags, others may conflict.

.

[in]

error

location to store the error occuring, or NULL to ignore.

[error-domains GSpawnError GsdAsyncOperationError]

Returns

whether asynchronous operation was successfully started.


gsd_async_operation_run_sync ()

gboolean
gsd_async_operation_run_sync (GsdAsyncOperation *self,
                              const gchar *working_directory,
                              GSpawnFlags spawn_flags,
                              gchar **standard_output,
                              GError **error);

Launches an operation synchronously.

Parameters

self

the GsdAsyncOperation instance

 

working_directory

 .

the working directory of the child process, or null to use the parent's one.

.

[in][allow-none]

spawn_flags

 .

SpawnFlags. You may only use the SEARCH_PATH and CHILD_INHERITS_STDIN flags, others may conflict.

.

[in]

standard_output

 .

return location for the subprocess' standard output, or null to ignore it.

.

[out]

error

location to store the error occuring, or NULL to ignore.

[error-domains GSpawnError GsdAsyncOperationError]

Returns

true if all worked properly, and false if something failed. An error is thrown if something fails. It can be the subprocess spawning (SpawnError) or the child that failed (AsyncOperationError.CHILD_FAILED).


gsd_async_operation_get_path ()

const gchar *
gsd_async_operation_get_path (GsdAsyncOperation *self);

Get and return the current value of the "path" property.

The path to the command to spawn.

Setting it to null resets it to its default value.

Parameters

self

the GsdAsyncOperation instance to query

 

Returns

the value of the "path" property


gsd_async_operation_set_path ()

void
gsd_async_operation_set_path (GsdAsyncOperation *self,
                              const gchar *value);

Set the value of the "path" property to value .

The path to the command to spawn.

Setting it to null resets it to its default value.

Parameters

self

the GsdAsyncOperation instance to modify

 

value

the new value of the "path" property

 

gsd_async_operation_get_busy ()

gboolean
gsd_async_operation_get_busy (GsdAsyncOperation *self);

Get and return the current value of the "busy" property.

Whether the operation object is busy.

A busy operation cannot be reused until it gets ready again. An operation is busy when it is currently doing a job.

Parameters

self

the GsdAsyncOperation instance to query

 

Returns

the value of the "busy" property

Types and Values

GSD_TYPE_ASYNC_OPERATION

#define GSD_TYPE_ASYNC_OPERATION (gsd_async_operation_get_type ())

The type for GsdAsyncOperation.


struct GsdAsyncOperation

struct GsdAsyncOperation;

An asynchronous process spawner, with support for progression and success report.

This is a base class designed to be subclassed by actual spawners, with as less efforts as possible.

To subclass this class, the only thing you need to implement is the argument builder, that gives the arguments of the spawned command; and you need to set the AsyncOperation::path property to the command to spawn in your constructor too (hence it is not required, it is slightly better to set it since it must be set before calling run() or run_sync() - or getting it). This said, you may want to override get_max_progress() and get_progress() to add actual progress support; and build_env() to provide a specific environment to your command.

Important note

As this class uses a timeout function to watch the child, you need a GLib MainLoop for the watching process to work for the asynchronous method.

Simple usage of an hypothetical FooOperation subclass

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
var foo = new FooOperation();

// Connect the finish callback
foo.finished.connect ((success, error) => {
                        if (success) {
                          stdout.printf ("success!\n");
                        } else {
                          stderr.printf ("failure: %s\n", error);
                        }
                      });
// and the progress callback
foo.progress.connect ((progress) => {
                        stdout.printf ("\r%.0f%%", progress * 100);
                      });
foo.run ();

var loop = GLib.MainLoop (null, false);
loop.run ();


struct GsdAsyncOperationClass

struct GsdAsyncOperationClass {
	GObjectClass parent_class;
	GList* (*build_args) (GsdAsyncOperation* self, GError** error);
	gchar** (*build_env) (GsdAsyncOperation* self, int* result_length1);
	void (*cleanup) (GsdAsyncOperation* self);
	guint (*get_max_progress) (GsdAsyncOperation* self);
	guint (*get_progress) (GsdAsyncOperation* self);
	gchar* (*get_subprocess_error_msg) (GsdAsyncOperation* self);
	GsdAsyncOperationExitStatus (*classify_exit_status) (GsdAsyncOperation* self, gint exit_status);
};

The class structure for GSD_TYPE_ASYNC_OPERATION. All the fields in this structure are private and should never be accessed directly.

Members

build_args ()

virtual method used internally

 

build_env ()

virtual method used internally

 

cleanup ()

virtual method used internally

 

get_max_progress ()

virtual method used internally

 

get_progress ()

virtual method used internally

 

get_subprocess_error_msg ()

virtual method used internally

 

classify_exit_status ()

virtual method used internally

 

enum GsdAsyncOperationError

Error domain for the AsyncOperation class.

Members

GSD_ASYNC_OPERATION_ERROR_CHILD_FAILED

The subprocess crashed or terminated with an error.

 

GSD_ASYNC_OPERATION_ERROR_SUBCLASS_ERROR

Other error from a subclass of AsyncOperation.

This is used as a workaround for the lack of error subclassing, disallowing to manage "generic" errors cleanly.

 

Property Details

The “busy” property

  “busy”                     gboolean

Whether the operation object is busy.

A busy operation cannot be reused until it gets ready again. An operation is busy when it is currently doing a job.

Flags: Read

Default value: FALSE


The “path” property

  “path”                     gchar *

The path to the command to spawn.

Setting it to null resets it to its default value.

Flags: Read / Write

Default value: NULL

Signal Details

The “finished” signal

void
user_function (GsdAsyncOperation *async_operation,
               gboolean           success,
               gchar             *message,
               gpointer           user_data)

This signal is emitted when the operation just terminated.

Parameters

async_operation

the GsdAsyncOperation instance that received the signal

 

success

 .

whether the operation succeed.

 

message

 .

any error or warning message.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “progress” signal

void
user_function (GsdAsyncOperation *async_operation,
               gdouble            fraction,
               gpointer           user_data)

This signal is emitted when the progress status of the operation changes.

Parameters

async_operation

the GsdAsyncOperation instance that received the signal

 

fraction

 .

the current progress, from 0.0 to 1.0.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last