gimp/app/core/gimpasync.c

/* GIMP - The GNU Image Manipulation Program
 * Copyright (C) 1995 Spencer Kimball and Peter Mattis
 *
 * gimpasync.c
 * Copyright (C) 2018 Ell
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program 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 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 <https://www.gnu.org/licenses/>.
 */

#include "config.h"

#include <gdk-pixbuf/gdk-pixbuf.h>
#include <gegl.h>

#include "core-types.h"

#include "gimpasync.h"
#include "gimpcancelable.h"
#include "gimpwaitable.h"


/* GimpAsync represents an asynchronous task.  Both the public and the
 * protected interfaces are intentionally minimal at this point, to keep things
 * simple.  They may be extended in the future as needed.
 *
 * GimpAsync implements the GimpWaitable and GimpCancelable interfaces.
 *
 * Upon creation, a GimpAsync object is in the "running" state.  Once the task
 * is complete (and before the object's destruction), it should be transitioned
 * to the "stopped" state, using either 'gimp_async_finish()' or
 * 'gimp_async_abort()'.
 *
 * Similarly, upon creation, a GimpAsync object is said to be "unsynced".  It
 * becomes synced once the execution of any of the completion callbacks added
 * through 'gimp_async_add_callback()' had started, or after a successful call
 * to one of the 'gimp_waitable_wait()' family of functions.
 *
 * Note that certain GimpAsync functions may only be called during a certain
 * state, on a certain thread, or depending on whether or not the object is
 * synced, as detailed for each function.  When referring to threads, the "main
 * thread" is the thread running the main loop, or any thread whose execution
 * is synchronized with the main thread, and the "async thread" is the thread
 * calling 'gimp_async_finish()' or 'gimp_async_abort()' (which may also be the
 * main thread), or any thread whose execution is synchronized with the async
 * thread.
 */


/* #define TIME_ASYNC_OPS */


enum
{
  WAITING,
  LAST_SIGNAL
};


typedef struct _GimpAsyncCallbackInfo GimpAsyncCallbackInfo;


struct _GimpAsyncCallbackInfo
{
  GimpAsync         *async;
  GimpAsyncCallback  callback;
  gpointer           data;
  gpointer           gobject;
};

struct _GimpAsyncPrivate
{
  GMutex         mutex;
  GCond          cond;

  GQueue         callbacks;

  gpointer       result;
  GDestroyNotify result_destroy_func;

  guint          idle_id;

  gboolean       stopped;
  gboolean       finished;
  gboolean       synced;
  gboolean       canceled;

#ifdef TIME_ASYNC_OPS
  guint64        start_time;
#endif
};


/*  local function prototypes  */

static void       gimp_async_waitable_iface_init   (GimpWaitableInterface   *iface);

static void       gimp_async_cancelable_iface_init (GimpCancelableInterface *iface);

static void       gimp_async_finalize              (GObject                 *object);

static void       gimp_async_wait                  (GimpWaitable            *waitable);
static gboolean   gimp_async_try_wait              (GimpWaitable            *waitable);
static gboolean   gimp_async_wait_until            (GimpWaitable            *waitable,
                                                    gint64                   end_time);

static void       gimp_async_cancel                (GimpCancelable          *cancelable);

static gboolean   gimp_async_idle                  (GimpAsync               *async);

static void       gimp_async_callback_weak_notify  (GimpAsyncCallbackInfo   *callback_info,
                                                    GObject                 *gobject);

static void       gimp_async_stop                  (GimpAsync               *async);
static void       gimp_async_run_callbacks         (GimpAsync               *async);


G_DEFINE_TYPE_WITH_CODE (GimpAsync, gimp_async, G_TYPE_OBJECT,
                         G_ADD_PRIVATE (GimpAsync)
                         G_IMPLEMENT_INTERFACE (GIMP_TYPE_WAITABLE,
                                                gimp_async_waitable_iface_init)
                         G_IMPLEMENT_INTERFACE (GIMP_TYPE_CANCELABLE,
                                                gimp_async_cancelable_iface_init))

#define parent_class gimp_async_parent_class

static guint async_signals[LAST_SIGNAL] = { 0 };


/*  local variables  */

