Transitions

A transition is an asynchronous operation, like GTask, that contains an internal state machine, where a series of 'steps' are executed in order to complete the operation.

For every step, () is called in order to determine the next step to execute. Afterwards, () is called to perform any actions necessary to complete this step. When execution of the step is done, the operation's code must call wp_transition_advance in order to continue to the next step. If an error occurs, the operation's code must call wp_transition_return_error instead, in which case the transition completes immediately and wp_transition_had_error returns TRUE.

Typically, every step will start an asynchronous operation. Although is is possible, the WpTransition base class does not expect () to call wp_transition_advance directly. Instead, it is expected that wp_transition_advance will be called from the callback that the step's asyncrhonous operation will call when it is completed.

WpTransition

GObject
    ╰──WpTransition
        ╰──WpFeatureActivationTransition

Members

parent_instance (GObject) –
No description available

Class structure

WpTransitionClass

Fields
parent_class (GObjectClass) –
No description available

Constructors

wp_transition_new

WpTransition *
wp_transition_new (GType type,
                   gpointer source_object,
                   GCancellable* cancellable,
                   GAsyncReadyCallback callback,
                   gpointer callback_data)

Creates a WpTransition acting on source_object. When the transition is done, callback will be invoked.

The transition does not automatically start executing steps. You must call wp_transition_advance after creating it in order to start it.

Note that the transition is automatically unref'ed after the callback has been executed. If you wish to keep an additional reference on it, you need to ref it explicitly.

Parameters:

type

the GType of the WpTransition subclass to instantiate

source_object ( [nullable][typeGObject])

the GObject that owns this task, or NULL

cancellable ( [nullable])

optional GCancellable

callback ( [scope async])

a GAsyncReadyCallback

callback_data ( [closure])

user data passed to callback

Returns ( [transfer: none])

the new transition


wp_transition_new_closure

WpTransition *
wp_transition_new_closure (GType type,
                           gpointer source_object,
                           GCancellable* cancellable,
                           GClosure* closure)

Creates a WpTransition acting on source_object. When the transition is done, closure will be invoked.

The transition does not automatically start executing steps. You must call wp_transition_advance after creating it in order to start it.

Note that the transition is automatically unref'ed after the closure has been executed. If you wish to keep an additional reference on it, you need to ref it explicitly.

Parameters:

type

the GType of the WpTransition subclass to instantiate

source_object ( [nullable][typeGObject])

the GObject that owns this task, or NULL

cancellable ( [nullable])

optional GCancellable

closure ( [nullable])

a GAsyncReadyCallback wrapped in a GClosure

Returns ( [transfer: none])

the new transition


Methods

wp_transition_advance

wp_transition_advance (WpTransition * self)

Advances the transition to the next step.

This initially calls get_next_step() in order to determine what the next step is. If get_next_step() returns a step different than the previous one, it calls execute_step() to execute it.

The very first time that get_next_step() is called, its step parameter equals WP_TRANSITION_STEP_NONE.

When get_next_step() returns WP_TRANSITION_STEP_NONE, this function completes the transition, calling the transition's callback and then unref-ing the transition.

When get_next_step() returns WP_TRANSITION_STEP_ERROR, this function calls wp_transition_return_error, unless it has already been called directly by get_next_step().

In error conditions, execute_step() is called once with step being WP_TRANSITION_STEP_ERROR, allowing the implementation to rollback any changes or cancel underlying jobs, if necessary.

Parameters:

self

the transition


wp_transition_get_completed

gboolean
wp_transition_get_completed (WpTransition * self)

Parameters:

self

the transition

Returns

TRUE if the transition has completed (with or without an error), FALSE otherwise


wp_transition_get_data

gpointer
wp_transition_get_data (WpTransition * self)

Gets self 's data. See wp_transition_set_data.

Parameters:

self

the transition

Returns ( [transfer: none])

the transition's data


wp_transition_get_source_object

gpointer
wp_transition_get_source_object (WpTransition * self)

Gets the source object from the transition. Like g_async_result_get_source_object, but does not ref the object.

Parameters:

self

the transition

Returns ( [transfer: none][typeGObject])

the source object


wp_transition_get_source_tag

gpointer
wp_transition_get_source_tag (WpTransition * self)

Gets self 's source tag. See wp_transition_set_source_tag.

Parameters:

self

the transition

Returns ( [transfer: none])

the transition's source tag


wp_transition_had_error

gboolean
wp_transition_had_error (WpTransition * self)

Parameters:

self

the transition

Returns

TRUE if the transition completed with an error, FALSE otherwise


wp_transition_is_tagged

gboolean
wp_transition_is_tagged (WpTransition * self,
                         gpointer tag)

Checks if self has the given tag (generally a function pointer indicating the function self was created by).

Parameters:

self

the transition

tag

a tag

Returns

TRUE if self has the indicated tag , FALSE if not.


wp_transition_return_error

wp_transition_return_error (WpTransition * self,
                            GError* error)

Completes the transition with an error. This can be called anytime from within any virtual function or an async job handler.

Note that in most cases this will also unref the transition, so it is not safe to access it after this function has been called.

Parameters:

self

the transition

error ( [transfer: full])

a GError


wp_transition_set_data

wp_transition_set_data (WpTransition * self,
                        gpointer data,
                        GDestroyNotify data_destroy)

Sets self 's data (freeing the existing data, if any). This can be an arbitrary user structure that holds data associated with this transition.

Parameters:

self

the transition

data ( [nullable])

transition-specific user data

data_destroy ( [nullable])

GDestroyNotify for data


wp_transition_set_source_tag

wp_transition_set_source_tag (WpTransition * self,
                              gpointer tag)

Sets self 's source tag. You can use this to tag a transition's return value with a particular pointer (usually a pointer to the function doing the tagging) and then later check it using wp_transition_get_source_tag (or g_async_result_is_tagged) in the transition's "finish" function, to figure out if the response came from a particular place.

Parameters:

self

the transition

tag

an opaque pointer indicating the source of this transition


Functions

wp_transition_finish

gboolean
wp_transition_finish (GAsyncResult* res,
                      GError** error)

This is meant to be called from within the GAsyncReadyCallback that was specified in wp_transition_new. It returns the final return status of the transition and its error, if there was one.

Parameters:

res

a transition, as a GAsyncResult

error ( [out][optional])

a location to return the transition's error, if any

Returns

TRUE if the transition completed successfully, FALSE if there was an error


Properties

completed

“completed” gboolean

Flags : Read


Virtual Methods

execute_step

execute_step (WpTransition * transition,
              guint step)

See wp_transition_advance

Parameters:

transition
No description available
step
No description available

get_next_step

guint
get_next_step (WpTransition * transition,
               guint step)

See wp_transition_advance

Parameters:

transition
No description available
step
No description available
Returns
No description available

Enumerations

WpTransitionStep

Members
WP_TRANSITION_STEP_NONE (0) –

the initial and final step of the transition

WP_TRANSITION_STEP_ERROR (1) –

returned by get_next_step() in case of an error

WP_TRANSITION_STEP_CUSTOM_START (16) –

starting value for steps defined in subclasses


Constants

WP_TYPE_TRANSITION

#define WP_TYPE_TRANSITION (wp_transition_get_type ())

The WpTransition GType


The results of the search are