lib: add new WpObject base class

A base class for objects that can have optional
features enabled and disabled. The intention is to make
this the superclass of WpProxy.

Instead of following the augment() pattern of WpProxy,
this one follows the more advanced transition pattern
that has been previously implemented in WpSessionItem.

lib/wp/meson.build

@@ -13,6 +13,7 @@ wp_lib_sources = files(
   'metadata.c',
   'module.c',
   'node.c',
+  'object.c',
   'object-interest.c',
   'object-manager.c',
   'plugin.c',
@@ -47,6 +48,7 @@ wp_lib_headers = files(
   'metadata.h',
   'module.h',
   'node.h',
+  'object.h',
   'object-interest.h',
   'object-manager.h',
   'plugin.h',

lib/wp/object.c

+/* WirePlumber
+ *
+ * Copyright © 2020 Collabora Ltd.
+ *    @author George Kiagiadakis <george.kiagiadakis@collabora.com>
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * SECTION: object
+ * @title: Base object type
+ */
+
+#define G_LOG_DOMAIN "wp-object"
+
+#include "object.h"
+#include "debug.h"
+#include "core.h"
+
+struct _WpFeatureActivationTransition
+{
+  WpTransition parent;
+  WpObjectFeatures missing;
+};
+
+/**
+ * WpFeatureActivationTransition:
+ *
+ * A #WpTransition that is used by #WpObject to implement feature activation.
+ */
+G_DEFINE_TYPE (WpFeatureActivationTransition,
+               wp_feature_activation_transition,
+               WP_TYPE_TRANSITION)
+
+static void
+wp_feature_activation_transition_init (
+    WpFeatureActivationTransition * transition)
+{
+}
+
+static WpObjectFeatures
+wp_feature_activation_transition_calc_missing_features (
+    WpFeatureActivationTransition * self, WpObject * object)
+{
+  /* missing features = features that have been requested,
+     they are supported and they are not active yet;
+     note that supported features may change while the transition is ongoing,
+     which is why we store the requested features as they were originally
+     and keep trying to activate everything that is supported at the time */
+  WpObjectFeatures requested =
+      wp_feature_activation_transition_get_requested_features (self);
+  WpObjectFeatures supported = wp_object_get_supported_features (object);
+  WpObjectFeatures active = wp_object_get_active_features (object);
+  return (requested & supported & ~active);
+}
+
+static guint
+wp_feature_activation_transition_get_next_step (
+    WpTransition * transition, guint step)
+{
+  WpFeatureActivationTransition *self =
+      WP_FEATURE_ACTIVATION_TRANSITION (transition);
+  WpObject *object = wp_transition_get_source_object (transition);
+
+  self->missing =
+      wp_feature_activation_transition_calc_missing_features (self, object);
+  wp_trace_object (object, "missing features to activate: 0x%x",
+      self->missing);
+
+  /* nothing to activate, we are done */
+  if (self->missing == 0)
+    return WP_TRANSITION_STEP_NONE;
+
+  g_return_val_if_fail (WP_OBJECT_GET_CLASS (object)->activate_get_next_step,
+      WP_TRANSITION_STEP_ERROR);
+
+  step = WP_OBJECT_GET_CLASS (object)->activate_get_next_step (object, self,
+      step, self->missing);
+
+  g_return_val_if_fail (step == WP_TRANSITION_STEP_NONE ||
+          WP_OBJECT_GET_CLASS (object)->activate_execute_step,
+      WP_TRANSITION_STEP_ERROR);
+  return step;
+}
+
+static void
+wp_feature_activation_transition_execute_step (
+    WpTransition * transition, guint step)
+{
+  WpFeatureActivationTransition *self =
+      WP_FEATURE_ACTIVATION_TRANSITION (transition);
+  WpObject *object = wp_transition_get_source_object (transition);
+
+  WP_OBJECT_GET_CLASS (object)->activate_execute_step (object, self, step,
+      self->missing);
+}
+
+static void
+wp_feature_activation_transition_class_init (
+    WpFeatureActivationTransitionClass * klass)
+{
+  WpTransitionClass *transition_class = (WpTransitionClass *) klass;
+
+  transition_class->get_next_step =
+      wp_feature_activation_transition_get_next_step;
+  transition_class->execute_step =
+      wp_feature_activation_transition_execute_step;
+}
+
+/**
+ * wp_feature_activation_transition_get_requested_features:
+ * @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
+ */
+WpObjectFeatures
+wp_feature_activation_transition_get_requested_features (
+    WpFeatureActivationTransition * self)
+{
+  return GPOINTER_TO_UINT (wp_transition_get_data (WP_TRANSITION (self)));
+}
+
+
+typedef struct _WpObjectPrivate WpObjectPrivate;
+struct _WpObjectPrivate
+{
+  /* properties */
+  GWeakRef core;
+
+  /* features state */
+  WpObjectFeatures ft_active;
+  GQueue *transitions; // element-type: WpFeatureActivationTransition*
+  GSource *idle_advnc_source;
+};
+
+enum {
+  PROP_0,
+  PROP_CORE,
+  PROP_ACTIVE_FEATURES,
+  PROP_SUPPORTED_FEATURES,
+};
+
+/**
+ * WpObject:
+ *
+ * Base class for objects that may have optional activatable features.
+ */
+G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (WpObject, wp_object, G_TYPE_OBJECT)
+
+static void
+wp_object_init (WpObject * self)
+{
+  WpObjectPrivate *priv = wp_object_get_instance_private (self);
+
+  g_weak_ref_init (&priv->core, NULL);
+  priv->transitions = g_queue_new ();
+}
+
+static void
+wp_object_dispose (GObject * object)
+{
+  WpObject *self = WP_OBJECT (object);
+  WpObjectPrivate *priv = wp_object_get_instance_private (self);
+
+  wp_object_deactivate (self, WP_OBJECT_FEATURES_ALL);
+
+  if (priv->idle_advnc_source)
+    g_source_destroy (priv->idle_advnc_source);
+
+  G_OBJECT_CLASS (wp_object_parent_class)->dispose (object);
+}
+
+static void
+wp_object_finalize (GObject * object)
+{
+  WpObject *self = WP_OBJECT (object);
+  WpObjectPrivate *priv = wp_object_get_instance_private (self);
+
+  /* there should be no transitions, since transitions hold a ref on WpObject */
+  g_warn_if_fail (g_queue_is_empty (priv->transitions));
+  g_clear_pointer (&priv->transitions, g_queue_free);
+  g_clear_pointer (&priv->idle_advnc_source, g_source_unref);
+  g_weak_ref_clear (&priv->core);
+
+  /* everything must have been deactivated in dispose() */
+  g_warn_if_fail (priv->ft_active == 0);
+
+  G_OBJECT_CLASS (wp_object_parent_class)->finalize (object);
+}
+
+static void
+wp_object_set_property (GObject * object, guint property_id,
+    const GValue * value, GParamSpec * pspec)
+{
+  WpObject *self = WP_OBJECT (object);
+  WpObjectPrivate *priv = wp_object_get_instance_private (self);
+
+  switch (property_id) {
+  case PROP_CORE:
+    g_weak_ref_set (&priv->core, g_value_get_object (value));
+    break;
+  default:
+    G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
+    break;
+  }
+}
+
+static void
+wp_object_get_property (GObject * object, guint property_id, GValue * value,
+    GParamSpec * pspec)
+{
+  WpObject *self = WP_OBJECT (object);
+  WpObjectPrivate *priv = wp_object_get_instance_private (self);
+
+  switch (property_id) {
+  case PROP_CORE:
+    g_value_take_object (value, g_weak_ref_get (&priv->core));
+    break;
+  case PROP_ACTIVE_FEATURES:
+    g_value_set_uint (value, priv->ft_active);
+    break;
+  case PROP_SUPPORTED_FEATURES:
+    g_value_set_uint (value, wp_object_get_supported_features (self));
+    break;
+  default:
+    G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
+    break;
+  }
+}
+
+static void
+wp_object_class_init (WpObjectClass * klass)
+{
+  GObjectClass *object_class = (GObjectClass *) klass;
+
+  object_class->dispose = wp_object_dispose;
+  object_class->finalize = wp_object_finalize;
+  object_class->get_property = wp_object_get_property;
+  object_class->set_property = wp_object_set_property;
+
+  g_object_class_install_property (object_class, PROP_CORE,
+      g_param_spec_object ("core", "core", "The WpCore", WP_TYPE_CORE,
+          G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
+
+  g_object_class_install_property (object_class, PROP_ACTIVE_FEATURES,
+      g_param_spec_uint ("active-features", "active-features",
+          "The active WpObjectFeatures on this proxy", 0, G_MAXUINT, 0,
+          G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
+
+  g_object_class_install_property (object_class, PROP_SUPPORTED_FEATURES,
+      g_param_spec_uint ("supported-features", "supported-features",
+          "The supported WpObjectFeatures on this proxy", 0, G_MAXUINT, 0,
+          G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
+}
+
+/**
+ * wp_object_get_core:
+ * @self: the object
+ *
+ * Returns: (transfer full): the core associated with this object
+ */
+WpCore *
+wp_object_get_core (WpObject * self)
+{
+  g_return_val_if_fail (WP_IS_OBJECT (self), NULL);
+
+  WpObjectPrivate *priv = wp_object_get_instance_private (self);
+  return g_weak_ref_get (&priv->core);
+}
+
+/**
+ * wp_object_get_active_features:
+ * @self: the object
+ *
+ * Returns: a bitset containing the active features of this object
+ */
+WpObjectFeatures
+wp_object_get_active_features (WpObject * self)
+{
+  g_return_val_if_fail (WP_IS_OBJECT (self), 0);
+
+  WpObjectPrivate *priv = wp_object_get_instance_private (self);
+  return priv->ft_active;
+}
+
+/**
+ * wp_object_get_supported_features:
+ * @self: the object
+ *
+ * Returns: a bitset containing the supported features of this object;
+ *   note that supported features may change at runtime
+ */
+WpObjectFeatures
+wp_object_get_supported_features (WpObject * self)
+{
+  g_return_val_if_fail (WP_IS_OBJECT (self), 0);
+  g_return_val_if_fail (WP_OBJECT_GET_CLASS (self)->get_supported_features, 0);
+
+  return WP_OBJECT_GET_CLASS (self)->get_supported_features (self);
+}
+
+static gboolean
+wp_object_advance_transitions (WpObject * self)
+{
+  WpObjectPrivate *priv = wp_object_get_instance_private (self);
+  WpTransition *t;
+
+  /* clear before advancing; a transition may need to schedule
+     a new call to wp_object_advance_transitions() */
+  g_clear_pointer (&priv->idle_advnc_source, g_source_unref);
+
+  while ((t = g_queue_peek_head (priv->transitions))) {
+    wp_transition_advance (t);
+    if (!wp_transition_get_completed (t))
+      break;
+    g_object_unref (g_queue_pop_head (priv->transitions));
+  }
+
+  return G_SOURCE_REMOVE;
+}
+
+/**
+ * wp_object_activate:
+ * @self: the object
+ * @features: the features to enable
+ * @cancellable: (nullable): a cancellable for the async operation
+ * @callback: (scope async): a function to call when activation is complete
+ * @user_data: (closure): data for @callback
+ *
+ * Activates the requested @features and calls @callback when this is done.
+ * @features may contain unsupported or already active features. The operation
+ * will filter them and activate only ones that are supported and inactive.
+ *
+ * If multiple calls to this method is done, the operations will be executed
+ * one after the other to ensure features only get activated once.
+ *
+ * Note that @callback may be called in sync while this method is being called,
+ * if there are no features to activate.
+ */
+void
+wp_object_activate (WpObject * self,
+    WpObjectFeatures features, GCancellable * cancellable,
+    GAsyncReadyCallback callback, gpointer user_data)
+{
+  g_return_if_fail (WP_IS_OBJECT (self));
+
+  WpObjectPrivate *priv = wp_object_get_instance_private (self);
+  g_autoptr (WpCore) core = g_weak_ref_get (&priv->core);
+
+  g_return_if_fail (core != NULL);
+
+  GClosure *closure =
+      g_cclosure_new (G_CALLBACK (callback), user_data, NULL);
+  WpTransition *transition = wp_transition_new_closure (
+      WP_TYPE_FEATURE_ACTIVATION_TRANSITION, self, cancellable, closure);
+  wp_transition_set_source_tag (transition, wp_object_activate);
+  wp_transition_set_data (transition, GUINT_TO_POINTER (features), NULL);
+
+  g_queue_push_tail (priv->transitions, g_object_ref (transition));
+
+  if (!priv->idle_advnc_source) {
+    wp_core_idle_add (core, &priv->idle_advnc_source,
+        G_SOURCE_FUNC (wp_object_advance_transitions), self, NULL);
+  }
+}
+
+/**
+ * wp_object_activate_finish:
+ * @self: the object
+ * @res: the async operation result
+ * @error: (out) (optional): the error of the operation, if any
+ *
+ * Returns: %TRUE if the requested features were activated,
+ *   %FALSE if there was an error
+ */
+gboolean
+wp_object_activate_finish (WpObject * self, GAsyncResult * res, GError ** error)
+{
+  g_return_val_if_fail (WP_IS_OBJECT (self), FALSE);
+  g_return_val_if_fail (
+      g_async_result_is_tagged (res, wp_object_activate), FALSE);
+  return wp_transition_finish (res, error);
+}
+
+/**
+ * wp_object_deactivate
+ * @self: the object
+ * @features: the features to deactivate
+ *
+ * Deactivates the given @features, leaving the object in the state it was
+ * before they were enabled. This is seldom needed to call manually, but it
+ * can be used to save resources if some features are no longer needed.
+ */
+void
+wp_object_deactivate (WpObject * self, WpObjectFeatures features)
+{
+  g_return_if_fail (WP_IS_OBJECT (self));
+  g_return_if_fail (WP_OBJECT_GET_CLASS (self)->deactivate);
+
+  WP_OBJECT_GET_CLASS (self)->deactivate (self, features);
+}
+
+/**
+ * wp_object_update_features:
+ *
+ * Private method to be called by subclasses. Allows subclasses to update
+ * the currently active features. @activated should contain new features and
+ * @deactivated should contain features that were just deactivated.
+ *
+ * Calling this method also advances the activation transitions.
+ */
+void
+wp_object_update_features (WpObject * self, WpObjectFeatures activated,
+    WpObjectFeatures deactivated)
+{
+  g_return_if_fail (WP_IS_OBJECT (self));
+
+  WpObjectPrivate *priv = wp_object_get_instance_private (self);
+  gint old_ft = priv->ft_active;
+
+  priv->ft_active |= activated;
+  priv->ft_active &= ~deactivated;
+
+  if (priv->ft_active != old_ft) {
+    wp_debug_object (self, "features changed 0x%x -> 0x%x", old_ft,
+        priv->ft_active);
+    g_object_notify (G_OBJECT (self), "active-features");
+  }
+
+  if (!g_queue_is_empty (priv->transitions) && !priv->idle_advnc_source) {
+    g_autoptr (WpCore) core = g_weak_ref_get (&priv->core);
+    g_return_if_fail (core != NULL);
+
+    wp_core_idle_add (core, &priv->idle_advnc_source,
+        G_SOURCE_FUNC (wp_object_advance_transitions), self, NULL);
+  }
+}

lib/wp/object.h

+/* WirePlumber
+ *
+ * Copyright © 2020 Collabora Ltd.
+ *    @author George Kiagiadakis <george.kiagiadakis@collabora.com>
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#ifndef __WIREPLUMBER_OBJECT_H__
+#define __WIREPLUMBER_OBJECT_H__
+
+#include "transition.h"
+
+G_BEGIN_DECLS
+
+typedef struct _WpCore WpCore;
+
+/**
+ * WpObjectFeatures:
+ *
+ * Flags that specify functionality that is available on this class.
+ *
+ * Use wp_object_activate() to enable more features,
+ * wp_object_get_supported_features() to see which features are supported and
+ * wp_object_get_active_features() to find out which features are already
+ * enabled. Features can also be deactivated later using wp_object_deactivate().
+ *
+ * Actual feature flags are to be specified by subclasses and their interfaces.
+ * %WP_OBJECT_FEATURES_ALL is a special value that can be used to activate
+ * all the supported features in any given object.
+ */
+typedef guint WpObjectFeatures;
+
+/**
+ * WP_OBJECT_FEATURES_ALL:
+ *
+ * Special value that can be used to activate
+ * all the supported features in any given object.
+ */
+static const WpObjectFeatures WP_OBJECT_FEATURES_ALL = 0xffffffff;
+
+/**
+ * WP_TYPE_FEATURE_ACTIVATION_TRANSITION:
+ *
+ * The #WpFeatureActivationTransition #GType
+ */
+#define WP_TYPE_FEATURE_ACTIVATION_TRANSITION \
+    (wp_feature_activation_transition_get_type ())
+WP_API
+G_DECLARE_FINAL_TYPE (WpFeatureActivationTransition,
+                      wp_feature_activation_transition,
+                      WP, FEATURE_ACTIVATION_TRANSITION, WpTransition)
+
+WP_API
+WpObjectFeatures wp_feature_activation_transition_get_requested_features (
+    WpFeatureActivationTransition * self);
+
+/**
+ * WP_TYPE_OBJECT:
+ *
+ * The #WpObject #GType
+ */
+#define WP_TYPE_OBJECT (wp_object_get_type ())
+WP_API
+G_DECLARE_DERIVABLE_TYPE (WpObject, wp_object, WP, OBJECT, GObject)
+
+struct _WpObjectClass
+{
+  GObjectClass parent_class;
+
+  WpObjectFeatures (*get_supported_features) (WpObject * self);
+
+  guint (*activate_get_next_step) (WpObject * self,
+      WpFeatureActivationTransition * transition, guint step,
+      WpObjectFeatures missing);
+  void (*activate_execute_step) (WpObject * self,
+      WpFeatureActivationTransition * transition, guint step,
+      WpObjectFeatures missing);
+
+  void (*deactivate) (WpObject * self, WpObjectFeatures features);
+};
+
+WP_API
+WpCore * wp_object_get_core (WpObject * self);
+
+WP_API
+WpObjectFeatures wp_object_get_active_features (WpObject * self);
+
+WP_API
+WpObjectFeatures wp_object_get_supported_features (WpObject * self);
+
+WP_API
+void wp_object_activate (WpObject * self,
+    WpObjectFeatures features, GCancellable * cancellable,
+    GAsyncReadyCallback callback, gpointer user_data);
+
+WP_API
+gboolean wp_object_activate_finish (WpObject * self, GAsyncResult * res,
+    GError ** error);
+
+WP_API
+void wp_object_deactivate (WpObject * self, WpObjectFeatures features);
+
+/* for subclasses only */
+
+WP_API
+void wp_object_update_features (WpObject * self, WpObjectFeatures activated,
+    WpObjectFeatures deactivated);
+
+G_END_DECLS
+
+#endif

lib/wp/wp.h

@@ -25,6 +25,7 @@
 #include "node.h"
 #include "object-interest.h"
 #include "object-manager.h"
+#include "object.h"
 #include "plugin.h"
 #include "port.h"
 #include "properties.h"