/* dzl-signal-group.c
 *
 * Copyright (C) 2015 Christian Hergert <christian@hergert.me>
 * Copyright (C) 2015 Garrett Regier <garrettregier@gmail.com>
 *
 * This file is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; either version 2.1 of the
 * License, or (at your option) any later version.
 *
 * This file is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

#define G_LOG_DOMAIN "dzl-signal-group"

#include "config.h"

#include <glib/gi18n.h>

#include "bindings/dzl-signal-group.h"
#include "util/dzl-macros.h"

/**
 * SECTION:dzlsignalgroup
 * @title: DzlSignalGroup
 * @short_description: Manage a collection of signals on a #GObject
 *
 * #DzlSignalGroup manages to simplify the process of connecting
 * many signals to a #GObject as a group. As such there is no API
 * to disconnect a signal from the group.
 *
 * In particular, this allows you to:
 *
 *  - Change the target instance, which automatically causes disconnection
 *    of the signals from the old instance and connecting to the new instance.
 *  - Block and unblock signals as a group
 *  - Ensuring that blocked state transfers across target instances.
 *
 * One place you might want to use such a structure is with #GtkTextView and
 * #GtkTextBuffer. Often times, you'll need to connect to many signals on
 * #GtkTextBuffer from a #GtkTextView subclass. This allows you to create a
 * signal group during instance construction, simply bind the
 * #GtkTextView:buffer property to #DzlSignalGroup:target and connect
 * all the signals you need. When the #GtkTextView:buffer property changes
 * all of the signals will be transitioned correctly.
 */

struct _DzlSignalGroup
{
  GObject     parent_instance;

  GWeakRef    target_ref;
  GPtrArray  *handlers;
  GType       target_type;
  gsize       block_count;

  guint       has_bound_at_least_once : 1;
};

struct _DzlSignalGroupClass
{
  GObjectClass parent_class;

  void (*bind) (DzlSignalGroup *self,
                GObject        *target);
};

typedef struct
{
  DzlSignalGroup *group;
  gulong          handler_id;
  GClosure       *closure;
  guint           signal_id;
  GQuark          signal_detail;
  guint           connect_after : 1;
} SignalHandler;

G_DEFINE_TYPE (DzlSignalGroup, dzl_signal_group, G_TYPE_OBJECT)

enum {
  PROP_0,
  PROP_TARGET,
  PROP_TARGET_TYPE,
  LAST_PROP
};

enum {
  BIND,
  UNBIND,
  LAST_SIGNAL
};

static GParamSpec *properties [LAST_PROP];
static guint signals [LAST_SIGNAL];

static void
dzl_signal_group_set_target_type (DzlSignalGroup *self,
                                  GType           target_type)
{
  g_assert (DZL_IS_SIGNAL_GROUP (self));
  g_assert (g_type_is_a (target_type, G_TYPE_OBJECT));

  self->target_type = target_type;

  /* The class must be created at least once for the signals
   * to be registered, otherwise g_signal_parse_name() will fail
   */
  if (G_TYPE_IS_INTERFACE (target_type))
    {
      if (g_type_default_interface_peek (target_type) == NULL)
        g_type_default_interface_unref (g_type_default_interface_ref (target_type));
    }
  else
    {
      if (g_type_class_peek (target_type) == NULL)
        g_type_class_unref (g_type_class_ref (target_type));
    }
}

static void
dzl_signal_group_gc_handlers (DzlSignalGroup *self)
{
  g_assert (DZL_IS_SIGNAL_GROUP (self));

  /*
   * Remove any handlers for which the closures have become invalid. We do
   * this cleanup lazily to avoid situations where we could have disposal
   * active on both the signal group and the peer object.
   */

  for (guint i = self->handlers->len; i > 0; i--)
    {
      const SignalHandler *handler = g_ptr_array_index (self->handlers, i - 1);

      g_assert (handler != NULL);
      g_assert (handler->closure != NULL);

      if (handler->closure->is_invalid)
        g_ptr_array_remove_index (self->handlers, i - 1);
    }
}