static volatile gint gimp_async_n_running = 0;


/*  private functions  */


static void
gimp_async_class_init (GimpAsyncClass *klass)
{
  GObjectClass *object_class = G_OBJECT_CLASS (klass);

  async_signals[WAITING] =
    g_signal_new ("waiting",
                  G_TYPE_FROM_CLASS (klass),
                  G_SIGNAL_RUN_FIRST,
                  G_STRUCT_OFFSET (GimpAsyncClass, waiting),
                  NULL, NULL, NULL,
                  G_TYPE_NONE, 0);

  object_class->finalize = gimp_async_finalize;
}

static void
gimp_async_waitable_iface_init (GimpWaitableInterface *iface)
{
  iface->wait       = gimp_async_wait;
  iface->try_wait   = gimp_async_try_wait;
  iface->wait_until = gimp_async_wait_until;
}

static void
gimp_async_cancelable_iface_init (GimpCancelableInterface *iface)
{
  iface->cancel = gimp_async_cancel;
}

static void
gimp_async_init (GimpAsync *async)
{
  async->priv = gimp_async_get_instance_private (async);

  g_mutex_init (&async->priv->mutex);
  g_cond_init  (&async->priv->cond);

  g_queue_init (&async->priv->callbacks);

  g_atomic_int_inc (&gimp_async_n_running);

#ifdef TIME_ASYNC_OPS
  async->priv->start_time = g_get_monotonic_time ();
#endif
}

