Transitions

digraph inheritance { rankdir=LR; GObject -> WpTransition; GInterface -> GAsyncResult; GAsyncResult -> WpTransition; WpTransition -> WpFeatureActivationTransition; }

struct WpTransition

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, _WpTransitionClass::get_next_step() is called in order to determine the next step to execute. Afterwards, _WpTransitionClass::execute_step() 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 _WpTransitionClass::execute_step() 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.

GObject Properties

completed

Whether the transition has completed, meaning its callback (if set) has been invoked. This can only happen after the final step has been reached or wp_transition_return_error()

has been called.

This property is guaranteed to change from FALSE to TRUE exactly once.

The GObject notify signal for this change is emitted in the same context as the transition’s callback, immediately after that callback is invoked.

gboolean

G_PARAM_READABLE

struct _WpTransitionClass

Public Members

GObjectClass parent_class
guint (*get_next_step)(WpTransition *transition, guint step)

See wp_transition_advance()

void (*execute_step)(WpTransition *transition, guint step)

See wp_transition_advance()

enum WpTransitionStep

Values for the steps of the implemented state machine.

Values:

enumerator WP_TRANSITION_STEP_NONE = 0

the initial and final step of the transition

enumerator WP_TRANSITION_STEP_ERROR

returned by _WpTransitionClass::get_next_step() in case of an error

enumerator WP_TRANSITION_STEP_CUSTOM_START = 0x10

starting value for steps defined in subclasses

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

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) (type GObject): 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

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) (type GObject): 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

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) (type GObject): the source object

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.

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

void 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

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

void 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

gboolean wp_transition_get_completed(WpTransition *self)

Checks if the transition completed.

Parameters

  • self – the transition

Returns

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

gboolean wp_transition_had_error(WpTransition *self)

Checks if the transition completed with an error.

Parameters

  • self – the transition

Returns

TRUE if the transition completed with an error, FALSE otherwise

void wp_transition_advance(WpTransition *self)

Advances the transition to the next step.

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

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

When _WpTransitionClass::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 _WpTransitionClass::get_next_step() returns WP_TRANSITION_STEP_ERROR, this function calls wp_transition_return_error(), unless it has already been called directly by _WpTransitionClass::get_next_step().

In error conditions, _WpTransitionClass::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

void 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

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

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

Returns the final return status of the transition and its error, if there was one.

This is meant to be called from within the GAsyncReadyCallback that was specified in wp_transition_new().

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

WP_TYPE_TRANSITION (wp_transition_get_type ())

The WpTransition GType.

struct WpFeatureActivationTransition

A WpTransition that is used by WpObject to implement feature activation.

WpObjectFeatures wp_feature_activation_transition_get_requested_features(WpFeatureActivationTransition *self)

Gets the features requested to be activated in this transition.

Parameters

  • self – the transition

Returns

the features that were requested to be activated in this transition; this contains the features as they were passed in wp_object_activate() and therefore it may contain unsupported or already active features

WP_TYPE_FEATURE_ACTIVATION_TRANSITION     (wp_feature_activation_transition_get_type ())

The WpFeatureActivationTransition GType.