static void
dzl_signal_group__target_weak_notify (gpointer  data,
                                      GObject  *where_object_was)
{
  DzlSignalGroup *self = data;

  g_assert (DZL_IS_SIGNAL_GROUP (self));
  g_assert (where_object_was != NULL);

  g_weak_ref_set (&self->target_ref, NULL);

  for (guint i = 0; i < self->handlers->len; i++)
    {
      SignalHandler *handler = g_ptr_array_index (self->handlers, i);

      handler->handler_id = 0;
    }

  g_signal_emit (self, signals [UNBIND], 0);
  g_object_notify_by_pspec (G_OBJECT (self), properties [PROP_TARGET]);
}

static void
dzl_signal_group_bind_handler (DzlSignalGroup *self,
                               SignalHandler  *handler,
                               GObject        *target)
{
  g_assert (self != NULL);
  g_assert (G_IS_OBJECT (target));
  g_assert (handler != NULL);
  g_assert (handler->signal_id != 0);
  g_assert (handler->closure != NULL);
  g_assert (handler->closure->is_invalid == 0);
  g_assert (handler->handler_id == 0);

  handler->handler_id = g_signal_connect_closure_by_id (target,
                                                        handler->signal_id,
                                                        handler->signal_detail,
                                                        handler->closure,
                                                        handler->connect_after);

  g_assert (handler->handler_id != 0);

  for (guint i = 0; i < self->block_count; i++)
    g_signal_handler_block (target, handler->handler_id);
}

static void
dzl_signal_group_bind (DzlSignalGroup *self,
                       GObject        *target)
{
  g_autoptr(GObject) hold = NULL;

  g_assert (DZL_IS_SIGNAL_GROUP (self));
  g_assert (!target || G_IS_OBJECT (target));

  if (target == NULL)
    return;

  self->has_bound_at_least_once = TRUE;

  hold = g_object_ref (target);

  g_weak_ref_set (&self->target_ref, hold);
  g_object_weak_ref (hold, dzl_signal_group__target_weak_notify, self);

  dzl_signal_group_gc_handlers (self);

  for (guint i = 0; i < self->handlers->len; i++)
    {
      SignalHandler *handler = g_ptr_array_index (self->handlers, i);

      dzl_signal_group_bind_handler (self, handler, hold);
    }

  g_signal_emit (self, signals [BIND], 0, hold);
}

static void
dzl_signal_group_unbind (DzlSignalGroup *self)
{
  g_autoptr(GObject) target = NULL;

  g_return_if_fail (DZL_IS_SIGNAL_GROUP (self));

  target = g_weak_ref_get (&self->target_ref);

  /*
   * Target may be NULL by this point, as we got notified of its destruction.
   * However, if we're early enough, we may get a full reference back and can
   * cleanly disconnect our connections.
   */

  if (target != NULL)
    {
      g_weak_ref_set (&self->target_ref, NULL);

      /*
       * Let go of our weak reference now that we have a full reference
       * for the life of this function.
       */
      g_object_weak_unref (target,
                           dzl_signal_group__target_weak_notify,
                           self);
    }

  dzl_signal_group_gc_handlers (self);

  for (guint i = 0; i < self->handlers->len; i++)
    {
      SignalHandler *handler;
      gulong handler_id;

      handler = g_ptr_array_index (self->handlers, i);

      g_assert (handler != NULL);
      g_assert (handler->signal_id != 0);
      g_assert (handler->closure != NULL);

      handler_id = handler->handler_id;
      handler->handler_id = 0;

      /*
       * If @target is NULL, we lost a race to cleanup the weak
       * instance and the signal connections have already been
       * finalized and therefore nothing to do.
       */

      if (target != NULL && handler_id != 0)
        g_signal_handler_disconnect (target, handler_id);
    }

  g_signal_emit (self, signals [UNBIND], 0);
}

static gboolean
dzl_signal_group_check_target_type (DzlSignalGroup *self,
                                    gpointer        target)
{
  if ((target != NULL) &&
      !g_type_is_a (G_OBJECT_TYPE (target), self->target_type))
    {
      g_critical ("Failed to set DzlSignalGroup of target type %s "
                  "using target %p of type %s",
                  g_type_name (self->target_type),
                  target, G_OBJECT_TYPE_NAME (target));
      return FALSE;
    }

  return TRUE;
}

