glib-2.0/glib/ghook.h

0001 /* GLIB - Library of useful routines for C programming
0002  * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
0003  *
0004  * SPDX-License-Identifier: LGPL-2.1-or-later
0005  *
0006  * This library is free software; you can redistribute it and/or
0007  * modify it under the terms of the GNU Lesser General Public
0008  * License as published by the Free Software Foundation; either
0009  * version 2.1 of the License, or (at your option) any later version.
0010  *
0011  * This library is distributed in the hope that it will be useful,
0012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0014  * Lesser General Public License for more details.
0015  *
0016  * You should have received a copy of the GNU Lesser General Public
0017  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
0018  */
0019
0020 /*
0021  * Modified by the GLib Team and others 1997-2000.  See the AUTHORS
0022  * file for a list of people on the GLib Team.  See the ChangeLog
0023  * files for a list of changes.  These files are distributed with
0024  * GLib at ftp://ftp.gtk.org/pub/gtk/.
0025  */
0026
0027 #ifndef __G_HOOK_H__
0028 #define __G_HOOK_H__
0029
0030 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
0031 #error "Only <glib.h> can be included directly."
0032 #endif
0033
0034 #include <glib/gmem.h>
0035
0036 G_BEGIN_DECLS
0037
0038
0039 /* --- typedefs --- */
0040 typedef struct _GHook       GHook;
0041 typedef struct _GHookList   GHookList;
0042
0043 typedef gint        (*GHookCompareFunc) (GHook      *new_hook,
0044                          GHook      *sibling);
0045 typedef gboolean    (*GHookFindFunc)    (GHook      *hook,
0046                          gpointer    data);
0047 typedef void        (*GHookMarshaller)  (GHook      *hook,
0048                          gpointer    marshal_data);
0049 typedef gboolean    (*GHookCheckMarshaller) (GHook      *hook,
0050                          gpointer    marshal_data);
0051 typedef void        (*GHookFunc)        (gpointer    data);
0052 typedef gboolean    (*GHookCheckFunc)   (gpointer    data);
0053 typedef void        (*GHookFinalizeFunc)    (GHookList      *hook_list,
0054                          GHook          *hook);
0055 typedef enum
0056 {
0057   G_HOOK_FLAG_ACTIVE        = 1 << 0,
0058   G_HOOK_FLAG_IN_CALL       = 1 << 1,
0059   G_HOOK_FLAG_RESERVED1     = 1 << 2, /*< private >*/
0060   G_HOOK_FLAG_RESERVED2     = 1 << 3, /*< private >*/
0061   G_HOOK_FLAG_MASK      = 0x0f
0062 } G_GNUC_FLAG_ENUM GHookFlagMask;
0063 #define G_HOOK_FLAG_USER_SHIFT  (4)
0064
0065
0066 /* --- structures --- */
0067 struct _GHookList
0068 {
0069   gulong        seq_id;
0070   guint         hook_size : 16;
0071   guint         is_setup : 1;
0072   GHook        *hooks;
0073   gpointer      dummy3;
0074   GHookFinalizeFunc finalize_hook;
0075   gpointer      dummy[2];
0076 };
0077 struct _GHook
0078 {
0079   gpointer   data;
0080   GHook     *next;
0081   GHook     *prev;
0082   guint      ref_count;
0083   gulong     hook_id;
0084   guint      flags;
0085   gpointer   func;
0086   GDestroyNotify destroy;
0087 };
0088
0089
0090 /* --- macros --- */
0091 #define G_HOOK(hook)            ((GHook*) (hook))
0092 #define G_HOOK_FLAGS(hook)      (G_HOOK (hook)->flags)
0093 #define G_HOOK_ACTIVE(hook)     ((G_HOOK_FLAGS (hook) & \
0094                       G_HOOK_FLAG_ACTIVE) != 0)
0095 #define G_HOOK_IN_CALL(hook)        ((G_HOOK_FLAGS (hook) & \
0096                       G_HOOK_FLAG_IN_CALL) != 0)
0097 #define G_HOOK_IS_VALID(hook)       (G_HOOK (hook)->hook_id != 0 && \
0098                      (G_HOOK_FLAGS (hook) & \
0099                                           G_HOOK_FLAG_ACTIVE))
0100 #define G_HOOK_IS_UNLINKED(hook)    (G_HOOK (hook)->next == NULL && \
0101                      G_HOOK (hook)->prev == NULL && \
0102                      G_HOOK (hook)->hook_id == 0 && \
0103                      G_HOOK (hook)->ref_count == 0)
0104
0105
0106 /* --- prototypes --- */
0107 /* callback maintenance functions */
0108 GLIB_AVAILABLE_IN_ALL
0109 void     g_hook_list_init       (GHookList      *hook_list,
0110                      guint           hook_size);
0111 GLIB_AVAILABLE_IN_ALL
0112 void     g_hook_list_clear      (GHookList      *hook_list);
0113 GLIB_AVAILABLE_IN_ALL
0114 GHook*   g_hook_alloc           (GHookList      *hook_list);
0115 GLIB_AVAILABLE_IN_ALL
0116 void     g_hook_free            (GHookList      *hook_list,
0117                      GHook          *hook);
0118 GLIB_AVAILABLE_IN_ALL
0119 GHook *  g_hook_ref         (GHookList      *hook_list,
0120                      GHook          *hook);
0121 GLIB_AVAILABLE_IN_ALL
0122 void     g_hook_unref           (GHookList      *hook_list,
0123                      GHook          *hook);
0124 GLIB_AVAILABLE_IN_ALL
0125 gboolean g_hook_destroy         (GHookList      *hook_list,
0126                      gulong          hook_id);
0127 GLIB_AVAILABLE_IN_ALL
0128 void     g_hook_destroy_link        (GHookList      *hook_list,
0129                      GHook          *hook);
0130 GLIB_AVAILABLE_IN_ALL
0131 void     g_hook_prepend         (GHookList      *hook_list,
0132                      GHook          *hook);
0133 GLIB_AVAILABLE_IN_ALL
0134 void     g_hook_insert_before       (GHookList      *hook_list,
0135                      GHook          *sibling,
0136                      GHook          *hook);
0137 GLIB_AVAILABLE_IN_ALL
0138 void     g_hook_insert_sorted       (GHookList      *hook_list,
0139                      GHook          *hook,
0140                      GHookCompareFunc    func);
0141 GLIB_AVAILABLE_IN_ALL
0142 GHook*   g_hook_get         (GHookList      *hook_list,
0143                      gulong          hook_id);
0144 GLIB_AVAILABLE_IN_ALL
0145 GHook*   g_hook_find            (GHookList      *hook_list,
0146                      gboolean        need_valids,
0147                      GHookFindFunc       func,
0148                      gpointer        data);
0149 GLIB_AVAILABLE_IN_ALL
0150 GHook*   g_hook_find_data       (GHookList      *hook_list,
0151                      gboolean        need_valids,
0152                      gpointer        data);
0153 GLIB_AVAILABLE_IN_ALL
0154 GHook*   g_hook_find_func       (GHookList      *hook_list,
0155                      gboolean        need_valids,
0156                      gpointer        func);
0157 GLIB_AVAILABLE_IN_ALL
0158 GHook*   g_hook_find_func_data      (GHookList      *hook_list,
0159                      gboolean        need_valids,
0160                      gpointer        func,
0161                      gpointer        data);
0162 /* return the first valid hook, and increment its reference count */
0163 GLIB_AVAILABLE_IN_ALL
0164 GHook*   g_hook_first_valid     (GHookList      *hook_list,
0165                      gboolean        may_be_in_call);
0166 /* return the next valid hook with incremented reference count, and
0167  * decrement the reference count of the original hook
0168  */
0169 GLIB_AVAILABLE_IN_ALL
0170 GHook*   g_hook_next_valid      (GHookList      *hook_list,
0171                      GHook          *hook,
0172                      gboolean        may_be_in_call);
0173 /* GHookCompareFunc implementation to insert hooks sorted by their id */
0174 GLIB_AVAILABLE_IN_ALL
0175 gint     g_hook_compare_ids     (GHook          *new_hook,
0176                      GHook          *sibling);
0177 /* convenience macros */
0178 #define  g_hook_append( hook_list, hook )  \
0179      g_hook_insert_before ((hook_list), NULL, (hook))
0180 /* invoke all valid hooks with the (*GHookFunc) signature.
0181  */
0182 GLIB_AVAILABLE_IN_ALL
0183 void     g_hook_list_invoke     (GHookList      *hook_list,
0184                      gboolean        may_recurse);
0185 /* invoke all valid hooks with the (*GHookCheckFunc) signature,
0186  * and destroy the hook if FALSE is returned.
0187  */
0188 GLIB_AVAILABLE_IN_ALL
0189 void     g_hook_list_invoke_check   (GHookList      *hook_list,
0190                      gboolean        may_recurse);
0191 /* invoke a marshaller on all valid hooks.
0192  */
0193 GLIB_AVAILABLE_IN_ALL
0194 void     g_hook_list_marshal        (GHookList      *hook_list,
0195                      gboolean        may_recurse,
0196                      GHookMarshaller     marshaller,
0197                      gpointer        marshal_data);
0198 GLIB_AVAILABLE_IN_ALL
0199 void     g_hook_list_marshal_check  (GHookList      *hook_list,
0200                      gboolean        may_recurse,
0201                      GHookCheckMarshaller    marshaller,
0202                      gpointer        marshal_data);
0203
0204 G_END_DECLS
0205
0206 #endif /* __G_HOOK_H__ */