Debian Codegraph @

lib/wp/transition.c

raw
1 /* WirePlumber
2 *
3 * Copyright © 2020 Collabora Ltd.
4 * @author George Kiagiadakis <[email protected]>
5 *
6 * SPDX-License-Identifier: MIT
7 */
8
9 #include "transition.h"
10 #include "log.h"
11 #include "error.h"
12
13 WP_DEFINE_LOCAL_LOG_TOPIC ("wp-transition")
14
15 /*! \defgroup wptransition Transitions */
16 /*!
17 * \struct WpTransition
18 *
19 * A transition is an asynchronous operation, like GTask, that contains an
20 * internal state machine, where a series of 'steps' are executed in order to
21 * complete the operation.
22 *
23 * For every step, _WpTransitionClass::get_next_step()
24 * is called in order to determine the next step to execute. Afterwards,
25 * _WpTransitionClass::execute_step() is called
26 * to perform any actions necessary to complete this step. When execution
27 * of the step is done, the operation's code must call wp_transition_advance()
28 * in order to continue to the next step. If an error occurs, the operation's
29 * code must call wp_transition_return_error() instead, in which case the
30 * transition completes immediately and wp_transition_had_error() returns TRUE.
31 *
32 * Typically, every step will start an asynchronous operation. Although it is
33 * possible, the WpTransition base class does not expect
34 * _WpTransitionClass::execute_step() to call wp_transition_advance() directly.
35 * Instead, it is expected that wp_transition_advance() will be called from
36 * the callback that the step's asynchronous operation will call when it is
37 * completed.
38 *
39 * \gproperties
40
41 * \gproperty{completed, gboolean, G_PARAM_READABLE,
42 * Whether the transition has completed\, meaning its callback (if set)
43 * has been invoked. This can only happen after the final step has been
44 * reached or wp_transition_return_error() has been called.
45 * \n
46 * This property is guaranteed to change from FALSE to TRUE exactly once.
47 * \n
48 * The GObject \c notify signal for this change is emitted in the same context
49 * as the transition’s callback\, immediately after that callback is invoked.}
50 */
51
52 typedef struct _WpTransitionPrivate WpTransitionPrivate;
53 struct _WpTransitionPrivate
54 {
55 /* source obj & callback */
56 GObject *source_object;
57 GCancellable *cancellable;
58 GClosure *closure;
59
60 /* GAsyncResult tag */
61 gpointer tag;
62
63 /* task data */
64 gpointer data;
65 GDestroyNotify data_destroy;
66
67 /* state machine */
68 gboolean started;
69 gboolean completed;
70 gboolean finished;
71 guint step;
72 GError *error;
73 };
74
75 enum {
76 PROP_0,
77 PROP_COMPLETED,
78 };
79
80 static void wp_transition_async_result_init (GAsyncResultIface *iface);
81
82 G_DEFINE_ABSTRACT_TYPE_WITH_CODE (WpTransition, wp_transition, G_TYPE_OBJECT,
83 G_IMPLEMENT_INTERFACE (G_TYPE_ASYNC_RESULT, wp_transition_async_result_init)
84 G_ADD_PRIVATE (WpTransition))
85
86 static void
87 wp_transition_init (WpTransition * self)
88 {
89 }
90
91 static void
92 wp_transition_finalize (GObject * object)
93 {
94 WpTransition * self = WP_TRANSITION (object);
95 WpTransitionPrivate *priv = wp_transition_get_instance_private (self);
96
97 if (priv->data && priv->data_destroy)
98 priv->data_destroy (priv->data);
99
100 g_clear_error (&priv->error);
101 g_clear_pointer (&priv->closure, g_closure_unref);
102 g_clear_object (&priv->cancellable);
103 g_clear_object (&priv->source_object);
104
105 G_OBJECT_CLASS (wp_transition_parent_class)->finalize (object);
106 }
107
108 static void
109 wp_transition_get_property (GObject * object, guint property_id,
110 GValue * value, GParamSpec * pspec)
111 {
112 WpTransition * self = WP_TRANSITION (object);
113
114 switch (property_id) {
115 case PROP_COMPLETED:
116 g_value_set_boolean (value, wp_transition_get_completed (self));
117 break;
118 default:
119 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
120 break;
121 }
122 }
123
124 static void
125 wp_transition_class_init (WpTransitionClass * klass)
126 {
127 GObjectClass *object_class = (GObjectClass *) klass;
128
129 object_class->finalize = wp_transition_finalize;
130 object_class->get_property = wp_transition_get_property;
131
132 g_object_class_install_property (object_class, PROP_COMPLETED,
133 g_param_spec_boolean ("completed", "completed",
134 "Whether the transition has completed", FALSE,
135 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
136 }
137
138 static GObject *
139 get_source_object (GAsyncResult * res)
140 {
141 WpTransitionPrivate *priv =
142 wp_transition_get_instance_private (WP_TRANSITION (res));
143 return priv->source_object ? g_object_ref (priv->source_object) : NULL;
144 }
145
146 static void
147 wp_transition_async_result_init (GAsyncResultIface * iface)
148 {
149 iface->get_source_object = get_source_object;
150 iface->get_user_data =
151 (gpointer (*)(GAsyncResult *)) wp_transition_get_data;
152 iface->is_tagged =
153 (gboolean (*)(GAsyncResult *, gpointer)) wp_transition_is_tagged;
154 }
155
156 /*!
157 * \brief Creates a WpTransition acting on \a source_object.
158 *
159 * When the transition is done, \a callback will be invoked.
160 *
161 * The transition does not automatically start executing steps. You must
162 * call wp_transition_advance() after creating it in order to start it.
163 *
164 * \note The transition is automatically unref'ed after the \a callback
165 * has been executed. If you wish to keep an additional reference on it,
166 * you need to ref it explicitly.
167 *
168 * \ingroup wptransition
169 * \param type the GType of the WpTransition subclass to instantiate
170 * \param source_object (nullable) (type GObject): the GObject that owns this
171 * task, or NULL
172 * \param cancellable (nullable): optional GCancellable
173 * \param callback (scope async)(closure callback_data): a GAsyncReadyCallback
174 * \param callback_data user data passed to \a callback
175 * \returns (transfer none): the new transition
176 */
177 WpTransition *
178 wp_transition_new (GType type,
179 gpointer source_object, GCancellable * cancellable,
180 GAsyncReadyCallback callback, gpointer callback_data)
181 {
182 return wp_transition_new_closure (type, source_object, cancellable,
183 g_cclosure_new (G_CALLBACK (callback), callback_data, NULL));
184 }
185
186 /*!
187 * \brief Creates a WpTransition acting on \a source_object.
188 * When the transition is done, \a closure will be invoked.
189 *
190 * The transition does not automatically start executing steps. You must
191 * call wp_transition_advance() after creating it in order to start it.
192 *
193 * Note that the transition is automatically unref'ed after the \a closure
194 * has been executed. If you wish to keep an additional reference on it,
195 * you need to ref it explicitly.
196 *
197 * \ingroup wptransition
198 * \param type the GType of the WpTransition subclass to instantiate
199 * \param source_object (nullable) (type GObject): the GObject that owns this
200 * task, or NULL
201 * \param cancellable (nullable): optional GCancellable
202 * \param closure (nullable): a GAsyncReadyCallback wrapped in a GClosure
203 * \returns (transfer none): the new transition
204 */
205 WpTransition *
206 wp_transition_new_closure (GType type, gpointer source_object,
207 GCancellable * cancellable, GClosure * closure)
208 {
209 g_return_val_if_fail (g_type_is_a (type, WP_TYPE_TRANSITION), NULL);
210 g_return_val_if_fail (G_IS_OBJECT (source_object), NULL);
211
212 WpTransition *self = g_object_new (type, NULL);
213 WpTransitionPrivate *priv = wp_transition_get_instance_private (self);
214
215 priv->source_object = source_object ? g_object_ref (source_object) : NULL;
216 priv->cancellable = cancellable ? g_object_ref (cancellable) : NULL;
217
218 if (closure) {
219 priv->closure = g_closure_ref (closure);
220 g_closure_sink (closure);
221 if (G_CLOSURE_NEEDS_MARSHAL (closure))
222 g_closure_set_marshal (closure, g_cclosure_marshal_VOID__OBJECT);
223 }
224
225 return self;
226 }
227
228 /*!
229 * \brief Gets the source object from the transition.
230 *
231 * Like g_async_result_get_source_object(), but does not ref the object.
232 *
233 * \ingroup wptransition
234 * \param self the transition
235 * \returns (transfer none) (type GObject): the source object
236 */
237 gpointer
238 wp_transition_get_source_object (WpTransition * self)
239 {
240 g_return_val_if_fail (WP_IS_TRANSITION (self), NULL);
241
242 WpTransitionPrivate *priv = wp_transition_get_instance_private (self);
243 return priv->source_object;
244 }
245
246 /*!
247 * \brief Checks if \a self has the given \a tag (generally a function pointer
248 * indicating the function \a self was created by).
249 *
250 * \ingroup wptransition
251 * \param self the transition
252 * \param tag a tag
253 * \returns TRUE if \a self has the indicated \a tag , FALSE if not.
254 */
255 gboolean
256 wp_transition_is_tagged (WpTransition * self, gpointer tag)
257 {
258 g_return_val_if_fail (WP_IS_TRANSITION (self), FALSE);
259
260 WpTransitionPrivate *priv = wp_transition_get_instance_private (self);
261 return (priv->tag == tag);
262 }
263
264 /*!
265 * \brief Gets \a self 's source tag.
266 * \see wp_transition_set_source_tag().
267 * \ingroup wptransition
268 * \param self the transition
269 * \returns (transfer none): the transition's source tag
270 */
271 gpointer
272 wp_transition_get_source_tag (WpTransition * self)
273 {
274 g_return_val_if_fail (WP_IS_TRANSITION (self), NULL);
275
276 WpTransitionPrivate *priv = wp_transition_get_instance_private (self);
277 return priv->tag;
278 }
279
280 /*!
281 * \brief Sets \a self 's source tag.
282 *
283 * You can use this to tag a transition's return
284 * value with a particular pointer (usually a pointer to the function doing
285 * the tagging) and then later check it using wp_transition_get_source_tag()
286 * (or g_async_result_is_tagged()) in the transition's "finish" function,
287 * to figure out if the response came from a particular place.
288
289 * \ingroup wptransition
290 * \param self the transition
291 * \param tag an opaque pointer indicating the source of this transition
292 */
293 void
294 wp_transition_set_source_tag (WpTransition * self, gpointer tag)
295 {
296 g_return_if_fail (WP_IS_TRANSITION (self));
297
298 WpTransitionPrivate *priv = wp_transition_get_instance_private (self);
299 priv->tag = tag;
300 }
301
302 /*!
303 * \brief Gets \a self 's data.
304 * \see wp_transition_set_data().
305 * \ingroup wptransition
306 * \param self the transition
307 * \returns (transfer none): the transition's data
308 */
309 gpointer
310 wp_transition_get_data (WpTransition * self)
311 {
312 g_return_val_if_fail (WP_IS_TRANSITION (self), NULL);
313
314 WpTransitionPrivate *priv = wp_transition_get_instance_private (self);
315 return priv->data;
316 }
317
318 /*!
319 * \brief Sets \a self 's data (freeing the existing data, if any). This can be an
320 * arbitrary user structure that holds data associated with this transition.
321 *
322 * \ingroup wptransition
323 * \param self the transition
324 * \param data (nullable): transition-specific user data
325 * \param data_destroy (nullable): GDestroyNotify for \a data
326 */
327 void
328 wp_transition_set_data (WpTransition * self, gpointer data,
329 GDestroyNotify data_destroy)
330 {
331 g_return_if_fail (WP_IS_TRANSITION (self));
332
333 WpTransitionPrivate *priv = wp_transition_get_instance_private (self);
334 if (priv->data && priv->data_destroy)
335 priv->data_destroy (priv->data);
336 priv->data = data;
337 priv->data_destroy = data_destroy;
338 }
339
340 /*!
341 * \brief Checks if the transition completed.
342 * \ingroup wptransition
343 * \param self the transition
344 * \returns TRUE if the transition has completed (with or without an error),
345 * FALSE otherwise
346 */
347 gboolean
348 wp_transition_get_completed (WpTransition * self)
349 {
350 g_return_val_if_fail (WP_IS_TRANSITION (self), FALSE);
351
352 WpTransitionPrivate *priv = wp_transition_get_instance_private (self);
353 return priv->completed;
354 }
355
356 /*!
357 * \brief Checks if the transition completed with an error.
358 * \ingroup wptransition
359 * \param self the transition
360 * \returns TRUE if the transition completed with an error, FALSE otherwise
361 */
362 gboolean
363 wp_transition_had_error (WpTransition * self)
364 {
365 g_return_val_if_fail (WP_IS_TRANSITION (self), FALSE);
366
367 WpTransitionPrivate *priv = wp_transition_get_instance_private (self);
368 return priv->step == WP_TRANSITION_STEP_ERROR;
369 }
370
371 static void
372 wp_transition_return (WpTransition * self, WpTransitionPrivate *priv)
373 {
374 g_assert (priv->completed);
375
376 if (priv->closure) {
377 GValue values[2] = { G_VALUE_INIT, G_VALUE_INIT };
378 g_value_init (&values[0], G_TYPE_OBJECT);
379 g_value_init (&values[1], G_TYPE_OBJECT);
380 g_value_set_object (&values[0], priv->source_object);
381 g_value_set_object (&values[1], self);
382 g_closure_invoke (priv->closure, NULL, 2, values, NULL);
383 g_value_unset (&values[0]);
384 g_value_unset (&values[1]);
385 }
386
387 g_object_notify (G_OBJECT (self), "completed");
388
389 /* WARNING */
390 g_object_unref (self);
391 }
392
393 /*!
394 * \brief Advances the transition to the next step.
395 *
396 * This initially calls _WpTransitionClass::get_next_step()
397 * in order to determine what the next step is.
398 * If _WpTransitionClass::get_next_step() returns a step
399 * different than the previous one, it calls
400 * _WpTransitionClass::execute_step() to execute it.
401 *
402 * The very first time that _WpTransitionClass::get_next_step()
403 * is called, its \a step parameter equals WP_TRANSITION_STEP_NONE.
404 *
405 * When _WpTransitionClass::get_next_step() returns
406 * WP_TRANSITION_STEP_NONE this function completes the transition,
407 * calling the transition's callback and then unref-ing the transition.
408 *
409 * When _WpTransitionClass::get_next_step() returns
410 * WP_TRANSITION_STEP_ERROR, this function calls wp_transition_return_error(),
411 * unless it has already been called directly by
412 * _WpTransitionClass::get_next_step().
413 *
414 * In error conditions, _WpTransitionClass::execute_step()
415 * is called once with \a step being WP_TRANSITION_STEP_ERROR, allowing the
416 * implementation to rollback any changes or cancel underlying jobs, if necessary.
417 *
418 * \ingroup wptransition
419 * \param self the transition
420 */
421 void
422 wp_transition_advance (WpTransition * self)
423 {
424 g_return_if_fail (WP_IS_TRANSITION (self));
425
426 /* keep a reference to avoid issues when wp_transition_return_error() is
427 called from within get_next_step() */
428 g_autoptr (WpTransition) self_ref = g_object_ref (self);
429 WpTransitionPrivate *priv = wp_transition_get_instance_private (self);
430 guint next_step;
431 GError *error = NULL;
432
433 if (priv->completed) {
434 wp_warning_object (priv->source_object, "tried to advance completed transition");
435 return;
436 }
437
438 priv->started = TRUE;
439
440 if (g_cancellable_set_error_if_cancelled (priv->cancellable, &error)) {
441 wp_transition_return_error (self, error);
442 return;
443 }
444
445 /* find the next step */
446 next_step = WP_TRANSITION_GET_CLASS (self)->get_next_step (self, priv->step);
447
448 wp_trace_object (priv->source_object, "transition: %d -> %d", priv->step,
449 next_step);
450
451 if (next_step == WP_TRANSITION_STEP_ERROR) {
452 /* return error if the callback didn't do it already */
453 if (G_UNLIKELY (!priv->completed)) {
454 wp_transition_return_error (self, g_error_new (WP_DOMAIN_LIBRARY,
455 WP_LIBRARY_ERROR_INVARIANT, "state machine error"));
456 }
457 return;
458 }
459
460 g_assert (!priv->completed);
461
462 /* if we reached STEP_NONE again, that means we reached the next state */
463 if (next_step == WP_TRANSITION_STEP_NONE) {
464 /* complete the transition */
465 priv->step = next_step;
466 priv->completed = TRUE;
467 wp_transition_return (self, priv);
468 return;
469 }
470
471 /* still at the same step, this means we are waiting for something */
472 if (next_step == priv->step)
473 return;
474
475 wp_trace_object (priv->source_object, "transition: execute %d", next_step);
476
477 /* execute the next step */
478 priv->step = next_step;
479 WP_TRANSITION_GET_CLASS (self)->execute_step (self, priv->step);
480 }
481
482 /*!
483 * \brief Completes the transition with an error.
484 *
485 * This can be called anytime from within any virtual function or an async
486 * job handler.
487 *
488 * \note In most cases this will also unref the transition, so it is
489 * not safe to access it after this function has been called.
490 *
491 * \ingroup wptransition
492 * \param self the transition
493 * \param error (transfer full): a GError
494 */
495 void
496 wp_transition_return_error (WpTransition * self, GError * error)
497 {
498 g_return_if_fail (WP_IS_TRANSITION (self));
499
500 WpTransitionPrivate *priv = wp_transition_get_instance_private (self);
501
502 /* don't allow _return_error() to be called multiple times,
503 as it is dangerous to recurse in execute_step() */
504 if (G_UNLIKELY (priv->completed)) {
505 wp_warning_object (priv->source_object,
506 "tried to set error on completed transition: %s", error->message);
507 g_error_free (error);
508 return;
509 }
510
511 priv->step = WP_TRANSITION_STEP_ERROR;
512 priv->error = error;
513 priv->completed = TRUE;
514
515 /* allow the implementation to rollback changes */
516 if (WP_TRANSITION_GET_CLASS (self)->execute_step)
517 WP_TRANSITION_GET_CLASS (self)->execute_step (self, priv->step);
518
519 wp_transition_return (self, priv);
520 }
521
522 /*!
523 * \brief Returns the final return status of the transition and its error,
524 * if there was one.
525 *
526 * This is meant to be called from within the GAsyncReadyCallback
527 * that was specified in wp_transition_new().
528 *
529 * \ingroup wptransition
530 * \param res a transition, as a GAsyncResult
531 * \param error (out) (optional): a location to return the transition's error,
532 * if any
533 * \returns TRUE if the transition completed successfully, FALSE if there
534 * was an error
535 */
536 gboolean
537 wp_transition_finish (GAsyncResult * res, GError ** error)
538 {
539 g_return_val_if_fail (WP_IS_TRANSITION (res), FALSE);
540
541 WpTransitionPrivate *priv =
542 wp_transition_get_instance_private (WP_TRANSITION (res));
543 if (priv->error) {
544 g_propagate_error (error, priv->error);
545 priv->error = NULL;
546 } else if (!priv->started) {
547 priv->step = WP_TRANSITION_STEP_ERROR;
548 g_propagate_error (error, g_error_new (WP_DOMAIN_LIBRARY,
549 WP_LIBRARY_ERROR_INVARIANT, "finished before starting"));
550 } else if (!priv->completed) {
551 priv->step = WP_TRANSITION_STEP_ERROR;
552 g_propagate_error (error, g_error_new (WP_DOMAIN_LIBRARY,
553 WP_LIBRARY_ERROR_INVARIANT, "finished before completion"));
554 } else if (priv->finished) {
555 priv->step = WP_TRANSITION_STEP_ERROR;
556 g_propagate_error (error, g_error_new (WP_DOMAIN_LIBRARY,
557 WP_LIBRARY_ERROR_INVARIANT, "finished multiple times"));
558 }
559
560 priv->finished = TRUE;
561
562 wp_trace_object (priv->source_object, "transition: finished %s",
563 (priv->step == WP_TRANSITION_STEP_NONE) ? "ok" : "with error");
564
565 return (priv->step == WP_TRANSITION_STEP_NONE);
566 }