/**
 * dzl_signal_group_block:
 * @self: the #DzlSignalGroup
 *
 * Blocks all signal handlers managed by @self so they will not
 * be called during any signal emissions. Must be unblocked exactly
 * the same number of times it has been blocked to become active again.
 *
 * This blocked state will be kept across changes of the target instance.
 *
 * See: g_signal_handler_block().
 */
void
dzl_signal_group_block (DzlSignalGroup *self)
{
  g_autoptr(GObject) target = NULL;

  g_return_if_fail (DZL_IS_SIGNAL_GROUP (self));
  g_return_if_fail (self->block_count != G_MAXSIZE);

  self->block_count++;

  target = g_weak_ref_get (&self->target_ref);

  if (target == NULL)
    return;

  for (guint i = 0; i < self->handlers->len; i++)
    {
      const SignalHandler *handler = g_ptr_array_index (self->handlers, i);

      g_assert (handler != NULL);
      g_assert (handler->signal_id != 0);
      g_assert (handler->closure != NULL);
      g_assert (handler->handler_id != 0);

      g_signal_handler_block (target, handler->handler_id);
    }
}

/**
 * dzl_signal_group_unblock:
 * @self: the #DzlSignalGroup
 *
 * Unblocks all signal handlers managed by @self so they will be
 * called again during any signal emissions unless it is blocked
 * again. Must be unblocked exactly the same number of times it
 * has been blocked to become active again.
 *
 * See: g_signal_handler_unblock().
 */
void
dzl_signal_group_unblock (DzlSignalGroup *self)
{
  g_autoptr(GObject) target = NULL;

  g_return_if_fail (DZL_IS_SIGNAL_GROUP (self));
  g_return_if_fail (self->block_count != 0);

  self->block_count--;

  target = g_weak_ref_get (&self->target_ref);

  if (target == NULL)
    return;

  for (guint i = 0; i < self->handlers->len; i++)
    {
      const SignalHandler *handler = g_ptr_array_index (self->handlers, i);

      g_assert (handler != NULL);
      g_assert (handler->signal_id != 0);
      g_assert (handler->closure != NULL);
      g_assert (handler->handler_id != 0);

      g_signal_handler_unblock (target, handler->handler_id);
    }
}

/**
 * dzl_signal_group_get_target:
 * @self: the #DzlSignalGroup
 *
 * Gets the target instance used when connecting signals.
 *
 * Returns: (nullable) (transfer none) (type GObject): The target instance.
 */
gpointer
dzl_signal_group_get_target (DzlSignalGroup *self)
{
  g_autoptr(GObject) target = NULL;

  g_return_val_if_fail (DZL_IS_SIGNAL_GROUP (self), NULL);

  target = g_weak_ref_get (&self->target_ref);

  /*
   * It is expected that this is called from a thread that owns a reference to
   * the target, so we can pass back a borrowed reference. However, to ensure
   * that we aren't racing in finalization of @target, we must ensure that the
   * ref_count >= 2 (as our get just incremented by one).
   */

  if (target == NULL || target->ref_count < 2)
    return NULL;

  /* Unref and pass back a borrowed reference. This looks unsafe, but is safe
   * because of our reference check above, so much as the assertion holds that
   * the caller obeyed the ownership rules of this class.
   */
  return target;
}

/**
 * dzl_signal_group_set_target:
 * @self: the #DzlSignalGroup.
 * @target: (nullable) (type GObject): The target instance used
 *     when connecting signals.
 *
 * Sets the target instance used when connecting signals. Any signal
 * that has been registered with dzl_signal_group_connect_object() or
 * similar functions will be connected to this object.
 *
 * If the target instance was previously set, signals will be
 * disconnected from that object prior to connecting to @target.
 */
