/* GLIB - Library of useful routines for C programming

 * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald

 *

 * GHook: Callback maintenance functions

 * Copyright (C) 1998 Tim Janik

 *

 * This library 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 of the License, or (at your option) any later version.

 *

 * This library 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 Lesser General Public

 * License along with this library; if not, write to the

 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,

 * Boston, MA 02111-1307, USA.

 */

/*

 * Modified by the GLib Team and others 1997-2000.  See the AUTHORS

 * file for a list of people on the GLib Team.  See the ChangeLog

 * files for a list of changes.  These files are distributed with

 * GLib at ftp://ftp.gtk.org/pub/gtk/.

 */

/*

 * MT safe

 */

#include "config.h"

#include "ghook.h"

#include "gtestutils.h"

#include "gslice.h"

/**

 * SECTION:hooks

 * @title: Hook Functions

 * @short_description: support for manipulating lists of hook functions

 *

 * The #GHookList, #GHook and their related functions provide support for

 * lists of hook functions. Functions can be added and removed from the lists,

 * and the list of hook functions can be invoked.

 */

/**

 * GHookList:

 * @seq_id: the next free #GHook id

 * @hook_size: the size of the #GHookList elements, in bytes

 * @is_setup: 1 if the #GHookList has been initialized

 * @hooks: the first #GHook element in the list

 * @dummy3: unused

 * @finalize_hook: the function to call to finalize a #GHook element.

 *     The default behaviour is to call the hooks @destroy function

 * @dummy: unused

 *

 * The <structname>GHookList</structname> struct represents a

 * list of hook functions.

 */

/**

 * GHookFinalizeFunc:

 * @hook_list: a #GHookList

 * @hook: the hook in @hook_list that gets finalized

 *

 * Defines the type of function to be called when a hook in a

 * list of hooks gets finalized.

 */

/**

 * GHookFlagMask:

 * @G_HOOK_FLAG_ACTIVE: set if the hook has not been destroyed

 * @G_HOOK_FLAG_IN_CALL: set if the hook is currently being run

 * @G_HOOK_FLAG_MASK: A mask covering all bits reserved for

 *   hook flags; see %G_HOOK_FLAG_USER_SHIFT

 *

 * Flags used internally in the #GHook implementation.

 */

/**

 * G_HOOK_FLAGS:

 * @hook: a #GHook

 *

 * Gets the flags of a hook.

 */

/**

 * G_HOOK_FLAG_USER_SHIFT:

 *

 * The position of the first bit which is not reserved for internal

 * use be the #GHook implementation, i.e.

 * <literal>1 << G_HOOK_FLAG_USER_SHIFT</literal> is the first

 * bit which can be used for application-defined flags.

 */

/**

 * G_HOOK:

 * @hook: a pointer

 *

 * Casts a pointer to a <literal>GHook*</literal>.

 */

/**

 * G_HOOK_IS_VALID:

 * @hook: a #GHook

 *

 * Returns %TRUE if the #GHook is valid, i.e. it is in a #GHookList,

 * it is active and it has not been destroyed.

 *

 * Returns: %TRUE if the #GHook is valid

 */

/**

 * G_HOOK_ACTIVE:

 * @hook: a #GHook

 *

 * Returns %TRUE if the #GHook is active, which is normally the case

 * until the #GHook is destroyed.

 *

 * Returns: %TRUE if the #GHook is active

 */

/**

 * G_HOOK_IN_CALL:

 * @hook: a #GHook

 *

 * Returns %TRUE if the #GHook function is currently executing.

 *

 * Returns: %TRUE if the #GHook function is currently executing

 */

/**

 * G_HOOK_IS_UNLINKED:

 * @hook: a #GHook

 *

 * Returns %TRUE if the #GHook is not in a #GHookList.

 * Returns: %TRUE if the #GHook is not in a #GHookList

 */

