1 /* GLIB - Library of useful routines for C programming
2 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
4 * GHook: Callback maintenance functions
5 * Copyright (C) 1998 Tim Janik
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20 * Boston, MA 02111-1307, USA.
24 * Modified by the GLib Team and others 1997-2000. See the AUTHORS
25 * file for a list of people on the GLib Team. See the ChangeLog
26 * files for a list of changes. These files are distributed with
27 * GLib at ftp://ftp.gtk.org/pub/gtk/.
38 #include "gtestutils.h"
43 * @title: Hook Functions
44 * @short_description: support for manipulating lists of hook functions
46 * The #GHookList, #GHook and their related functions provide support for
47 * lists of hook functions. Functions can be added and removed from the lists,
48 * and the list of hook functions can be invoked.
53 * @seq_id: the next free #GHook id
54 * @hook_size: the size of the #GHookList elements, in bytes
55 * @is_setup: 1 if the #GHookList has been initialized
56 * @hooks: the first #GHook element in the list
58 * @finalize_hook: the function to call to finalize a #GHook element.
59 * The default behaviour is to call the hooks @destroy function
62 * The <structname>GHookList</structname> struct represents a
63 * list of hook functions.
68 * @hook_list: a #GHookList
69 * @hook: the hook in @hook_list that gets finalized
71 * Defines the type of function to be called when a hook in a
72 * list of hooks gets finalized.
77 * @G_HOOK_FLAG_ACTIVE: set if the hook has not been destroyed
78 * @G_HOOK_FLAG_IN_CALL: set if the hook is currently being run
79 * @G_HOOK_FLAG_MASK: A mask covering all bits reserved for
80 * hook flags; see %G_HOOK_FLAG_USER_SHIFT
82 * Flags used internally in the #GHook implementation.
89 * Gets the flags of a hook.
93 * G_HOOK_FLAG_USER_SHIFT:
95 * The position of the first bit which is not reserved for internal
96 * use be the #GHook implementation, i.e.
97 * <literal>1 << G_HOOK_FLAG_USER_SHIFT</literal> is the first
98 * bit which can be used for application-defined flags.
105 * Casts a pointer to a <literal>GHook*</literal>.
112 * Returns %TRUE if the #GHook is valid, i.e. it is in a #GHookList,
113 * it is active and it has not been destroyed.
115 * Returns: %TRUE if the #GHook is valid
122 * Returns %TRUE if the #GHook is active, which is normally the case
123 * until the #GHook is destroyed.
125 * Returns: %TRUE if the #GHook is active
132 * Returns %TRUE if the #GHook function is currently executing.
134 * Returns: %TRUE if the #GHook function is currently executing
138 * G_HOOK_IS_UNLINKED:
141 * Returns %TRUE if the #GHook is not in a #GHookList.
143 * Returns: %TRUE if the #GHook is not in a #GHookList
148 * @data: data which is passed to func when this hook is invoked
149 * @next: pointer to the next hook in the list
150 * @prev: pointer to the previous hook in the list
151 * @ref_count: the reference count of this hook
152 * @hook_id: the id of this hook, which is unique within its list
153 * @flags: flags which are set for this hook. See #GHookFlagMask for
155 * @func: the function to call when this hook is invoked. The possible
156 * signatures for this function are #GHookFunc and #GHookCheckFunc
157 * @destroy: the default @finalize_hook function of a #GHookList calls
158 * this member of the hook that is being finalized
160 * The <structname>GHook</structname> struct represents a single hook
161 * function in a #GHookList.
166 * @data: the data field of the #GHook is passed to the hook function here
168 * Defines the type of a hook function that can be invoked
169 * by g_hook_list_invoke().
174 * @data: the data field of the #GHook is passed to the hook function here
176 * Defines the type of a hook function that can be invoked
177 * by g_hook_list_invoke_check().
179 * Returns: %FALSE if the #GHook should be destroyed
182 /* --- functions --- */
184 default_finalize_hook (GHookList
*hook_list
,
187 GDestroyNotify destroy
= hook
->destroy
;
191 hook
->destroy
= NULL
;
192 destroy (hook
->data
);
198 * @hook_list: a #GHookList
199 * @hook_size: the size of each element in the #GHookList,
200 * typically <literal>sizeof (GHook)</literal>
202 * Initializes a #GHookList.
203 * This must be called before the #GHookList is used.
206 g_hook_list_init (GHookList
*hook_list
,
209 g_return_if_fail (hook_list
!= NULL
);
210 g_return_if_fail (hook_size
>= sizeof (GHook
));
212 hook_list
->seq_id
= 1;
213 hook_list
->hook_size
= hook_size
;
214 hook_list
->is_setup
= TRUE
;
215 hook_list
->hooks
= NULL
;
216 hook_list
->dummy3
= NULL
;
217 hook_list
->finalize_hook
= default_finalize_hook
;
218 hook_list
->dummy
[0] = NULL
;
219 hook_list
->dummy
[1] = NULL
;
224 * @hook_list: a #GHookList
226 * Removes all the #GHook elements from a #GHookList.
229 g_hook_list_clear (GHookList
*hook_list
)
231 g_return_if_fail (hook_list
!= NULL
);
233 if (hook_list
->is_setup
)
237 hook_list
->is_setup
= FALSE
;
239 hook
= hook_list
->hooks
;
242 /* destroy hook_list->hook_memchunk */
249 g_hook_ref (hook_list
, hook
);
250 g_hook_destroy_link (hook_list
, hook
);
252 g_hook_unref (hook_list
, hook
);
261 * @hook_list: a #GHookList
263 * Allocates space for a #GHook and initializes it.
265 * Returns: a new #GHook
268 g_hook_alloc (GHookList
*hook_list
)
272 g_return_val_if_fail (hook_list
!= NULL
, NULL
);
273 g_return_val_if_fail (hook_list
->is_setup
, NULL
);
275 hook
= g_slice_alloc0 (hook_list
->hook_size
);
279 hook
->flags
= G_HOOK_FLAG_ACTIVE
;
283 hook
->destroy
= NULL
;
289 * @hook_list: a #GHookList
290 * @hook: the #GHook to free
292 * Calls the #GHookList @finalize_hook function if it exists,
293 * and frees the memory allocated for the #GHook.
296 g_hook_free (GHookList
*hook_list
,
299 g_return_if_fail (hook_list
!= NULL
);
300 g_return_if_fail (hook_list
->is_setup
);
301 g_return_if_fail (hook
!= NULL
);
302 g_return_if_fail (G_HOOK_IS_UNLINKED (hook
));
303 g_return_if_fail (!G_HOOK_IN_CALL (hook
));
305 if(hook_list
->finalize_hook
!= NULL
)
306 hook_list
->finalize_hook (hook_list
, hook
);
307 g_slice_free1 (hook_list
->hook_size
, hook
);
311 * g_hook_destroy_link:
312 * @hook_list: a #GHookList
313 * @hook: the #GHook to remove
315 * Removes one #GHook from a #GHookList, marking it
316 * inactive and calling g_hook_unref() on it.
319 g_hook_destroy_link (GHookList
*hook_list
,
322 g_return_if_fail (hook_list
!= NULL
);
323 g_return_if_fail (hook
!= NULL
);
325 hook
->flags
&= ~G_HOOK_FLAG_ACTIVE
;
329 g_hook_unref (hook_list
, hook
); /* counterpart to g_hook_insert_before */
335 * @hook_list: a #GHookList
336 * @hook_id: a hook ID
338 * Destroys a #GHook, given its ID.
340 * Returns: %TRUE if the #GHook was found in the #GHookList and destroyed
343 g_hook_destroy (GHookList
*hook_list
,
348 g_return_val_if_fail (hook_list
!= NULL
, FALSE
);
349 g_return_val_if_fail (hook_id
> 0, FALSE
);
351 hook
= g_hook_get (hook_list
, hook_id
);
354 g_hook_destroy_link (hook_list
, hook
);
363 * @hook_list: a #GHookList
364 * @hook: the #GHook to unref
366 * Decrements the reference count of a #GHook.
367 * If the reference count falls to 0, the #GHook is removed
368 * from the #GHookList and g_hook_free() is called to free it.
371 g_hook_unref (GHookList
*hook_list
,
374 g_return_if_fail (hook_list
!= NULL
);
375 g_return_if_fail (hook
!= NULL
);
376 g_return_if_fail (hook
->ref_count
> 0);
379 if (!hook
->ref_count
)
381 g_return_if_fail (hook
->hook_id
== 0);
382 g_return_if_fail (!G_HOOK_IN_CALL (hook
));
385 hook
->prev
->next
= hook
->next
;
387 hook_list
->hooks
= hook
->next
;
390 hook
->next
->prev
= hook
->prev
;
395 if (!hook_list
->is_setup
)
397 hook_list
->is_setup
= TRUE
;
398 g_hook_free (hook_list
, hook
);
399 hook_list
->is_setup
= FALSE
;
401 if (!hook_list
->hooks
)
403 /* destroy hook_list->hook_memchunk */
407 g_hook_free (hook_list
, hook
);
413 * @hook_list: a #GHookList
414 * @hook: the #GHook to increment the reference count of
416 * Increments the reference count for a #GHook.
418 * Returns: the @hook that was passed in (since 2.6)
421 g_hook_ref (GHookList
*hook_list
,
424 g_return_val_if_fail (hook_list
!= NULL
, NULL
);
425 g_return_val_if_fail (hook
!= NULL
, NULL
);
426 g_return_val_if_fail (hook
->ref_count
> 0, NULL
);
435 * @hook_list: a #GHookList
436 * @hook: the #GHook to add to the end of @hook_list
438 * Appends a #GHook onto the end of a #GHookList.
443 * @hook_list: a #GHookList
444 * @hook: the #GHook to add to the start of @hook_list
446 * Prepends a #GHook on the start of a #GHookList.
449 g_hook_prepend (GHookList
*hook_list
,
452 g_return_if_fail (hook_list
!= NULL
);
454 g_hook_insert_before (hook_list
, hook_list
->hooks
, hook
);
458 * g_hook_insert_before:
459 * @hook_list: a #GHookList
460 * @sibling: the #GHook to insert the new #GHook before
461 * @hook: the #GHook to insert
463 * Inserts a #GHook into a #GHookList, before a given #GHook.
466 g_hook_insert_before (GHookList
*hook_list
,
470 g_return_if_fail (hook_list
!= NULL
);
471 g_return_if_fail (hook_list
->is_setup
);
472 g_return_if_fail (hook
!= NULL
);
473 g_return_if_fail (G_HOOK_IS_UNLINKED (hook
));
474 g_return_if_fail (hook
->ref_count
== 0);
476 hook
->hook_id
= hook_list
->seq_id
++;
477 hook
->ref_count
= 1; /* counterpart to g_hook_destroy_link */
483 hook
->prev
= sibling
->prev
;
484 hook
->prev
->next
= hook
;
485 hook
->next
= sibling
;
486 sibling
->prev
= hook
;
490 hook_list
->hooks
= hook
;
491 hook
->next
= sibling
;
492 sibling
->prev
= hook
;
497 if (hook_list
->hooks
)
499 sibling
= hook_list
->hooks
;
500 while (sibling
->next
)
501 sibling
= sibling
->next
;
502 hook
->prev
= sibling
;
503 sibling
->next
= hook
;
506 hook_list
->hooks
= hook
;
511 * g_hook_list_invoke:
512 * @hook_list: a #GHookList
513 * @may_recurse: %TRUE if functions which are already running
514 * (e.g. in another thread) can be called. If set to %FALSE,
517 * Calls all of the #GHook functions in a #GHookList.
520 g_hook_list_invoke (GHookList
*hook_list
,
521 gboolean may_recurse
)
525 g_return_if_fail (hook_list
!= NULL
);
526 g_return_if_fail (hook_list
->is_setup
);
528 hook
= g_hook_first_valid (hook_list
, may_recurse
);
532 gboolean was_in_call
;
534 func
= (GHookFunc
) hook
->func
;
536 was_in_call
= G_HOOK_IN_CALL (hook
);
537 hook
->flags
|= G_HOOK_FLAG_IN_CALL
;
540 hook
->flags
&= ~G_HOOK_FLAG_IN_CALL
;
542 hook
= g_hook_next_valid (hook_list
, hook
, may_recurse
);
547 * g_hook_list_invoke_check:
548 * @hook_list: a #GHookList
549 * @may_recurse: %TRUE if functions which are already running
550 * (e.g. in another thread) can be called. If set to %FALSE,
553 * Calls all of the #GHook functions in a #GHookList.
554 * Any function which returns %FALSE is removed from the #GHookList.
557 g_hook_list_invoke_check (GHookList
*hook_list
,
558 gboolean may_recurse
)
562 g_return_if_fail (hook_list
!= NULL
);
563 g_return_if_fail (hook_list
->is_setup
);
565 hook
= g_hook_first_valid (hook_list
, may_recurse
);
569 gboolean was_in_call
;
570 gboolean need_destroy
;
572 func
= (GHookCheckFunc
) hook
->func
;
574 was_in_call
= G_HOOK_IN_CALL (hook
);
575 hook
->flags
|= G_HOOK_FLAG_IN_CALL
;
576 need_destroy
= !func (hook
->data
);
578 hook
->flags
&= ~G_HOOK_FLAG_IN_CALL
;
580 g_hook_destroy_link (hook_list
, hook
);
582 hook
= g_hook_next_valid (hook_list
, hook
, may_recurse
);
587 * GHookCheckMarshaller:
589 * @marshal_data: user data
591 * Defines the type of function used by g_hook_list_marshal_check().
593 * Returns: %FALSE if @hook should be destroyed
597 * g_hook_list_marshal_check:
598 * @hook_list: a #GHookList
599 * @may_recurse: %TRUE if hooks which are currently running
600 * (e.g. in another thread) are considered valid. If set to %FALSE,
602 * @marshaller: the function to call for each #GHook
603 * @marshal_data: data to pass to @marshaller
605 * Calls a function on each valid #GHook and destroys it if the
606 * function returns %FALSE.
609 g_hook_list_marshal_check (GHookList
*hook_list
,
610 gboolean may_recurse
,
611 GHookCheckMarshaller marshaller
,
616 g_return_if_fail (hook_list
!= NULL
);
617 g_return_if_fail (hook_list
->is_setup
);
618 g_return_if_fail (marshaller
!= NULL
);
620 hook
= g_hook_first_valid (hook_list
, may_recurse
);
623 gboolean was_in_call
;
624 gboolean need_destroy
;
626 was_in_call
= G_HOOK_IN_CALL (hook
);
627 hook
->flags
|= G_HOOK_FLAG_IN_CALL
;
628 need_destroy
= !marshaller (hook
, data
);
630 hook
->flags
&= ~G_HOOK_FLAG_IN_CALL
;
632 g_hook_destroy_link (hook_list
, hook
);
634 hook
= g_hook_next_valid (hook_list
, hook
, may_recurse
);
641 * @marshal_data: user data
643 * Defines the type of function used by g_hook_list_marshal().
647 * g_hook_list_marshal:
648 * @hook_list: a #GHookList
649 * @may_recurse: %TRUE if hooks which are currently running
650 * (e.g. in another thread) are considered valid. If set to %FALSE,
652 * @marshaller: the function to call for each #GHook
653 * @marshal_data: data to pass to @marshaller
655 * Calls a function on each valid #GHook.
658 g_hook_list_marshal (GHookList
*hook_list
,
659 gboolean may_recurse
,
660 GHookMarshaller marshaller
,
665 g_return_if_fail (hook_list
!= NULL
);
666 g_return_if_fail (hook_list
->is_setup
);
667 g_return_if_fail (marshaller
!= NULL
);
669 hook
= g_hook_first_valid (hook_list
, may_recurse
);
672 gboolean was_in_call
;
674 was_in_call
= G_HOOK_IN_CALL (hook
);
675 hook
->flags
|= G_HOOK_FLAG_IN_CALL
;
676 marshaller (hook
, data
);
678 hook
->flags
&= ~G_HOOK_FLAG_IN_CALL
;
680 hook
= g_hook_next_valid (hook_list
, hook
, may_recurse
);
685 * g_hook_first_valid:
686 * @hook_list: a #GHookList
687 * @may_be_in_call: %TRUE if hooks which are currently running
688 * (e.g. in another thread) are considered valid. If set to %FALSE,
691 * Returns the first #GHook in a #GHookList which has not been destroyed.
692 * The reference count for the #GHook is incremented, so you must call
693 * g_hook_unref() to restore it when no longer needed. (Or call
694 * g_hook_next_valid() if you are stepping through the #GHookList.)
696 * Returns: the first valid #GHook, or %NULL if none are valid
699 g_hook_first_valid (GHookList
*hook_list
,
700 gboolean may_be_in_call
)
702 g_return_val_if_fail (hook_list
!= NULL
, NULL
);
704 if (hook_list
->is_setup
)
708 hook
= hook_list
->hooks
;
711 g_hook_ref (hook_list
, hook
);
712 if (G_HOOK_IS_VALID (hook
) && (may_be_in_call
|| !G_HOOK_IN_CALL (hook
)))
715 return g_hook_next_valid (hook_list
, hook
, may_be_in_call
);
724 * @hook_list: a #GHookList
725 * @hook: the current #GHook
726 * @may_be_in_call: %TRUE if hooks which are currently running
727 * (e.g. in another thread) are considered valid. If set to %FALSE,
730 * Returns the next #GHook in a #GHookList which has not been destroyed.
731 * The reference count for the #GHook is incremented, so you must call
732 * g_hook_unref() to restore it when no longer needed. (Or continue to call
733 * g_hook_next_valid() until %NULL is returned.)
735 * Returns: the next valid #GHook, or %NULL if none are valid
738 g_hook_next_valid (GHookList
*hook_list
,
740 gboolean may_be_in_call
)
744 g_return_val_if_fail (hook_list
!= NULL
, NULL
);
752 if (G_HOOK_IS_VALID (hook
) && (may_be_in_call
|| !G_HOOK_IN_CALL (hook
)))
754 g_hook_ref (hook_list
, hook
);
755 g_hook_unref (hook_list
, ohook
);
761 g_hook_unref (hook_list
, ohook
);
768 * @hook_list: a #GHookList
769 * @hook_id: a hook id
771 * Returns the #GHook with the given id, or %NULL if it is not found.
773 * Returns: the #GHook with the given id, or %NULL if it is not found
776 g_hook_get (GHookList
*hook_list
,
781 g_return_val_if_fail (hook_list
!= NULL
, NULL
);
782 g_return_val_if_fail (hook_id
> 0, NULL
);
784 hook
= hook_list
->hooks
;
787 if (hook
->hook_id
== hook_id
)
798 * @data: user data passed to g_hook_find_func()
800 * Defines the type of the function passed to g_hook_find().
802 * Returns: %TRUE if the required #GHook has been found
807 * @hook_list: a #GHookList
808 * @need_valids: %TRUE if #GHook elements which have been destroyed
810 * @func: the function to call for each #GHook, which should return
811 * %TRUE when the #GHook has been found
812 * @data: the data to pass to @func
814 * Finds a #GHook in a #GHookList using the given function to
817 * Returns: the found #GHook or %NULL if no matching #GHook is found
820 g_hook_find (GHookList
*hook_list
,
821 gboolean need_valids
,
827 g_return_val_if_fail (hook_list
!= NULL
, NULL
);
828 g_return_val_if_fail (func
!= NULL
, NULL
);
830 hook
= hook_list
->hooks
;
835 /* test only non-destroyed hooks */
842 g_hook_ref (hook_list
, hook
);
844 if (func (hook
, data
) && hook
->hook_id
&& (!need_valids
|| G_HOOK_ACTIVE (hook
)))
846 g_hook_unref (hook_list
, hook
);
852 g_hook_unref (hook_list
, hook
);
861 * @hook_list: a #GHookList
862 * @need_valids: %TRUE if #GHook elements which have been destroyed
864 * @data: the data to find
866 * Finds a #GHook in a #GHookList with the given data.
868 * Returns: the #GHook with the given @data or %NULL if no matching
872 g_hook_find_data (GHookList
*hook_list
,
873 gboolean need_valids
,
878 g_return_val_if_fail (hook_list
!= NULL
, NULL
);
880 hook
= hook_list
->hooks
;
883 /* test only non-destroyed hooks */
884 if (hook
->data
== data
&&
886 (!need_valids
|| G_HOOK_ACTIVE (hook
)))
897 * @hook_list: a #GHookList
898 * @need_valids: %TRUE if #GHook elements which have been destroyed
900 * @func: the function to find
902 * Finds a #GHook in a #GHookList with the given function.
904 * Returns: the #GHook with the given @func or %NULL if no matching
908 g_hook_find_func (GHookList
*hook_list
,
909 gboolean need_valids
,
914 g_return_val_if_fail (hook_list
!= NULL
, NULL
);
915 g_return_val_if_fail (func
!= NULL
, NULL
);
917 hook
= hook_list
->hooks
;
920 /* test only non-destroyed hooks */
921 if (hook
->func
== func
&&
923 (!need_valids
|| G_HOOK_ACTIVE (hook
)))
933 * g_hook_find_func_data:
934 * @hook_list: a #GHookList
935 * @need_valids: %TRUE if #GHook elements which have been destroyed
937 * @func: the function to find
938 * @data: the data to find
940 * Finds a #GHook in a #GHookList with the given function and data.
942 * Returns: the #GHook with the given @func and @data or %NULL if
943 * no matching #GHook is found
946 g_hook_find_func_data (GHookList
*hook_list
,
947 gboolean need_valids
,
953 g_return_val_if_fail (hook_list
!= NULL
, NULL
);
954 g_return_val_if_fail (func
!= NULL
, NULL
);
956 hook
= hook_list
->hooks
;
959 /* test only non-destroyed hooks */
960 if (hook
->data
== data
&&
961 hook
->func
== func
&&
963 (!need_valids
|| G_HOOK_ACTIVE (hook
)))
974 * @new_hook: the #GHook being inserted
975 * @sibling: the #GHook to compare with @new_hook
977 * Defines the type of function used to compare #GHook elements in
978 * g_hook_insert_sorted().
980 * Returns: a value <= 0 if @new_hook should be before @sibling
984 * g_hook_insert_sorted:
985 * @hook_list: a #GHookList
986 * @hook: the #GHook to insert
987 * @func: the comparison function used to sort the #GHook elements
989 * Inserts a #GHook into a #GHookList, sorted by the given function.
992 g_hook_insert_sorted (GHookList
*hook_list
,
994 GHookCompareFunc func
)
998 g_return_if_fail (hook_list
!= NULL
);
999 g_return_if_fail (hook_list
->is_setup
);
1000 g_return_if_fail (hook
!= NULL
);
1001 g_return_if_fail (G_HOOK_IS_UNLINKED (hook
));
1002 g_return_if_fail (hook
->func
!= NULL
);
1003 g_return_if_fail (func
!= NULL
);
1005 /* first non-destroyed hook */
1006 sibling
= hook_list
->hooks
;
1007 while (sibling
&& !sibling
->hook_id
)
1008 sibling
= sibling
->next
;
1014 g_hook_ref (hook_list
, sibling
);
1015 if (func (hook
, sibling
) <= 0 && sibling
->hook_id
)
1017 g_hook_unref (hook_list
, sibling
);
1021 /* next non-destroyed hook */
1022 tmp
= sibling
->next
;
1023 while (tmp
&& !tmp
->hook_id
)
1026 g_hook_unref (hook_list
, sibling
);
1031 g_hook_insert_before (hook_list
, sibling
, hook
);
1035 * g_hook_compare_ids:
1036 * @new_hook: a #GHook
1037 * @sibling: a #GHook to compare with @new_hook
1039 * Compares the ids of two #GHook elements, returning a negative value
1040 * if the second id is greater than the first.
1042 * Returns: a value <= 0 if the id of @sibling is >= the id of @new_hook
1045 g_hook_compare_ids (GHook
*new_hook
,
1048 if (new_hook
->hook_id
< sibling
->hook_id
)
1050 else if (new_hook
->hook_id
> sibling
->hook_id
)