void
dzl_signal_group_set_target (DzlSignalGroup *self,
                             gpointer        target)
{
  g_autoptr(GObject) object = NULL;

  g_return_if_fail (DZL_IS_SIGNAL_GROUP (self));

  object = g_weak_ref_get (&self->target_ref);

  if (object == (GObject *)target)
    return;

  if (!dzl_signal_group_check_target_type (self, target))
    return;

  /* Only emit unbind if we've ever called bind */
  if (self->has_bound_at_least_once)
    dzl_signal_group_unbind (self);

  dzl_signal_group_bind (self, target);

  g_object_notify_by_pspec (G_OBJECT (self), properties [PROP_TARGET]);
}

static void
signal_handler_free (gpointer data)
{
  SignalHandler *handler = data;

  if (handler->closure != NULL)
    g_closure_invalidate (handler->closure);

  handler->handler_id = 0;
  handler->signal_id = 0;
  handler->signal_detail = 0;
  dzl_clear_pointer (&handler->closure, g_closure_unref);
  g_slice_free (SignalHandler, handler);
}

static void
dzl_signal_group_constructed (GObject *object)
{
  DzlSignalGroup *self = (DzlSignalGroup *)object;
  g_autoptr(GObject) target = g_weak_ref_get (&self->target_ref);

  if (!dzl_signal_group_check_target_type (self, target))
    dzl_signal_group_set_target (self, NULL);

  G_OBJECT_CLASS (dzl_signal_group_parent_class)->constructed (object);
}

static void
dzl_signal_group_dispose (GObject *object)
{
  DzlSignalGroup *self = (DzlSignalGroup *)object;

  dzl_signal_group_gc_handlers (self);

  if (self->has_bound_at_least_once)
    dzl_signal_group_unbind (self);

  dzl_clear_pointer (&self->handlers, g_ptr_array_unref);

  G_OBJECT_CLASS (dzl_signal_group_parent_class)->dispose (object);
}

static void
dzl_signal_group_finalize (GObject *object)
{
  DzlSignalGroup *self = (DzlSignalGroup *)object;

  g_weak_ref_clear (&self->target_ref);

  G_OBJECT_CLASS (dzl_signal_group_parent_class)->finalize (object);
}

static void
dzl_signal_group_get_property (GObject    *object,
                               guint       prop_id,
                               GValue     *value,
                               GParamSpec *pspec)
{
  DzlSignalGroup *self = DZL_SIGNAL_GROUP (object);

  switch (prop_id)
    {
    case PROP_TARGET:
      g_value_take_object (value, g_weak_ref_get (&self->target_ref));
      break;

    case PROP_TARGET_TYPE:
      g_value_set_gtype (value, self->target_type);
      break;

    default:
      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
    }
}

static void
dzl_signal_group_set_property (GObject      *object,
                               guint         prop_id,
                               const GValue *value,
                               GParamSpec   *pspec)
{
  DzlSignalGroup *self = DZL_SIGNAL_GROUP (object);

  switch (prop_id)
    {
    case PROP_TARGET:
      dzl_signal_group_set_target (self, g_value_get_object (value));
      break;

    case PROP_TARGET_TYPE:
      dzl_signal_group_set_target_type (self, g_value_get_gtype (value));
      break;

    default:
      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
    }
}