/**

 * GHook:

 * @data: data which is passed to func when this hook is invoked

 * @next: pointer to the next hook in the list

 * @prev: pointer to the previous hook in the list

 * @ref_count: the reference count of this hook

 * @hook_id: the id of this hook, which is unique within its list

 * @flags: flags which are set for this hook. See #GHookFlagMask for

 *     predefined flags

 * @func: the function to call when this hook is invoked. The possible

 *     signatures for this function are #GHookFunc and #GHookCheckFunc

 * @destroy: the default @finalize_hook function of a #GHookList calls

 *     this member of the hook that is being finalized

 *

 * The <structname>GHook</structname> struct represents a single hook

 * function in a #GHookList.

 */

/**

 * GHookFunc:

 * @data: the data field of the #GHook is passed to the hook function here

 *

 * Defines the type of a hook function that can be invoked

 * by g_hook_list_invoke().

 */

/**

 * GHookCheckFunc:

 * @data: the data field of the #GHook is passed to the hook function here

 *

 * Defines the type of a hook function that can be invoked

 * by g_hook_list_invoke_check().

 *

 * Returns: %FALSE if the #GHook should be destroyed

 */

/* --- functions --- */

static void

default_finalize_hook (GHookList *hook_list,

		       GHook     *hook)

{

  GDestroyNotify destroy = hook->destroy;

  if (destroy)

    {

      hook->destroy = NULL;

      destroy (hook->data);

    }

}

/**

 * g_hook_list_init:

 * @hook_list: a #GHookList

 * @hook_size: the size of each element in the #GHookList,

 *     typically <literal>sizeof (GHook)</literal>

 *

 * Initializes a #GHookList.

 * This must be called before the #GHookList is used.

 */

void

g_hook_list_init (GHookList *hook_list,

		  guint	     hook_size)

{

  g_return_if_fail (hook_list != NULL);

  g_return_if_fail (hook_size >= sizeof (GHook));

  hook_list->seq_id = 1;

  hook_list->hook_size = hook_size;

  hook_list->is_setup = TRUE;

  hook_list->hooks = NULL;

  hook_list->dummy3 = NULL;

  hook_list->finalize_hook = default_finalize_hook;

  hook_list->dummy[0] = NULL;

  hook_list->dummy[1] = NULL;

}

/**

 * g_hook_list_clear:

 * @hook_list: a #GHookList

 *

 * Removes all the #GHook elements from a #GHookList.

 */

void

g_hook_list_clear (GHookList *hook_list)

{

  g_return_if_fail (hook_list != NULL);

  if (hook_list->is_setup)

    {

      GHook *hook;

      hook_list->is_setup = FALSE;

      hook = hook_list->hooks;

      if (!hook)

	{

	  /* destroy hook_list->hook_memchunk */

	}

      else

	do

	  {

	    GHook *tmp;

	    g_hook_ref (hook_list, hook);

	    g_hook_destroy_link (hook_list, hook);

	    tmp = hook->next;

	    g_hook_unref (hook_list, hook);

	    hook = tmp;

	  }

	while (hook);

    }

}

/**

 * g_hook_alloc:

 * @hook_list: a #GHookList

 *

 * Allocates space for a #GHook and initializes it.

 *

 * Returns: a new #GHook

 */

GHook*

g_hook_alloc (GHookList *hook_list)

{

  GHook *hook;

  g_return_val_if_fail (hook_list != NULL, NULL);

  g_return_val_if_fail (hook_list->is_setup, NULL);

  hook = g_slice_alloc0 (hook_list->hook_size);

  hook->data = NULL;

  hook->next = NULL;

  hook->prev = NULL;

  hook->flags = G_HOOK_FLAG_ACTIVE;

  hook->ref_count = 0;

  hook->hook_id = 0;

  hook->func = NULL;

  hook->destroy = NULL;

  return hook;

}

/**

 * g_hook_free:

 * @hook_list: a #GHookList

 * @hook: the #GHook to free

 *

 * Calls the #GHookList @finalize_hook function if it exists,

 * and frees the memory allocated for the #GHook.

 */

void

g_hook_free (GHookList *hook_list,

	     GHook     *hook)