static void
gimp_async_finalize (GObject *object)
{
  GimpAsync *async = GIMP_ASYNC (object);

  g_warn_if_fail (async->priv->stopped);
  g_warn_if_fail (async->priv->idle_id == 0);
  g_warn_if_fail (g_queue_is_empty (&async->priv->callbacks));

  if (async->priv->finished &&
      async->priv->result   &&
      async->priv->result_destroy_func)
    {
      async->priv->result_destroy_func (async->priv->result);

      async->priv->result = NULL;
    }

  g_cond_clear  (&async->priv->cond);
  g_mutex_clear (&async->priv->mutex);

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

/* waits for 'waitable' to transition to the "stopped" state.  if 'waitable' is
 * already stopped, returns immediately.
 *
 * after the call, all callbacks previously added through
 * 'gimp_async_add_callback()' are guaranteed to have been called.
 *
 * may only be called on the main thread.
 */
static void
gimp_async_wait (GimpWaitable *waitable)
{
  GimpAsync *async = GIMP_ASYNC (waitable);

  g_mutex_lock (&async->priv->mutex);

  if (! async->priv->stopped)
    {
      g_signal_emit (async, async_signals[WAITING], 0);

      while (! async->priv->stopped)
        g_cond_wait (&async->priv->cond, &async->priv->mutex);
    }

  g_mutex_unlock (&async->priv->mutex);

  gimp_async_run_callbacks (async);
}

/* same as 'gimp_async_wait()', but returns immediately if 'waitable' is not in
 * the "stopped" state.
 *
 * returns TRUE if 'waitable' has transitioned to the "stopped" state, or FALSE
 * otherwise.
 */
static gboolean
gimp_async_try_wait (GimpWaitable *waitable)
{
  GimpAsync *async = GIMP_ASYNC (waitable);

  g_mutex_lock (&async->priv->mutex);

  if (! async->priv->stopped)
    {
      g_mutex_unlock (&async->priv->mutex);

      return FALSE;
    }

  g_mutex_unlock (&async->priv->mutex);

  gimp_async_run_callbacks (async);

  return TRUE;
}

/* same as 'gimp_async_wait()', taking an additional 'end_time' parameter,
 * specifying the maximal monotonic time until which to wait for 'waitable' to
 * stop.
 *
 * returns TRUE if 'waitable' has transitioned to the "stopped" state, or FALSE
 * if the wait was interrupted before the transition.
 */
static gboolean
gimp_async_wait_until (GimpWaitable *waitable,
                       gint64        end_time)
{
  GimpAsync *async = GIMP_ASYNC (waitable);

  g_mutex_lock (&async->priv->mutex);

  if (! async->priv->stopped)
    {
      g_signal_emit (async, async_signals[WAITING], 0);

      while (! async->priv->stopped)
        {
          if (! g_cond_wait_until (&async->priv->cond, &async->priv->mutex,
                                   end_time))
            {
              g_mutex_unlock (&async->priv->mutex);

              return FALSE;
            }
        }
    }

  g_mutex_unlock (&async->priv->mutex);

  gimp_async_run_callbacks (async);

  return TRUE;
}

/* requests the cancellation of the task managed by 'cancelable'.
 *
 * note that 'gimp_async_cancel()' doesn't directly cause 'cancelable' to be
 * stopped, nor synced.  furthermore, 'cancelable' may still complete
 * successfully even when cancellation has been requested.
 *
 * may only be called on the main thread.
 */
static void
gimp_async_cancel (GimpCancelable *cancelable)
{
  GimpAsync *async = GIMP_ASYNC (cancelable);

  async->priv->canceled = TRUE;
}

static gboolean
gimp_async_idle (GimpAsync *async)
{
  gimp_waitable_wait (GIMP_WAITABLE (async));

  return G_SOURCE_REMOVE;
}

static void
gimp_async_callback_weak_notify (GimpAsyncCallbackInfo *callback_info,
                                 GObject               *gobject)
{
  GimpAsync *async       = callback_info->async;
  gboolean   unref_async = FALSE;

  g_mutex_lock (&async->priv->mutex);

  g_queue_remove (&async->priv->callbacks, callback_info);

  g_slice_free (GimpAsyncCallbackInfo, callback_info);

  if (g_queue_is_empty (&async->priv->callbacks) && async->priv->idle_id)
    {
      g_source_remove (async->priv->idle_id);
      async->priv->idle_id = 0;

      unref_async = TRUE;
    }

  g_mutex_unlock (&async->priv->mutex);

  if (unref_async)
    g_object_unref (async);
}

static void
gimp_async_stop (GimpAsync *async)
{
#ifdef TIME_ASYNC_OPS
  {
    guint64 time = g_get_monotonic_time ();

    g_printerr ("Asynchronous operation took %g seconds%s\n",
                (time - async->priv->start_time) / 1000000.0,
                async->priv->finished ? "" : " (aborted)");
  }
#endif

  g_atomic_int_dec_and_test (&gimp_async_n_running);

  if (! g_queue_is_empty (&async->priv->callbacks))
    {
      g_object_ref (async);

      async->priv->idle_id = g_idle_add_full (G_PRIORITY_DEFAULT,
                                              (GSourceFunc) gimp_async_idle,
                                              async, NULL);
    }

  async->priv->stopped = TRUE;

  g_cond_broadcast (&async->priv->cond);
}

static void
gimp_async_run_callbacks (GimpAsync *async)
{
  GimpAsyncCallbackInfo *callback_info;
  gboolean               unref_async = FALSE;

  if (async->priv->idle_id)
    {
      g_source_remove (async->priv->idle_id);
      async->priv->idle_id = 0;

      unref_async = TRUE;
    }

  async->priv->synced = TRUE;

  while ((callback_info = g_queue_pop_head (&async->priv->callbacks)))
    {
      if (callback_info->gobject)
        {
          g_object_ref (callback_info->gobject);

          g_object_weak_unref (callback_info->gobject,
                               (GWeakNotify) gimp_async_callback_weak_notify,
                               callback_info);
        }

      callback_info->callback (async, callback_info->data);

      if (callback_info->gobject)
        g_object_unref (callback_info->gobject);

      g_slice_free (GimpAsyncCallbackInfo, callback_info);
    }

  if (unref_async)
    g_object_unref (async);
}


/*  public functions  */


/* creates a new GimpAsync object, initially unsynced and placed in the
 * "running" state.
 */
GimpAsync *
gimp_async_new (void)
{
  return g_object_new (GIMP_TYPE_ASYNC,
                       NULL);
}

/* checks if 'async' is synced.
 *
 * may only be called on the main thread.
 */
gboolean
gimp_async_is_synced (GimpAsync *async)
{
  g_return_val_if_fail (GIMP_IS_ASYNC (async), FALSE);

  return async->priv->synced;
}

/* registers a callback to be called when 'async' transitions to the "stopped"
 * state.  if 'async' is already stopped, the callback may be called directly.
 *
 * callbacks are called in the order in which they were added.  'async' is
 * guaranteed to be kept alive, even without an external reference, between the
 * point where it was stopped, and until all callbacks added while 'async' was
 * externally referenced have been called.
 *
 * the callback is guaranteed to be called on the main thread.
 *
 * may only be called on the main thread.
 */
void
gimp_async_add_callback (GimpAsync         *async,
                         GimpAsyncCallback  callback,
                         gpointer           data)
{
  GimpAsyncCallbackInfo *callback_info;

  g_return_if_fail (GIMP_IS_ASYNC (async));
  g_return_if_fail (callback != NULL);

  g_mutex_lock (&async->priv->mutex);

  if (async->priv->stopped && g_queue_is_empty (&async->priv->callbacks))
    {
      async->priv->synced = TRUE;

      g_mutex_unlock (&async->priv->mutex);

      callback (async, data);

      return;
    }

  callback_info           = g_slice_new0 (GimpAsyncCallbackInfo);
  callback_info->async    = async;
  callback_info->callback = callback;
  callback_info->data     = data;

  g_queue_push_tail (&async->priv->callbacks, callback_info);

  g_mutex_unlock (&async->priv->mutex);
}

/* same as 'gimp_async_add_callback()', however, takes an additional 'gobject'
 * argument, which should be a GObject.
 *
 * 'gobject' is guaranteed to remain alive for the duration of the callback.
 *
 * When 'gobject' is destroyed, the callback is automatically removed.
 */
void
gimp_async_add_callback_for_object (GimpAsync         *async,
                                    GimpAsyncCallback  callback,
                                    gpointer           data,
                                    gpointer           gobject)
{
  GimpAsyncCallbackInfo *callback_info;

  g_return_if_fail (GIMP_IS_ASYNC (async));
  g_return_if_fail (callback != NULL);
  g_return_if_fail (G_IS_OBJECT (gobject));

  g_mutex_lock (&async->priv->mutex);

  if (async->priv->stopped && g_queue_is_empty (&async->priv->callbacks))
    {
      async->priv->synced = TRUE;

      g_mutex_unlock (&async->priv->mutex);

      g_object_ref (gobject);

      callback (async, data);

      g_object_unref (gobject);

      return;
    }

  callback_info           = g_slice_new0 (GimpAsyncCallbackInfo);
  callback_info->async    = async;
  callback_info->callback = callback;
  callback_info->data     = data;
  callback_info->gobject  = gobject;

  g_queue_push_tail (&async->priv->callbacks, callback_info);

  g_object_weak_ref (gobject,
                     (GWeakNotify) gimp_async_callback_weak_notify,
                     callback_info);

  g_mutex_unlock (&async->priv->mutex);
}

/* removes all callbacks previously registered through
 * 'gimp_async_add_callback()', matching 'callback' and 'data', which hasn't
 * been called yet.
 *
 * may only be called on the main thread.
 */
void
gimp_async_remove_callback (GimpAsync         *async,
                            GimpAsyncCallback  callback,
                            gpointer           data)
{
  GList    *iter;
  gboolean  unref_async = FALSE;

  g_return_if_fail (GIMP_IS_ASYNC (async));
  g_return_if_fail (callback != NULL);

  g_mutex_lock (&async->priv->mutex);

  iter = g_queue_peek_head_link (&async->priv->callbacks);

  while (iter)
    {
      GimpAsyncCallbackInfo *callback_info = iter->data;
      GList                 *next          = g_list_next (iter);

      if (callback_info->callback == callback &&
          callback_info->data     == data)
        {
          if (callback_info->gobject)
            {
              g_object_weak_unref (
                callback_info->gobject,
                (GWeakNotify) gimp_async_callback_weak_notify,
                callback_info);
            }

          g_queue_delete_link (&async->priv->callbacks, iter);

          g_slice_free (GimpAsyncCallbackInfo, callback_info);
        }

      iter = next;
    }

  if (g_queue_is_empty (&async->priv->callbacks) && async->priv->idle_id)
    {
      g_source_remove (async->priv->idle_id);
      async->priv->idle_id = 0;

      unref_async = TRUE;
    }

  g_mutex_unlock (&async->priv->mutex);

  if (unref_async)
    g_object_unref (async);
}

/* checks if 'async' is in the "stopped" state.
 *
 * may only be called on the async thread.
 */
gboolean
gimp_async_is_stopped (GimpAsync *async)
{
  g_return_val_if_fail (GIMP_IS_ASYNC (async), FALSE);

  return async->priv->stopped;
}

/* transitions 'async' to the "stopped" state, indicating that the task
 * completed normally, possibly providing a result.
 *
 * 'async' shall be in the "running" state.
 *
 * may only be called on the async thread.
 */
void
gimp_async_finish (GimpAsync *async,
                   gpointer   result)
{
  gimp_async_finish_full (async, result, NULL);
}

/* same as 'gimp_async_finish()', taking an additional GDestroyNotify function,
 * used for freeing the result when 'async' is destroyed.
 */
void
gimp_async_finish_full (GimpAsync      *async,
                        gpointer        result,
                        GDestroyNotify  result_destroy_func)
{
  g_return_if_fail (GIMP_IS_ASYNC (async));
  g_return_if_fail (! async->priv->stopped);

  g_mutex_lock (&async->priv->mutex);

  async->priv->finished            = TRUE;
  async->priv->result              = result;
  async->priv->result_destroy_func = result_destroy_func;

  gimp_async_stop (async);

  g_mutex_unlock (&async->priv->mutex);
}

/* checks if 'async' completed normally, using 'gimp_async_finish()' (in
 * contrast to 'gimp_async_abort()').
 *
 * 'async' shall be in the "stopped" state.
 *
 * may only be called on the async thread, or on the main thread when 'async'
 * is synced.
 */
gboolean
gimp_async_is_finished (GimpAsync *async)
{
  g_return_val_if_fail (GIMP_IS_ASYNC (async), FALSE);
  g_return_val_if_fail (async->priv->stopped, FALSE);

  return async->priv->finished;
}

/* returns the result of 'async', as passed to 'gimp_async_finish()'.
 *
 * 'async' shall be in the "stopped" state, and should have completed normally.
 *
 * may only be called on the async thread, or on the main thread when 'async'
 * is synced.
 */
gpointer
gimp_async_get_result (GimpAsync *async)
{
  g_return_val_if_fail (GIMP_IS_ASYNC (async), NULL);
  g_return_val_if_fail (async->priv->stopped, NULL);
  g_return_val_if_fail (async->priv->finished, NULL);

  return async->priv->result;
}

/* transitions 'async' to the "stopped" state, indicating that the task
 * was stopped before completion (normally, in response to a
 * 'gimp_cancelable_cancel()' call).
 *
 * 'async' shall be in the "running" state.
 *
 * may only be called on the async thread.
 */
void
gimp_async_abort (GimpAsync *async)
{
  g_return_if_fail (GIMP_IS_ASYNC (async));
  g_return_if_fail (! async->priv->stopped);

  g_mutex_lock (&async->priv->mutex);

  gimp_async_stop (async);

  g_mutex_unlock (&async->priv->mutex);
}

/* checks if cancellation of 'async' has been requested.
 *
 * note that a return value of TRUE only indicates that
 * 'gimp_cancelable_cancel()' has been called for 'async', and not that 'async'
 * is stopped, or, if it is stopped, that it was aborted.
 */
gboolean
gimp_async_is_canceled (GimpAsync *async)
{
  g_return_val_if_fail (GIMP_IS_ASYNC (async), FALSE);

  return async->priv->canceled;
}

/* a convenience function, canceling 'async' and waiting for it to stop.
 *
 * may only be called on the main thread.
 */
void
gimp_async_cancel_and_wait (GimpAsync *async)
{
  g_return_if_fail (GIMP_IS_ASYNC (async));

  gimp_cancelable_cancel (GIMP_CANCELABLE (async));
  gimp_waitable_wait (GIMP_WAITABLE (async));
}


/*  public functions (stats)  */


gint
gimp_async_get_n_running (void)
{
  return gimp_async_n_running;
}