static void
dzl_signal_group_class_init (DzlSignalGroupClass *klass)
{
  GObjectClass *object_class = G_OBJECT_CLASS (klass);

  object_class->constructed = dzl_signal_group_constructed;
  object_class->dispose = dzl_signal_group_dispose;
  object_class->finalize = dzl_signal_group_finalize;
  object_class->get_property = dzl_signal_group_get_property;
  object_class->set_property = dzl_signal_group_set_property;

  /**
   * DzlSignalGroup:target
   *
   * The target instance used when connecting signals.
   */
  properties [PROP_TARGET] =
    g_param_spec_object ("target",
                         "Target",
                         "The target instance used when connecting signals.",
                         G_TYPE_OBJECT,
                         (G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY | G_PARAM_STATIC_STRINGS));

  /**
   * DzlSignalGroup:target-type
   *
   * The GType of the target property.
   */
  properties [PROP_TARGET_TYPE] =
    g_param_spec_gtype ("target-type",
                        "Target Type",
                        "The GType of the target property.",
                        G_TYPE_OBJECT,
                        (G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));

  g_object_class_install_properties (object_class, LAST_PROP, properties);

  /**
   * DzlSignalGroup::bind:
   * @self: the #DzlSignalGroup
   * @instance: a #GObject
   *
   * This signal is emitted when the target instance of @self
   * is set to a new #GObject.
   *
   * This signal will only be emitted if the target of @self is non-%NULL.
   */
  signals [BIND] =
    g_signal_new ("bind",
                  G_TYPE_FROM_CLASS (klass),
                  G_SIGNAL_RUN_LAST,
                  0,
                  NULL, NULL, NULL,
                  G_TYPE_NONE,
                  1,
                  G_TYPE_OBJECT);

  /**
   * DzlSignalGroup::unbind:
   * @self: a #DzlSignalGroup
   *
   * This signal is emitted when the target instance of @self
   * is set to a new #GObject.
   *
   * This signal will only be emitted if the previous target
   * of @self is non-%NULL.
   */
  signals [UNBIND] =
    g_signal_new ("unbind",
                  G_TYPE_FROM_CLASS (klass),
                  G_SIGNAL_RUN_LAST,
                  0,
                  NULL, NULL, NULL,
                  G_TYPE_NONE,
                  0);
}

static void
dzl_signal_group_init (DzlSignalGroup *self)
{
  self->handlers = g_ptr_array_new_with_free_func (signal_handler_free);
  self->target_type = G_TYPE_OBJECT;
}

/**
 * dzl_signal_group_new:
 * @target_type: the #GType of the target instance.
 *
 * Creates a new #DzlSignalGroup for target instances of @target_type.
 *
 * Returns: a new #DzlSignalGroup
 */
DzlSignalGroup *
dzl_signal_group_new (GType target_type)
{
  g_return_val_if_fail (g_type_is_a (target_type, G_TYPE_OBJECT), NULL);

  return g_object_new (DZL_TYPE_SIGNAL_GROUP,
                       "target-type", target_type,
                       NULL);
}

static void
dzl_signal_group_connect_full (DzlSignalGroup *self,
                               const gchar    *detailed_signal,
                               GCallback       callback,
                               gpointer        data,
                               GClosureNotify  notify,
                               GConnectFlags   flags,
                               gboolean        is_object)
{
  g_autoptr(GObject) target = NULL;
  SignalHandler *handler;
  GClosure *closure;
  guint signal_id;
  GQuark signal_detail;

  g_return_if_fail (DZL_IS_SIGNAL_GROUP (self));
  g_return_if_fail (detailed_signal != NULL);
  g_return_if_fail (g_signal_parse_name (detailed_signal, self->target_type,
                                         &signal_id, &signal_detail, TRUE) != 0);
  g_return_if_fail (callback != NULL);
  g_return_if_fail (!is_object || G_IS_OBJECT (data));

  if ((flags & G_CONNECT_SWAPPED) != 0)
    closure = g_cclosure_new_swap (callback, data, notify);
  else
    closure = g_cclosure_new (callback, data, notify);

  handler = g_slice_new0 (SignalHandler);
  handler->group = self;
  handler->signal_id = signal_id;
  handler->signal_detail = signal_detail;
  handler->closure = g_closure_ref (closure);
  handler->connect_after = ((flags & G_CONNECT_AFTER) != 0);

  g_closure_sink (closure);

  if (is_object)
    {
      /* Set closure->is_invalid when data is disposed. We only track this to avoid
       * reconnecting in the future. However, we do a round of cleanup when ever we
       * connect a new object or the target changes to GC the old handlers.
       */
      g_object_watch_closure (data, closure);
    }

  g_ptr_array_add (self->handlers, handler);

  target = g_weak_ref_get (&self->target_ref);
  if (target != NULL)
    dzl_signal_group_bind_handler (self, handler, target);

  /* Lazily remove any old handlers on connect */
  dzl_signal_group_gc_handlers (self);
}