{

  g_return_if_fail (hook_list != NULL);

  g_return_if_fail (hook_list->is_setup);

  g_return_if_fail (hook != NULL);

  g_return_if_fail (G_HOOK_IS_UNLINKED (hook));

  g_return_if_fail (!G_HOOK_IN_CALL (hook));

  if(hook_list->finalize_hook != NULL)

      hook_list->finalize_hook (hook_list, hook);

  g_slice_free1 (hook_list->hook_size, hook);

}

/**

 * g_hook_destroy_link:

 * @hook_list: a #GHookList

 * @hook: the #GHook to remove

 *

 * Removes one #GHook from a #GHookList, marking it

 * inactive and calling g_hook_unref() on it.

 */

void

g_hook_destroy_link (GHookList *hook_list,

		     GHook     *hook)

{

  g_return_if_fail (hook_list != NULL);

  g_return_if_fail (hook != NULL);

  hook->flags &= ~G_HOOK_FLAG_ACTIVE;

  if (hook->hook_id)

    {

      hook->hook_id = 0;

      g_hook_unref (hook_list, hook); /* counterpart to g_hook_insert_before */

    }

}

/**

 * g_hook_destroy:

 * @hook_list: a #GHookList

 * @hook_id: a hook ID

 *

 * Destroys a #GHook, given its ID.

 *

 * Returns: %TRUE if the #GHook was found in the #GHookList and destroyed

 */

gboolean

g_hook_destroy (GHookList   *hook_list,

		gulong	     hook_id)

{

  GHook *hook;

  g_return_val_if_fail (hook_list != NULL, FALSE);

  g_return_val_if_fail (hook_id > 0, FALSE);

  hook = g_hook_get (hook_list, hook_id);

  if (hook)

    {

      g_hook_destroy_link (hook_list, hook);

      return TRUE;

    }

  return FALSE;

}

/**

 * g_hook_unref:

 * @hook_list: a #GHookList

 * @hook: the #GHook to unref

 *

 * Decrements the reference count of a #GHook.

 * If the reference count falls to 0, the #GHook is removed

 * from the #GHookList and g_hook_free() is called to free it.

 */

void

g_hook_unref (GHookList *hook_list,

	      GHook	*hook)

{

  g_return_if_fail (hook_list != NULL);

  g_return_if_fail (hook != NULL);

  g_return_if_fail (hook->ref_count > 0);

  hook->ref_count--;

  if (!hook->ref_count)

    {

      g_return_if_fail (hook->hook_id == 0);

      g_return_if_fail (!G_HOOK_IN_CALL (hook));

      if (hook->prev)

	hook->prev->next = hook->next;

      else

	hook_list->hooks = hook->next;

      if (hook->next)

	{

	  hook->next->prev = hook->prev;

	  hook->next = NULL;

	}

      hook->prev = NULL;

      if (!hook_list->is_setup)

	{

	  hook_list->is_setup = TRUE;

	  g_hook_free (hook_list, hook);

	  hook_list->is_setup = FALSE;

	  if (!hook_list->hooks)

	    {

	      /* destroy hook_list->hook_memchunk */

	    }

	}

      else

	g_hook_free (hook_list, hook);

    }

}

/**

 * g_hook_ref:

 * @hook_list: a #GHookList

 * @hook: the #GHook to increment the reference count of

 *

 * Increments the reference count for a #GHook.

 *

 * Returns: the @hook that was passed in (since 2.6)

 */

GHook *

g_hook_ref (GHookList *hook_list,

	    GHook     *hook)

{

  g_return_val_if_fail (hook_list != NULL, NULL);

  g_return_val_if_fail (hook != NULL, NULL);

  g_return_val_if_fail (hook->ref_count > 0, NULL);

  hook->ref_count++;

  return hook;

}

/**

 * g_hook_append:

 * @hook_list: a #GHookList

 * @hook: the #GHook to add to the end of @hook_list

 *

 * Appends a #GHook onto the end of a #GHookList.

 */

/**

 * g_hook_prepend:

 * @hook_list: a #GHookList

 * @hook: the #GHook to add to the start of @hook_list

 *

 * Prepends a #GHook on the start of a #GHookList.

 */

void

g_hook_prepend (GHookList *hook_list,

		GHook	  *hook)

