Debian Codegraph @

lib/wp/object.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 <spa/utils/defs.h>
10
11 #include "object.h"
12 #include "log.h"
13 #include "core.h"
14 #include "error.h"
15
16 WP_DEFINE_LOCAL_LOG_TOPIC ("wp-object")
17
18 /*! \defgroup wpfeatureactivationtransition WpFeatureActivationTransition */
19 /*!
20 * \struct WpFeatureActivationTransition
21 * A WpTransition that is used by WpObject to implement feature activation.
22 */
23 struct _WpFeatureActivationTransition
24 {
25 WpTransition parent;
26 WpObjectFeatures missing;
27 };
28
29 G_DEFINE_TYPE (WpFeatureActivationTransition,
30 wp_feature_activation_transition,
31 WP_TYPE_TRANSITION)
32
33 static void
34 wp_feature_activation_transition_init (
35 WpFeatureActivationTransition * transition)
36 {
37 }
38
39 static WpObjectFeatures
40 wp_feature_activation_transition_calc_missing_features (
41 WpFeatureActivationTransition * self, WpObject * object)
42 {
43 /* missing features = features that have been requested,
44 they are supported and they are not active yet;
45 note that supported features may change while the transition is ongoing,
46 which is why we store the requested features as they were originally
47 and keep trying to activate everything that is supported at the time */
48 WpObjectFeatures requested =
49 wp_feature_activation_transition_get_requested_features (self);
50 WpObjectFeatures supported = wp_object_get_supported_features (object);
51 WpObjectFeatures active = wp_object_get_active_features (object);
52 return (requested & supported & ~active);
53 }
54
55 static guint
56 wp_feature_activation_transition_get_next_step (
57 WpTransition * transition, guint step)
58 {
59 WpFeatureActivationTransition *self =
60 WP_FEATURE_ACTIVATION_TRANSITION (transition);
61 WpObject *object = wp_transition_get_source_object (transition);
62
63 self->missing =
64 wp_feature_activation_transition_calc_missing_features (self, object);
65 wp_trace_object (object, "missing features to activate: 0x%x",
66 self->missing);
67
68 /* nothing to activate, we are done */
69 if (self->missing == 0)
70 return WP_TRANSITION_STEP_NONE;
71
72 g_return_val_if_fail (WP_OBJECT_GET_CLASS (object)->activate_get_next_step,
73 WP_TRANSITION_STEP_ERROR);
74
75 step = WP_OBJECT_GET_CLASS (object)->activate_get_next_step (object, self,
76 step, self->missing);
77
78 g_return_val_if_fail (step == WP_TRANSITION_STEP_NONE ||
79 WP_OBJECT_GET_CLASS (object)->activate_execute_step,
80 WP_TRANSITION_STEP_ERROR);
81 return step;
82 }
83
84 static void
85 wp_feature_activation_transition_execute_step (
86 WpTransition * transition, guint step)
87 {
88 WpFeatureActivationTransition *self =
89 WP_FEATURE_ACTIVATION_TRANSITION (transition);
90 WpObject *object = wp_transition_get_source_object (transition);
91
92 WP_OBJECT_GET_CLASS (object)->activate_execute_step (object, self, step,
93 self->missing);
94 }
95
96 static void
97 wp_feature_activation_transition_class_init (
98 WpFeatureActivationTransitionClass * klass)
99 {
100 WpTransitionClass *transition_class = (WpTransitionClass *) klass;
101
102 transition_class->get_next_step =
103 wp_feature_activation_transition_get_next_step;
104 transition_class->execute_step =
105 wp_feature_activation_transition_execute_step;
106 }
107
108 /*!
109 * \brief Gets the features requested to be activated in this transition.
110 * \ingroup wpfeatureactivationtransition
111 * \param self the transition
112 * \returns the features that were requested to be activated in this transition;
113 * this contains the features as they were passed in wp_object_activate() and
114 * therefore it may contain unsupported or already active features
115 */
116 WpObjectFeatures
117 wp_feature_activation_transition_get_requested_features (
118 WpFeatureActivationTransition * self)
119 {
120 return GPOINTER_TO_UINT (wp_transition_get_data (WP_TRANSITION (self)));
121 }
122
123 /*! \defgroup wpobject WpObject */
124 /*!
125 * \struct WpObject
126 *
127 * Base class for objects that have activatable features.
128 *
129 * \gproperties
130 *
131 * \gproperty{core, WpCore *, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY,
132 * The WpCore associated with this object}
133 *
134 * \gproperty{active-features, guint (WpObjectFeatures), G_PARAM_READABLE,
135 * The active WpObjectFeatures on this proxy}
136 *
137 * \gproperty{supported-features, guint (WpObjectFeatures), G_PARAM_READABLE,
138 * The supported WpObjectFeatures on this proxy}
139 */
140 typedef struct _WpObjectPrivate WpObjectPrivate;
141 struct _WpObjectPrivate
142 {
143 /* properties */
144 guint id;
145 GWeakRef core;
146
147 /* features state */
148 WpObjectFeatures ft_active;
149 GQueue *transitions; // element-type: WpFeatureActivationTransition*
150 GSource *idle_advnc_source;
151 GWeakRef ongoing_transition;
152 };
153
154 enum {
155 PROP_0,
156 PROP_ID,
157 PROP_CORE,
158 PROP_ACTIVE_FEATURES,
159 PROP_SUPPORTED_FEATURES,
160 };
161
162 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (WpObject, wp_object, G_TYPE_OBJECT)
163
164 static guint
165 get_next_id ()
166 {
167 static guint next_id = 0;
168 g_atomic_int_inc (&next_id);
169 return next_id;
170 }
171
172 static void
173 wp_object_init (WpObject * self)
174 {
175 WpObjectPrivate *priv = wp_object_get_instance_private (self);
176
177 priv->id = get_next_id ();
178 g_weak_ref_init (&priv->core, NULL);
179 priv->transitions = g_queue_new ();
180 g_weak_ref_init (&priv->ongoing_transition, NULL);
181 }
182
183 static void
184 wp_object_dispose (GObject * object)
185 {
186 WpObject *self = WP_OBJECT (object);
187 WpObjectPrivate *priv = wp_object_get_instance_private (self);
188
189 wp_trace_object (self, "dispose");
190
191 wp_object_deactivate (self, WP_OBJECT_FEATURES_ALL);
192
193 if (priv->idle_advnc_source)
194 g_source_destroy (priv->idle_advnc_source);
195
196 G_OBJECT_CLASS (wp_object_parent_class)->dispose (object);
197 }
198
199 static void
200 wp_object_finalize (GObject * object)
201 {
202 WpObject *self = WP_OBJECT (object);
203 WpObjectPrivate *priv = wp_object_get_instance_private (self);
204
205 /* there should be no transitions, since transitions hold a ref on WpObject */
206 g_warn_if_fail (g_queue_is_empty (priv->transitions));
207 g_clear_pointer (&priv->transitions, g_queue_free);
208 g_clear_pointer (&priv->idle_advnc_source, g_source_unref);
209 g_weak_ref_clear (&priv->ongoing_transition);
210 g_weak_ref_clear (&priv->core);
211
212 /* everything must have been deactivated in dispose() */
213 g_warn_if_fail (priv->ft_active == 0);
214
215 G_OBJECT_CLASS (wp_object_parent_class)->finalize (object);
216 }
217
218 static void
219 wp_object_set_property (GObject * object, guint property_id,
220 const GValue * value, GParamSpec * pspec)
221 {
222 WpObject *self = WP_OBJECT (object);
223 WpObjectPrivate *priv = wp_object_get_instance_private (self);
224
225 switch (property_id) {
226 case PROP_CORE:
227 g_weak_ref_set (&priv->core, g_value_get_object (value));
228 break;
229 default:
230 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
231 break;
232 }
233 }
234
235 static void
236 wp_object_get_property (GObject * object, guint property_id, GValue * value,
237 GParamSpec * pspec)
238 {
239 WpObject *self = WP_OBJECT (object);
240 WpObjectPrivate *priv = wp_object_get_instance_private (self);
241
242 switch (property_id) {
243 case PROP_ID:
244 g_value_set_uint (value, priv->id);
245 break;
246 case PROP_CORE:
247 g_value_take_object (value, wp_object_get_core (self));
248 break;
249 case PROP_ACTIVE_FEATURES:
250 g_value_set_uint (value, priv->ft_active);
251 break;
252 case PROP_SUPPORTED_FEATURES:
253 g_value_set_uint (value, wp_object_get_supported_features (self));
254 break;
255 default:
256 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
257 break;
258 }
259 }
260
261 static void
262 wp_object_class_init (WpObjectClass * klass)
263 {
264 GObjectClass *object_class = (GObjectClass *) klass;
265
266 object_class->dispose = wp_object_dispose;
267 object_class->finalize = wp_object_finalize;
268 object_class->get_property = wp_object_get_property;
269 object_class->set_property = wp_object_set_property;
270
271 g_object_class_install_property (object_class, PROP_ID,
272 g_param_spec_uint ("id", "id",
273 "The object unique id", 0, G_MAXUINT, 0,
274 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
275
276 g_object_class_install_property (object_class, PROP_CORE,
277 g_param_spec_object ("core", "core", "The WpCore", WP_TYPE_CORE,
278 G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
279
280 g_object_class_install_property (object_class, PROP_ACTIVE_FEATURES,
281 g_param_spec_uint ("active-features", "active-features",
282 "The active WpObjectFeatures on this proxy", 0, G_MAXUINT, 0,
283 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
284
285 g_object_class_install_property (object_class, PROP_SUPPORTED_FEATURES,
286 g_param_spec_uint ("supported-features", "supported-features",
287 "The supported WpObjectFeatures on this proxy", 0, G_MAXUINT, 0,
288 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
289 }
290
291 /*!
292 * \brief Gets the unique wireplumber Id of this object
293 * \ingroup wpsessionitem
294 * \param self the session item
295 */
296 guint
297 wp_object_get_id (WpObject * self)
298 {
299 g_return_val_if_fail (WP_IS_OBJECT (self), SPA_ID_INVALID);
300
301 WpObjectPrivate *priv = wp_object_get_instance_private (self);
302 return priv->id;
303 }
304
305 /*!
306 * \brief Gets the core associated with this object.
307 *
308 * \ingroup wpobject
309 * \param self the object
310 * \returns (transfer full): the core associated with this object
311 */
312 WpCore *
313 wp_object_get_core (WpObject * self)
314 {
315 g_return_val_if_fail (WP_IS_OBJECT (self), NULL);
316
317 WpObjectPrivate *priv = wp_object_get_instance_private (self);
318 WpCore *core = g_weak_ref_get (&priv->core);
319 if (!core && WP_IS_CORE (self))
320 core = WP_CORE (g_object_ref (self));
321 return core;
322 }
323
324 /*!
325 * \brief Gets the active features of this object.
326 * \ingroup wpobject
327 * \param self the object
328 * \returns A bitset containing the active features of this object
329 */
330 WpObjectFeatures
331 wp_object_get_active_features (WpObject * self)
332 {
333 g_return_val_if_fail (WP_IS_OBJECT (self), 0);
334
335 WpObjectPrivate *priv = wp_object_get_instance_private (self);
336 return priv->ft_active;
337 }
338
339 /*!
340 * \brief Checks if the given features are active on this object.
341 * \param self the object
342 * \param features the features to check
343 * \returns TRUE if all the given features are active on this object
344 * \ingroup wpobject
345 * \since 0.5.0
346 */
347 gboolean
348 wp_object_test_active_features (WpObject * self, WpObjectFeatures features)
349 {
350 g_return_val_if_fail (WP_IS_OBJECT (self), FALSE);
351
352 WpObjectPrivate *priv = wp_object_get_instance_private (self);
353 return (priv->ft_active & features) == features;
354 }
355
356 /*!
357 * \brief Gets the supported features of this object.
358 * \ingroup wpobject
359 * \param self the object
360 * \returns A bitset containing the supported features of this object;
361 * note that supported features may change at runtime
362 */
363 WpObjectFeatures
364 wp_object_get_supported_features (WpObject * self)
365 {
366 g_return_val_if_fail (WP_IS_OBJECT (self), 0);
367 g_return_val_if_fail (WP_OBJECT_GET_CLASS (self)->get_supported_features, 0);
368
369 return WP_OBJECT_GET_CLASS (self)->get_supported_features (self);
370 }
371
372 /*!
373 * \brief Checks if the given features are supported on this object.
374 * \param self the object
375 * \param features the features to check
376 * \returns TRUE if all the given features are supported on this object
377 * \ingroup wpobject
378 * \since 0.5.0
379 */
380 gboolean
381 wp_object_test_supported_features (WpObject * self, WpObjectFeatures features)
382 {
383 return (wp_object_get_supported_features (self) & features) == features;
384 }
385
386 static gboolean
387 wp_object_advance_transitions (WpObject * self)
388 {
389 WpObjectPrivate *priv = wp_object_get_instance_private (self);
390 g_autoptr (WpTransition) t = NULL;
391
392 /* clear before advancing; a transition may need to schedule
393 a new call to wp_object_advance_transitions() */
394 g_clear_pointer (&priv->idle_advnc_source, g_source_unref);
395
396 /* advance ongoing transition if any */
397 t = g_weak_ref_get (&priv->ongoing_transition);
398 if (t) {
399 wp_transition_advance (t);
400 if (!wp_transition_get_completed (t))
401 return G_SOURCE_REMOVE;
402 }
403
404 /* set next transition and advance */
405 if (!g_queue_is_empty (priv->transitions)) {
406 WpTransition *next = g_queue_pop_head (priv->transitions);
407 g_weak_ref_set (&priv->ongoing_transition, next);
408 wp_transition_advance (next);
409 }
410
411 return G_SOURCE_REMOVE;
412 }
413
414 static void
415 on_transition_completed (WpTransition * transition, GParamSpec * param,
416 WpObject * self)
417 {
418 WpObjectPrivate *priv = wp_object_get_instance_private (self);
419
420 /* abort activation if a transition failed */
421 if (wp_transition_had_error (transition)) {
422 wp_object_abort_activation (self, "a transition failed");
423 return;
424 }
425
426 /* advance pending transitions */
427 if (!g_queue_is_empty (priv->transitions) && !priv->idle_advnc_source) {
428 g_autoptr (WpCore) core = wp_object_get_core (self);
429 g_return_if_fail (core != NULL);
430
431 wp_core_idle_add (core, &priv->idle_advnc_source,
432 G_SOURCE_FUNC (wp_object_advance_transitions), g_object_ref (self),
433 g_object_unref);
434 }
435 }
436
437 /*!
438 * \brief Callback version of wp_object_activate_closure()
439 *
440 * \ingroup wpobject
441 * \param self the object
442 * \param features the features to enable
443 * \param cancellable (nullable): a cancellable for the async operation
444 * \param callback (scope async)(closure user_data): a function to call when activation is complete
445 * \param user_data data for \a callback
446 */
447 void
448 wp_object_activate (WpObject * self,
449 WpObjectFeatures features, GCancellable * cancellable,
450 GAsyncReadyCallback callback, gpointer user_data)
451 {
452 g_return_if_fail (WP_IS_OBJECT (self));
453
454 GClosure *closure = g_cclosure_new (G_CALLBACK (callback), user_data, NULL);
455
456 wp_object_activate_closure (self, features, cancellable, closure);
457 }
458
459 /*!
460 * \brief Activates the requested \a features and invokes \a closure when this
461 * is done. \a features may contain unsupported or already active features.
462 * The operation will filter them and activate only ones that are supported and
463 * inactive.
464 *
465 * If multiple calls to this method is done, the operations will be executed
466 * one after the other to ensure features only get activated once.
467 *
468 * \note \a closure may be invoked in sync while this method is being called,
469 * if there are no features to activate.
470 *
471 * \ingroup wpobject
472 * \param self the object
473 * \param features the features to enable
474 * \param cancellable (nullable): a cancellable for the async operation
475 * \param closure (transfer full): the closure to use when activation is completed
476 */
477 void
478 wp_object_activate_closure (WpObject * self,
479 WpObjectFeatures features, GCancellable * cancellable,
480 GClosure *closure)
481 {
482 g_return_if_fail (WP_IS_OBJECT (self));
483
484 WpObjectPrivate *priv = wp_object_get_instance_private (self);
485 g_autoptr (WpCore) core = wp_object_get_core (self);
486
487 g_return_if_fail (core != NULL);
488
489 WpTransition *transition = wp_transition_new_closure (
490 WP_TYPE_FEATURE_ACTIVATION_TRANSITION, self, cancellable, closure);
491 wp_transition_set_source_tag (transition, wp_object_activate);
492 wp_transition_set_data (transition, GUINT_TO_POINTER (features), NULL);
493 g_signal_connect_object (transition, "notify::completed",
494 G_CALLBACK (on_transition_completed), self, 0);
495
496 g_queue_push_tail (priv->transitions, transition);
497
498 if (!priv->idle_advnc_source) {
499 wp_core_idle_add (core, &priv->idle_advnc_source,
500 G_SOURCE_FUNC (wp_object_advance_transitions), g_object_ref (self),
501 g_object_unref);
502 }
503 }
504
505 /*!
506 * \brief Finishes the async operation that was started with wp_object_activate()
507 *
508 * \ingroup wpobject
509 * \param self the object
510 * \param res the async operation result
511 * \param error (out) (optional): the error of the operation, if any
512 * \returns TRUE if the requested features were activated,
513 * FALSE if there was an error
514 */
515 gboolean
516 wp_object_activate_finish (WpObject * self, GAsyncResult * res, GError ** error)
517 {
518 g_return_val_if_fail (WP_IS_OBJECT (self), FALSE);
519 g_return_val_if_fail (
520 g_async_result_is_tagged (res, wp_object_activate), FALSE);
521 return wp_transition_finish (res, error);
522 }
523
524 /*!
525 * \brief Deactivates the given \a features, leaving the object in the state
526 * it was before they were enabled.
527 *
528 * This is seldom needed to call manually, but it can be used to save
529 * resources if some features are no longer needed.
530 *
531 * \ingroup wpobject
532 * \param self the object
533 * \param features the features to deactivate
534 */
535 void
536 wp_object_deactivate (WpObject * self, WpObjectFeatures features)
537 {
538 g_return_if_fail (WP_IS_OBJECT (self));
539 g_return_if_fail (WP_OBJECT_GET_CLASS (self)->deactivate);
540
541 WpObjectPrivate *priv = wp_object_get_instance_private (self);
542 WP_OBJECT_GET_CLASS (self)->deactivate (self, features & priv->ft_active);
543 }
544
545 /*!
546 * \brief Aborts the current object activation by returning a transition error
547 * if any transitions are pending.
548 *
549 * This is usually used to stop any pending activation if an error happened.
550 *
551 * \ingroup wpobject
552 * \param self the object
553 * \param msg the message used in the transition error
554 * \since 0.4.6
555 */
556 void
557 wp_object_abort_activation (WpObject * self, const gchar *msg)
558 {
559 WpObjectPrivate *priv;
560 g_autoptr (WpTransition) t = NULL;
561
562 g_return_if_fail (WP_IS_OBJECT (self));
563
564 priv = wp_object_get_instance_private (self);
565
566 g_clear_pointer (&priv->idle_advnc_source, g_source_unref);
567
568 /* abort ongoing transition if any */
569 t = g_weak_ref_get (&priv->ongoing_transition);
570 if (t && !wp_transition_get_completed (t)) {
571 wp_transition_return_error (t, g_error_new (WP_DOMAIN_LIBRARY,
572 WP_LIBRARY_ERROR_OPERATION_FAILED,
573 "Object activation aborted: %s", msg));
574 return;
575 }
576
577 /* recursively abort the queued transitions if any */
578 if (!g_queue_is_empty (priv->transitions)) {
579 WpTransition *next = g_queue_pop_head (priv->transitions);
580 g_weak_ref_set (&priv->ongoing_transition, next);
581 wp_object_abort_activation (self, msg);
582 }
583 }
584
585 /*!
586 * \brief Allows subclasses to update the currently active features.
587 *
588 * \a activated should contain new features and \a deactivated
589 * should contain features that were just deactivated.
590 * Calling this method also advances the activation transitions.
591 *
592 * \remark Private method to be called by subclasses only.
593 *
594 * \ingroup wpobject
595 * \param self the object
596 * \param activated the features that were activated, or 0
597 * \param deactivated the features that were deactivated, or 0
598 */
599 void
600 wp_object_update_features (WpObject * self, WpObjectFeatures activated,
601 WpObjectFeatures deactivated)
602 {
603 g_return_if_fail (WP_IS_OBJECT (self));
604
605 WpObjectPrivate *priv = wp_object_get_instance_private (self);
606 guint old_ft = priv->ft_active;
607 g_autoptr (WpTransition) t = NULL;
608
609 priv->ft_active |= activated;
610 priv->ft_active &= ~deactivated;
611
612 if (priv->ft_active != old_ft) {
613 wp_debug_object (self, "features changed 0x%x -> 0x%x", old_ft,
614 priv->ft_active);
615 g_object_notify (G_OBJECT (self), "active-features");
616 }
617
618 t = g_weak_ref_get (&priv->ongoing_transition);
619 if ((t || !g_queue_is_empty (priv->transitions)) && !priv->idle_advnc_source) {
620 g_autoptr (WpCore) core = wp_object_get_core (self);
621 g_return_if_fail (core != NULL);
622
623 wp_core_idle_add (core, &priv->idle_advnc_source,
624 G_SOURCE_FUNC (wp_object_advance_transitions), g_object_ref (self),
625 g_object_unref);
626 }
627 }