1 /* GObject - GLib Type, Object, Parameter and Signal Library 2 * Copyright (C) 2000-2001 Red Hat, Inc. 3 * Copyright (C) 2005 Imendio AB 4 * 5 * This library is free software; you can redistribute it and/or 6 * modify it under the terms of the GNU Lesser General Public 7 * License as published by the Free Software Foundation; either 8 * version 2 of the License, or (at your option) any later version. 9 * 10 * This library is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 * Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General 16 * Public License along with this library; if not, write to the 17 * Free Software Foundation, Inc., 59 Temple Place, Suite 330, 18 * Boston, MA 02111-1307, USA. 19 */ 20 #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION) 21 #error "Only <glib-object.h> can be included directly." 22 #endif 23 24 #ifndef __G_CLOSURE_H__ 25 #define __G_CLOSURE_H__ 26 27 #include <gobject/gtype.h> 28 29 G_BEGIN_DECLS 30 31 /* --- defines --- */ 32 /** 33 * G_CLOSURE_NEEDS_MARSHAL: 34 * @closure: a #GClosure 35 * 36 * Check if the closure still needs a marshaller. See g_closure_set_marshal(). 37 * 38 * Returns: %TRUE if a #GClosureMarshal marshaller has not yet been set on 39 * @closure. 40 */ 41 #define G_CLOSURE_NEEDS_MARSHAL(closure) (((GClosure*) (closure))->marshal == NULL) 42 /** 43 * G_CLOSURE_N_NOTIFIERS: 44 * @cl: a #GClosure 45 * 46 * Get the total number of notifiers connected with the closure @cl. 47 * The count includes the meta marshaller, the finalize and invalidate notifiers 48 * and the marshal guards. Note that each guard counts as two notifiers. 49 * See g_closure_set_meta_marshal(), g_closure_add_finalize_notifier(), 50 * g_closure_add_invalidate_notifier() and g_closure_add_marshal_guards(). 51 * 52 * Returns: number of notifiers 53 */ 54 #define G_CLOSURE_N_NOTIFIERS(cl) ((cl)->meta_marshal + ((cl)->n_guards << 1L) + \ 55 (cl)->n_fnotifiers + (cl)->n_inotifiers) 56 /** 57 * G_CCLOSURE_SWAP_DATA: 58 * @cclosure: a #GCClosure 59 * 60 * Checks whether the user data of the #GCClosure should be passed as the 61 * first parameter to the callback. See g_cclosure_new_swap(). 62 * 63 * Returns: %TRUE if data has to be swapped. 64 */ 65 #define G_CCLOSURE_SWAP_DATA(cclosure) (((GClosure*) (cclosure))->derivative_flag) 66 /** 67 * G_CALLBACK: 68 * @f: a function pointer. 69 * 70 * Cast a function pointer to a #GCallback. 71 */ 72 #define G_CALLBACK(f) ((GCallback) (f)) 73 74 75 /* -- typedefs --- */ 76 typedef struct _GClosure GClosure; 77 typedef struct _GClosureNotifyData GClosureNotifyData; 78 79 /** 80 * GCallback: 81 * 82 * The type used for callback functions in structure definitions and function 83 * signatures. This doesn't mean that all callback functions must take no 84 * parameters and return void. The required signature of a callback function 85 * is determined by the context in which is used (e.g. the signal to which it 86 * is connected). Use G_CALLBACK() to cast the callback function to a #GCallback. 87 */ 88 typedef void (*GCallback) (void); 89 /** 90 * GClosureNotify: 91 * @data: data specified when registering the notification callback 92 * @closure: the #GClosure on which the notification is emitted 93 * 94 * The type used for the various notification callbacks which can be registered 95 * on closures. 96 */ 97 typedef void (*GClosureNotify) (gpointer data, 98 GClosure *closure); 99 /** 100 * GClosureMarshal: 101 * @closure: the #GClosure to which the marshaller belongs 102 * @return_value: a #GValue to store the return value. May be %NULL if the 103 * callback of @closure doesn't return a value. 104 * @n_param_values: the length of the @param_values array 105 * @param_values: an array of #GValue<!-- -->s holding the arguments on 106 * which to invoke the callback of @closure 107 * @invocation_hint: the invocation hint given as the last argument 108 * to g_closure_invoke() 109 * @marshal_data: additional data specified when registering the marshaller, 110 * see g_closure_set_marshal() and g_closure_set_meta_marshal() 111 * 112 * The type used for marshaller functions. 113 */ 114 typedef void (*GClosureMarshal) (GClosure *closure, 115 GValue *return_value, 116 guint n_param_values, 117 const GValue *param_values, 118 gpointer invocation_hint, 119 gpointer marshal_data); 120 /** 121 * GCClosure: 122 * @closure: the #GClosure 123 * @callback: the callback function 124 * 125 * A #GCClosure is a specialization of #GClosure for C function callbacks. 126 */ 127 typedef struct _GCClosure GCClosure; 128 129 130 /* --- structures --- */ 131 struct _GClosureNotifyData 132 { 133 gpointer data; 134 GClosureNotify notify; 135 }; 136 /** 137 * GClosure: 138 * @in_marshal: Indicates whether the closure is currently being invoked with 139 * g_closure_invoke() 140 * @is_invalid: Indicates whether the closure has been invalidated by 141 * g_closure_invalidate() 142 * 143 * A #GClosure represents a callback supplied by the programmer. 144 */ 145 struct _GClosure 146 { 147 /*< private >*/ 148 volatile guint ref_count : 15; 149 volatile guint meta_marshal : 1; 150 volatile guint n_guards : 1; 151 volatile guint n_fnotifiers : 2; /* finalization notifiers */ 152 volatile guint n_inotifiers : 8; /* invalidation notifiers */ 153 volatile guint in_inotify : 1; 154 volatile guint floating : 1; 155 /*< protected >*/ 156 volatile guint derivative_flag : 1; 157 /*< public >*/ 158 volatile guint in_marshal : 1; 159 volatile guint is_invalid : 1; 160 161 /*< private >*/ void (*marshal) (GClosure *closure, 162 GValue /*out*/ *return_value, 163 guint n_param_values, 164 const GValue *param_values, 165 gpointer invocation_hint, 166 gpointer marshal_data); 167 /*< protected >*/ gpointer data; 168 169 /*< private >*/ GClosureNotifyData *notifiers; 170 171 /* invariants/constrains: 172 * - ->marshal and ->data are _invalid_ as soon as ->is_invalid==TRUE 173 * - invocation of all inotifiers occours prior to fnotifiers 174 * - order of inotifiers is random 175 * inotifiers may _not_ free/invalidate parameter values (e.g. ->data) 176 * - order of fnotifiers is random 177 * - each notifier may only be removed before or during its invocation 178 * - reference counting may only happen prior to fnotify invocation 179 * (in that sense, fnotifiers are really finalization handlers) 180 */ 181 }; 182 /* closure for C function calls, callback() is the user function 183 */ 184 struct _GCClosure 185 { 186 GClosure closure; 187 gpointer callback; 188 }; 189 190 191 /* --- prototypes --- */ 192 GClosure* g_cclosure_new (GCallback callback_func, 193 gpointer user_data, 194 GClosureNotify destroy_data); 195 GClosure* g_cclosure_new_swap (GCallback callback_func, 196 gpointer user_data, 197 GClosureNotify destroy_data); 198 GClosure* g_signal_type_cclosure_new (GType itype, 199 guint struct_offset); 200 201 202 /* --- prototypes --- */ 203 GClosure* g_closure_ref (GClosure *closure); 204 void g_closure_sink (GClosure *closure); 205 void g_closure_unref (GClosure *closure); 206 /* intimidating */ 207 GClosure* g_closure_new_simple (guint sizeof_closure, 208 gpointer data); 209 void g_closure_add_finalize_notifier (GClosure *closure, 210 gpointer notify_data, 211 GClosureNotify notify_func); 212 void g_closure_remove_finalize_notifier (GClosure *closure, 213 gpointer notify_data, 214 GClosureNotify notify_func); 215 void g_closure_add_invalidate_notifier (GClosure *closure, 216 gpointer notify_data, 217 GClosureNotify notify_func); 218 void g_closure_remove_invalidate_notifier (GClosure *closure, 219 gpointer notify_data, 220 GClosureNotify notify_func); 221 void g_closure_add_marshal_guards (GClosure *closure, 222 gpointer pre_marshal_data, 223 GClosureNotify pre_marshal_notify, 224 gpointer post_marshal_data, 225 GClosureNotify post_marshal_notify); 226 void g_closure_set_marshal (GClosure *closure, 227 GClosureMarshal marshal); 228 void g_closure_set_meta_marshal (GClosure *closure, 229 gpointer marshal_data, 230 GClosureMarshal meta_marshal); 231 void g_closure_invalidate (GClosure *closure); 232 void g_closure_invoke (GClosure *closure, 233 GValue /*out*/ *return_value, 234 guint n_param_values, 235 const GValue *param_values, 236 gpointer invocation_hint); 237 238 /* FIXME: 239 OK: data_object::destroy -> closure_invalidate(); 240 MIS: closure_invalidate() -> disconnect(closure); 241 MIS: disconnect(closure) -> (unlink) closure_unref(); 242 OK: closure_finalize() -> g_free (data_string); 243 244 random remarks: 245 - need marshaller repo with decent aliasing to base types 246 - provide marshaller collection, virtually covering anything out there 247 */ 248 249 G_END_DECLS 250 251 #endif /* __G_CLOSURE_H__ */ 252
