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_MASK      = 0x0f
0060 } GHookFlagMask;
0061 #define G_HOOK_FLAG_USER_SHIFT  (4)
0062
0063
0064 /* --- structures --- */
0065 struct _GHookList
0066 {
0067   gulong        seq_id;
0068   guint         hook_size : 16;
0069   guint         is_setup : 1;
0070   GHook        *hooks;
0071   gpointer      dummy3;
0072   GHookFinalizeFunc finalize_hook;
0073   gpointer      dummy[2];
0074 };
0075 struct _GHook
0076 {
0077   gpointer   data;
0078   GHook     *next;
0079   GHook     *prev;
0080   guint      ref_count;
0081   gulong     hook_id;
0082   guint      flags;
0083   gpointer   func;
0084   GDestroyNotify destroy;
0085 };
0086
0087
0088 /* --- macros --- */
0089 #define G_HOOK(hook)            ((GHook*) (hook))
0090 #define G_HOOK_FLAGS(hook)      (G_HOOK (hook)->flags)
0091 #define G_HOOK_ACTIVE(hook)     ((G_HOOK_FLAGS (hook) & \
0092                       G_HOOK_FLAG_ACTIVE) != 0)
0093 #define G_HOOK_IN_CALL(hook)        ((G_HOOK_FLAGS (hook) & \
0094                       G_HOOK_FLAG_IN_CALL) != 0)
0095 #define G_HOOK_IS_VALID(hook)       (G_HOOK (hook)->hook_id != 0 && \
0096                      (G_HOOK_FLAGS (hook) & \
0097                                           G_HOOK_FLAG_ACTIVE))
0098 #define G_HOOK_IS_UNLINKED(hook)    (G_HOOK (hook)->next == NULL && \
0099                      G_HOOK (hook)->prev == NULL && \
0100                      G_HOOK (hook)->hook_id == 0 && \
0101                      G_HOOK (hook)->ref_count == 0)
0102
0103
0104 /* --- prototypes --- */
0105 /* callback maintenance functions */
0106 GLIB_AVAILABLE_IN_ALL
0107 void     g_hook_list_init       (GHookList      *hook_list,
0108                      guint           hook_size);
0109 GLIB_AVAILABLE_IN_ALL
0110 void     g_hook_list_clear      (GHookList      *hook_list);
0111 GLIB_AVAILABLE_IN_ALL
0112 GHook*   g_hook_alloc           (GHookList      *hook_list);
0113 GLIB_AVAILABLE_IN_ALL
0114 void     g_hook_free            (GHookList      *hook_list,
0115                      GHook          *hook);
0116 GLIB_AVAILABLE_IN_ALL
0117 GHook *  g_hook_ref         (GHookList      *hook_list,
0118                      GHook          *hook);
0119 GLIB_AVAILABLE_IN_ALL
0120 void     g_hook_unref           (GHookList      *hook_list,
0121                      GHook          *hook);
0122 GLIB_AVAILABLE_IN_ALL
0123 gboolean g_hook_destroy         (GHookList      *hook_list,
0124                      gulong          hook_id);
0125 GLIB_AVAILABLE_IN_ALL
0126 void     g_hook_destroy_link        (GHookList      *hook_list,
0127                      GHook          *hook);
0128 GLIB_AVAILABLE_IN_ALL
0129 void     g_hook_prepend         (GHookList      *hook_list,
0130                      GHook          *hook);
0131 GLIB_AVAILABLE_IN_ALL
0132 void     g_hook_insert_before       (GHookList      *hook_list,
0133                      GHook          *sibling,
0134                      GHook          *hook);
0135 GLIB_AVAILABLE_IN_ALL
0136 void     g_hook_insert_sorted       (GHookList      *hook_list,
0137                      GHook          *hook,
0138                      GHookCompareFunc    func);
0139 GLIB_AVAILABLE_IN_ALL
0140 GHook*   g_hook_get         (GHookList      *hook_list,
0141                      gulong          hook_id);
0142 GLIB_AVAILABLE_IN_ALL
0143 GHook*   g_hook_find            (GHookList      *hook_list,
0144                      gboolean        need_valids,
0145                      GHookFindFunc       func,
0146                      gpointer        data);
0147 GLIB_AVAILABLE_IN_ALL
0148 GHook*   g_hook_find_data       (GHookList      *hook_list,
0149                      gboolean        need_valids,
0150                      gpointer        data);
0151 GLIB_AVAILABLE_IN_ALL
0152 GHook*   g_hook_find_func       (GHookList      *hook_list,
0153                      gboolean        need_valids,
0154                      gpointer        func);
0155 GLIB_AVAILABLE_IN_ALL
0156 GHook*   g_hook_find_func_data      (GHookList      *hook_list,
0157                      gboolean        need_valids,
0158                      gpointer        func,
0159                      gpointer        data);
0160 /* return the first valid hook, and increment its reference count */
0161 GLIB_AVAILABLE_IN_ALL
0162 GHook*   g_hook_first_valid     (GHookList      *hook_list,
0163                      gboolean        may_be_in_call);
0164 /* return the next valid hook with incremented reference count, and
0165  * decrement the reference count of the original hook
0166  */
0167 GLIB_AVAILABLE_IN_ALL
0168 GHook*   g_hook_next_valid      (GHookList      *hook_list,
0169                      GHook          *hook,
0170                      gboolean        may_be_in_call);
0171 /* GHookCompareFunc implementation to insert hooks sorted by their id */
0172 GLIB_AVAILABLE_IN_ALL
0173 gint     g_hook_compare_ids     (GHook          *new_hook,
0174                      GHook          *sibling);
0175 /* convenience macros */
0176 #define  g_hook_append( hook_list, hook )  \
0177      g_hook_insert_before ((hook_list), NULL, (hook))
0178 /* invoke all valid hooks with the (*GHookFunc) signature.
0179  */
0180 GLIB_AVAILABLE_IN_ALL
0181 void     g_hook_list_invoke     (GHookList      *hook_list,
0182                      gboolean        may_recurse);
0183 /* invoke all valid hooks with the (*GHookCheckFunc) signature,
0184  * and destroy the hook if FALSE is returned.
0185  */
0186 GLIB_AVAILABLE_IN_ALL
0187 void     g_hook_list_invoke_check   (GHookList      *hook_list,
0188                      gboolean        may_recurse);
0189 /* invoke a marshaller on all valid hooks.
0190  */
0191 GLIB_AVAILABLE_IN_ALL
0192 void     g_hook_list_marshal        (GHookList      *hook_list,
0193                      gboolean        may_recurse,
0194                      GHookMarshaller     marshaller,
0195                      gpointer        marshal_data);
0196 GLIB_AVAILABLE_IN_ALL
0197 void     g_hook_list_marshal_check  (GHookList      *hook_list,
0198                      gboolean        may_recurse,
0199                      GHookCheckMarshaller    marshaller,
0200                      gpointer        marshal_data);
0201
0202 G_END_DECLS
0203
0204 #endif /* __G_HOOK_H__ */