{

  g_return_if_fail (hook_list != NULL);

  g_hook_insert_before (hook_list, hook_list->hooks, hook);

}

/**

 * g_hook_insert_before:

 * @hook_list: a #GHookList

 * @sibling: the #GHook to insert the new #GHook before

 * @hook: the #GHook to insert

 *

 * Inserts a #GHook into a #GHookList, before a given #GHook.

 */

void

g_hook_insert_before (GHookList *hook_list,

		      GHook	*sibling,

		      GHook	*hook)

{

  g_return_if_fail (hook_list != NULL);

  g_return_if_fail (hook_list->is_setup);

  g_return_if_fail (hook != NULL);

  g_return_if_fail (G_HOOK_IS_UNLINKED (hook));

  g_return_if_fail (hook->ref_count == 0);

  hook->hook_id = hook_list->seq_id++;

  hook->ref_count = 1; /* counterpart to g_hook_destroy_link */

  if (sibling)

    {

      if (sibling->prev)

	{

	  hook->prev = sibling->prev;

	  hook->prev->next = hook;

	  hook->next = sibling;

	  sibling->prev = hook;

	}

      else

	{

	  hook_list->hooks = hook;

	  hook->next = sibling;

	  sibling->prev = hook;

	}

    }

  else

    {

      if (hook_list->hooks)

	{

	  sibling = hook_list->hooks;

	  while (sibling->next)

	    sibling = sibling->next;

	  hook->prev = sibling;

	  sibling->next = hook;

	}

      else

	hook_list->hooks = hook;

    }

}

/**

 * g_hook_list_invoke:

 * @hook_list: a #GHookList

 * @may_recurse: %TRUE if functions which are already running

 *     (e.g. in another thread) can be called. If set to %FALSE,

 *     these are skipped

 *

 * Calls all of the #GHook functions in a #GHookList.

 */

void

g_hook_list_invoke (GHookList *hook_list,

		    gboolean   may_recurse)

{

  GHook *hook;

  g_return_if_fail (hook_list != NULL);

  g_return_if_fail (hook_list->is_setup);

  hook = g_hook_first_valid (hook_list, may_recurse);

  while (hook)

    {

      GHookFunc func;

      gboolean was_in_call;

      func = (GHookFunc) hook->func;

      was_in_call = G_HOOK_IN_CALL (hook);

      hook->flags |= G_HOOK_FLAG_IN_CALL;

      func (hook->data);

      if (!was_in_call)

	hook->flags &= ~G_HOOK_FLAG_IN_CALL;

      hook = g_hook_next_valid (hook_list, hook, may_recurse);

    }

}

/**

 * g_hook_list_invoke_check:

 * @hook_list: a #GHookList

 * @may_recurse: %TRUE if functions which are already running

 *     (e.g. in another thread) can be called. If set to %FALSE,

 *     these are skipped

 *

 * Calls all of the #GHook functions in a #GHookList.

 * Any function which returns %FALSE is removed from the #GHookList.

 */

void

g_hook_list_invoke_check (GHookList *hook_list,

			  gboolean   may_recurse)

{

  GHook *hook;

  g_return_if_fail (hook_list != NULL);

  g_return_if_fail (hook_list->is_setup);

  hook = g_hook_first_valid (hook_list, may_recurse);

  while (hook)

    {

      GHookCheckFunc func;

      gboolean was_in_call;

      gboolean need_destroy;

      func = (GHookCheckFunc) hook->func;

      was_in_call = G_HOOK_IN_CALL (hook);

      hook->flags |= G_HOOK_FLAG_IN_CALL;

      need_destroy = !func (hook->data);

      if (!was_in_call)

	hook->flags &= ~G_HOOK_FLAG_IN_CALL;

      if (need_destroy)

	g_hook_destroy_link (hook_list, hook);

      hook = g_hook_next_valid (hook_list, hook, may_recurse);

    }

}

/**

 * GHookCheckMarshaller:

 * @hook: a #GHook

 * @marshal_data: user data

 *

 * Defines the type of function used by g_hook_list_marshal_check().

 *

 * Returns: %FALSE if @hook should be destroyed

 */