/**
 * dzl_signal_group_connect_object: (skip)
 * @self: a #DzlSignalGroup
 * @detailed_signal: a string of the form "signal-name::detail"
 * @c_handler: (scope notified): the #GCallback to connect
 * @object: the #GObject to pass as data to @callback calls
 *
 * Connects @callback to the signal @detailed_signal
 * on the target object of @self.
 *
 * Ensures that the @object stays alive during the call to @callback
 * by temporarily adding a reference count. When the @object is destroyed
 * the signal handler will automatically be removed.
 *
 * See: g_signal_connect_object().
 */
void
dzl_signal_group_connect_object (DzlSignalGroup *self,
                                 const gchar    *detailed_signal,
                                 GCallback       c_handler,
                                 gpointer        object,
                                 GConnectFlags   flags)
{
  g_return_if_fail (G_IS_OBJECT (object));

  dzl_signal_group_connect_full (self, detailed_signal, c_handler, object, NULL,
                                 flags, TRUE);
}

/**
 * dzl_signal_group_connect_data:
 * @self: a #DzlSignalGroup
 * @detailed_signal: a string of the form "signal-name::detail"
 * @c_handler: (scope notified) (closure data) (destroy notify): the #GCallback to connect
 * @data: the data to pass to @callback calls
 * @notify: function to be called when disposing of @self
 * @flags: the flags used to create the signal connection
 *
 * Connects @callback to the signal @detailed_signal
 * on the target instance of @self.
 *
 * See: g_signal_connect_data().
 */
void
dzl_signal_group_connect_data (DzlSignalGroup *self,
                               const gchar    *detailed_signal,
                               GCallback       c_handler,
                               gpointer        data,
                               GClosureNotify  notify,
                               GConnectFlags   flags)
{
  dzl_signal_group_connect_full (self, detailed_signal, c_handler, data, notify,
                                 flags, FALSE);
}

/**
 * dzl_signal_group_connect: (skip)
 * @self: a #DzlSignalGroup
 * @detailed_signal: a string of the form "signal-name::detail"
 * @c_handler: (scope notified): the #GCallback to connect
 * @data: the data to pass to @callback calls
 *
 * Connects @callback to the signal @detailed_signal
 * on the target instance of @self.
 *
 * See: g_signal_connect().
 */
void
dzl_signal_group_connect (DzlSignalGroup *self,
                          const gchar    *detailed_signal,
                          GCallback       c_handler,
                          gpointer        data)
{
  dzl_signal_group_connect_full (self, detailed_signal, c_handler, data, NULL,
                                 0, FALSE);
}

/**
 * dzl_signal_group_connect_after: (skip)
 * @self: a #DzlSignalGroup
 * @detailed_signal: a string of the form "signal-name::detail"
 * @c_handler: (scope notified): the #GCallback to connect
 * @data: the data to pass to @callback calls
 *
 * Connects @callback to the signal @detailed_signal
 * on the target instance of @self.
 *
 * The @callback will be called after the default handler of the signal.
 *
 * See: g_signal_connect_after().
 */
void
dzl_signal_group_connect_after (DzlSignalGroup *self,
                                const gchar    *detailed_signal,
                                GCallback       c_handler,
                                gpointer        data)
{
  dzl_signal_group_connect_full (self, detailed_signal, c_handler,
                                 data, NULL, G_CONNECT_AFTER, FALSE);
}

/**
 * dzl_signal_group_connect_swapped:
 * @self: a #DzlSignalGroup
 * @detailed_signal: a string of the form "signal-name::detail"
 * @c_handler: (scope async): the #GCallback to connect
 * @data: the data to pass to @callback calls
 *
 * Connects @callback to the signal @detailed_signal
 * on the target instance of @self.
 *
 * The instance on which the signal is emitted and @data
 * will be swapped when calling @callback.
 *
 * See: g_signal_connect_swapped().
 */
void
dzl_signal_group_connect_swapped (DzlSignalGroup *self,
                                  const gchar    *detailed_signal,
                                  GCallback       c_handler,
                                  gpointer        data)
{
  dzl_signal_group_connect_full (self, detailed_signal, c_handler, data, NULL,
                                 G_CONNECT_SWAPPED, FALSE);
}
