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)
–
Class structure
WpTransitionClass
Fields
parent_class
(GObjectClass)
–
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
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
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
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
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
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
the transition's source tag
wp_transition_had_error
gboolean wp_transition_had_error (WpTransition * self)
Parameters:
self
–
the transition
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
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
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)
Parameters:
transition
–
step
–
get_next_step
guint get_next_step (WpTransition * transition, guint step)
Parameters:
transition
–
step
–
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
The results of the search are