/**

 * g_hook_list_marshal_check:

 * @hook_list: a #GHookList

 * @may_recurse: %TRUE if hooks which are currently running

 *     (e.g. in another thread) are considered valid. If set to %FALSE,

 *     these are skipped

 * @marshaller: the function to call for each #GHook

 * @marshal_data: data to pass to @marshaller

 *

 * Calls a function on each valid #GHook and destroys it if the

 * function returns %FALSE.

 */

void

g_hook_list_marshal_check (GHookList	       *hook_list,

			   gboolean		may_recurse,

			   GHookCheckMarshaller marshaller,

			   gpointer		data)

{

  GHook *hook;

  g_return_if_fail (hook_list != NULL);

  g_return_if_fail (hook_list->is_setup);

  g_return_if_fail (marshaller != NULL);

  hook = g_hook_first_valid (hook_list, may_recurse);

  while (hook)

    {

      gboolean was_in_call;

      gboolean need_destroy;

      was_in_call = G_HOOK_IN_CALL (hook);

      hook->flags |= G_HOOK_FLAG_IN_CALL;

      need_destroy = !marshaller (hook, data);

      if (!was_in_call)

	hook->flags &= ~G_HOOK_FLAG_IN_CALL;

      if (need_destroy)

	g_hook_destroy_link (hook_list, hook);

      hook = g_hook_next_valid (hook_list, hook, may_recurse);

    }

}

/**

 * GHookMarshaller:

 * @hook: a #GHook

 * @marshal_data: user data

 *

 * Defines the type of function used by g_hook_list_marshal().

 */

/**

 * g_hook_list_marshal:

 * @hook_list: a #GHookList

 * @may_recurse: %TRUE if hooks which are currently running

 *     (e.g. in another thread) are considered valid. If set to %FALSE,

 *     these are skipped

 * @marshaller: the function to call for each #GHook

 * @marshal_data: data to pass to @marshaller

 *

 * Calls a function on each valid #GHook.

 */

void

g_hook_list_marshal (GHookList		     *hook_list,

		     gboolean		      may_recurse,

		     GHookMarshaller	      marshaller,

		     gpointer		      data)

{

  GHook *hook;

  g_return_if_fail (hook_list != NULL);

  g_return_if_fail (hook_list->is_setup);

  g_return_if_fail (marshaller != NULL);

  hook = g_hook_first_valid (hook_list, may_recurse);

  while (hook)

    {

      gboolean was_in_call;

      was_in_call = G_HOOK_IN_CALL (hook);

      hook->flags |= G_HOOK_FLAG_IN_CALL;

      marshaller (hook, data);

      if (!was_in_call)

	hook->flags &= ~G_HOOK_FLAG_IN_CALL;

      hook = g_hook_next_valid (hook_list, hook, may_recurse);

    }

}

/**

 * g_hook_first_valid:

 * @hook_list: a #GHookList

 * @may_be_in_call: %TRUE if hooks which are currently running

 *     (e.g. in another thread) are considered valid. If set to %FALSE,

 *     these are skipped

 *

 * Returns the first #GHook in a #GHookList which has not been destroyed.

 * The reference count for the #GHook is incremented, so you must call

 * g_hook_unref() to restore it when no longer needed. (Or call

 * g_hook_next_valid() if you are stepping through the #GHookList.)

 *

 * Returns: the first valid #GHook, or %NULL if none are valid

 */

GHook*

g_hook_first_valid (GHookList *hook_list,

		    gboolean   may_be_in_call)

{

  g_return_val_if_fail (hook_list != NULL, NULL);

  if (hook_list->is_setup)

    {

      GHook *hook;

      hook = hook_list->hooks;

      if (hook)

	{

	  g_hook_ref (hook_list, hook);

	  if (G_HOOK_IS_VALID (hook) && (may_be_in_call || !G_HOOK_IN_CALL (hook)))

	    return hook;

	  else

	    return g_hook_next_valid (hook_list, hook, may_be_in_call);

	}

    }

  return NULL;

}

/**

 * g_hook_next_valid:

 * @hook_list: a #GHookList

 * @hook: the current #GHook

 * @may_be_in_call: %TRUE if hooks which are currently running

 *     (e.g. in another thread) are considered valid. If set to %FALSE,

 *     these are skipped

 *

 * Returns the next #GHook in a #GHookList which has not been destroyed.

 * The reference count for the #GHook is incremented, so you must call

 * g_hook_unref() to restore it when no longer needed. (Or continue to call

 * g_hook_next_valid() until %NULL is returned.)

 *

 * Returns: the next valid #GHook, or %NULL if none are valid

 */

GHook*

g_hook_next_valid (GHookList *hook_list,

		   GHook     *hook,

		   gboolean   may_be_in_call)

{

  GHook *ohook = hook;

  g_return_val_if_fail (hook_list != NULL, NULL);

  if (!hook)

    return NULL;

  hook = hook->next;

  while (hook)

    {

      if (G_HOOK_IS_VALID (hook) && (may_be_in_call || !G_HOOK_IN_CALL (hook)))

	{

	  g_hook_ref (hook_list, hook);

	  g_hook_unref (hook_list, ohook);

	  return hook;

	}

      hook = hook->next;

    }

  g_hook_unref (hook_list, ohook);

  return NULL;

}

/**

 * g_hook_get:

 * @hook_list: a #GHookList

 * @hook_id: a hook id

 *

 * Returns the #GHook with the given id, or %NULL if it is not found.

 *

 * Returns: the #GHook with the given id, or %NULL if it is not found

 */

GHook*

g_hook_get (GHookList *hook_list,

	    gulong     hook_id)

{

  GHook *hook;

  g_return_val_if_fail (hook_list != NULL, NULL);

  g_return_val_if_fail (hook_id > 0, NULL);

  hook = hook_list->hooks;

  while (hook)

    {

      if (hook->hook_id == hook_id)

	return hook;

      hook = hook->next;

    }

  return NULL;

}

/**

 * GHookFindFunc:

 * @hook: a #GHook

 * @data: user data passed to g_hook_find_func()

 *

 * Defines the type of the function passed to g_hook_find().

 *

 * Returns: %TRUE if the required #GHook has been found

 */

/**

 * g_hook_find:

 * @hook_list: a #GHookList

 * @need_valids: %TRUE if #GHook elements which have been destroyed

 *     should be skipped

 * @func: the function to call for each #GHook, which should return

 *     %TRUE when the #GHook has been found

 * @data: the data to pass to @func

 *

 * Finds a #GHook in a #GHookList using the given function to

 * test for a match.

 *

 * Returns: the found #GHook or %NULL if no matching #GHook is found

 */

GHook*

g_hook_find (GHookList	  *hook_list,

	     gboolean	   need_valids,

	     GHookFindFunc func,

	     gpointer	   data)

{

  GHook *hook;

  g_return_val_if_fail (hook_list != NULL, NULL);

  g_return_val_if_fail (func != NULL, NULL);

  hook = hook_list->hooks;

  while (hook)

    {

      GHook *tmp;

      /* test only non-destroyed hooks */

      if (!hook->hook_id)

	{

	  hook = hook->next;

	  continue;

	}

      g_hook_ref (hook_list, hook);

      if (func (hook, data) && hook->hook_id && (!need_valids || G_HOOK_ACTIVE (hook)))

	{

	  g_hook_unref (hook_list, hook);

	  return hook;

	}

      tmp = hook->next;

      g_hook_unref (hook_list, hook);

      hook = tmp;

    }

  return NULL;

}

/**

 * g_hook_find_data:

 * @hook_list: a #GHookList

 * @need_valids: %TRUE if #GHook elements which have been destroyed

 *     should be skipped

 * @data: the data to find

 *

 * Finds a #GHook in a #GHookList with the given data.

 *

 * Returns: the #GHook with the given @data or %NULL if no matching

 *     #GHook is found

 */

GHook*

g_hook_find_data (GHookList *hook_list,

		  gboolean   need_valids,

		  gpointer   data)

{

  GHook *hook;

  g_return_val_if_fail (hook_list != NULL, NULL);

  hook = hook_list->hooks;