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.1 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, see <http://www.gnu.org/licenses/>. 17 */ 18 #ifndef __G_CLOSURE_H__ 19 #define __G_CLOSURE_H__ 20 21 #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION) 22 #error "Only <glib-object.h> can be included directly." 23 #endif 24 25 #include <gobject/gtype.h> 26 27 G_BEGIN_DECLS 28 29 /* --- defines --- */ 30 /** 31 * G_CLOSURE_NEEDS_MARSHAL: 32 * @closure: a #GClosure 33 * 34 * Check if the closure still needs a marshaller. See g_closure_set_marshal(). 35 * 36 * Returns: %TRUE if a #GClosureMarshal marshaller has not yet been set on 37 * @closure. 38 */ 39 #define G_CLOSURE_NEEDS_MARSHAL(closure) (((GClosure*) (closure))->marshal == NULL) 40 /** 41 * G_CLOSURE_N_NOTIFIERS: 42 * @cl: a #GClosure 43 * 44 * Get the total number of notifiers connected with the closure @cl. 45 * 46 * The count includes the meta marshaller, the finalize and invalidate notifiers 47 * and the marshal guards. Note that each guard counts as two notifiers. 48 * See g_closure_set_meta_marshal(), g_closure_add_finalize_notifier(), 49 * g_closure_add_invalidate_notifier() and g_closure_add_marshal_guards(). 50 * 51 * Returns: number of notifiers 52 */ 53 #define G_CLOSURE_N_NOTIFIERS(cl) (((cl)->n_guards << 1L) + \ 54 (cl)->n_fnotifiers + (cl)->n_inotifiers) 55 /** 56 * G_CCLOSURE_SWAP_DATA: 57 * @cclosure: a #GCClosure 58 * 59 * Checks whether the user data of the #GCClosure should be passed as the 60 * first parameter to the callback. See g_cclosure_new_swap(). 61 * 62 * Returns: %TRUE if data has to be swapped. 63 */ 64 #define G_CCLOSURE_SWAP_DATA(cclosure) (((GClosure*) (cclosure))->derivative_flag) 65 /** 66 * G_CALLBACK: 67 * @f: a function pointer. 68 * 69 * Cast a function pointer to a #GCallback. 70 */ 71 #define G_CALLBACK(f) ((GCallback) (f)) 72 73 74 /* -- typedefs --- */ 75 typedef struct _GClosure GClosure; 76 typedef struct _GClosureNotifyData GClosureNotifyData; 77 78 /** 79 * GCallback: 80 * 81 * The type used for callback functions in structure definitions and function 82 * signatures. 83 * 84 * This doesn't mean that all callback functions must take no parameters and 85 * return void. The required signature of a callback function is determined by 86 * the context in which is used (e.g. the signal to which it is connected). 87 * 88 * Use G_CALLBACK() to cast the callback function to a #GCallback. 89 */ 90 typedef void (*GCallback) (void); 91 /** 92 * GClosureNotify: 93 * @data: data specified when registering the notification callback 94 * @closure: the #GClosure on which the notification is emitted 95 * 96 * The type used for the various notification callbacks which can be registered 97 * on closures. 98 */ 99 typedef void (*GClosureNotify) (gpointer data, 100 GClosure *closure); 101 /** 102 * GClosureMarshal: 103 * @closure: the #GClosure to which the marshaller belongs 104 * @return_value: (nullable): a #GValue to store the return 105 * value. May be %NULL if the callback of @closure doesn't return a 106 * value. 107 * @n_param_values: the length of the @param_values array 108 * @param_values: (array length=n_param_values): an array of 109 * #GValues holding the arguments on which to invoke the 110 * callback of @closure 111 * @invocation_hint: (nullable): the invocation hint given as the 112 * last argument to g_closure_invoke() 113 * @marshal_data: (nullable): additional data specified when 114 * registering the marshaller, see g_closure_set_marshal() and 115 * g_closure_set_meta_marshal() 116 * 117 * The type used for marshaller functions. 118 */ 119 typedef void (*GClosureMarshal) (GClosure *closure, 120 GValue *return_value, 121 guint n_param_values, 122 const GValue *param_values, 123 gpointer invocation_hint, 124 gpointer marshal_data); 125 126 /** 127 * GVaClosureMarshal: 128 * @closure: the #GClosure to which the marshaller belongs 129 * @return_value: (nullable): a #GValue to store the return 130 * value. May be %NULL if the callback of @closure doesn't return a 131 * value. 132 * @instance: (type GObject.TypeInstance): the instance on which the closure is 133 * invoked. 134 * @args: va_list of arguments to be passed to the closure. 135 * @marshal_data: (nullable): additional data specified when 136 * registering the marshaller, see g_closure_set_marshal() and 137 * g_closure_set_meta_marshal() 138 * @n_params: the length of the @param_types array 139 * @param_types: (array length=n_params): the #GType of each argument from 140 * @args. 141 * 142 * This is the signature of va_list marshaller functions, an optional 143 * marshaller that can be used in some situations to avoid 144 * marshalling the signal argument into GValues. 145 */ 146 typedef void (* GVaClosureMarshal) (GClosure *closure, 147 GValue *return_value, 148 gpointer instance, 149 va_list args, 150 gpointer marshal_data, 151 int n_params, 152 GType *param_types); 153 154 /** 155 * GCClosure: 156 * @closure: the #GClosure 157 * @callback: the callback function 158 * 159 * A #GCClosure is a specialization of #GClosure for C function callbacks. 160 */ 161 typedef struct _GCClosure GCClosure; 162 163 164 /* --- structures --- */ 165 struct _GClosureNotifyData 166 { 167 gpointer data; 168 GClosureNotify notify; 169 }; 170 /** 171 * GClosure: 172 * @in_marshal: Indicates whether the closure is currently being invoked with 173 * g_closure_invoke() 174 * @is_invalid: Indicates whether the closure has been invalidated by 175 * g_closure_invalidate() 176 * 177 * A #GClosure represents a callback supplied by the programmer. 178 */ 179 struct _GClosure 180 { 181 /*< private >*/ 182 guint ref_count : 15; /* (atomic) */ 183 /* meta_marshal is not used anymore but must be zero for historical reasons 184 as it was exposed in the G_CLOSURE_N_NOTIFIERS macro */ 185 guint meta_marshal_nouse : 1; /* (atomic) */ 186 guint n_guards : 1; /* (atomic) */ 187 guint n_fnotifiers : 2; /* finalization notifiers (atomic) */ 188 guint n_inotifiers : 8; /* invalidation notifiers (atomic) */ 189 guint in_inotify : 1; /* (atomic) */ 190 guint floating : 1; /* (atomic) */ 191 /*< protected >*/ 192 guint derivative_flag : 1; /* (atomic) */ 193 /*< public >*/ 194 guint in_marshal : 1; /* (atomic) */ 195 guint is_invalid : 1; /* (atomic) */ 196 197 /*< private >*/ void (*marshal) (GClosure *closure, 198 GValue /*out*/ *return_value, 199 guint n_param_values, 200 const GValue *param_values, 201 gpointer invocation_hint, 202 gpointer marshal_data); 203 /*< protected >*/ gpointer data; 204 205 /*< private >*/ GClosureNotifyData *notifiers; 206 207 /* invariants/constraints: 208 * - ->marshal and ->data are _invalid_ as soon as ->is_invalid==TRUE 209 * - invocation of all inotifiers occurs prior to fnotifiers 210 * - order of inotifiers is random 211 * inotifiers may _not_ free/invalidate parameter values (e.g. ->data) 212 * - order of fnotifiers is random 213 * - each notifier may only be removed before or during its invocation 214 * - reference counting may only happen prior to fnotify invocation 215 * (in that sense, fnotifiers are really finalization handlers) 216 */ 217 }; 218 /* closure for C function calls, callback() is the user function 219 */ 220 struct _GCClosure 221 { 222 GClosure closure; 223 gpointer callback; 224 }; 225 226 227 /* --- prototypes --- */ 228 GLIB_AVAILABLE_IN_ALL 229 GClosure* g_cclosure_new (GCallback callback_func, 230 gpointer user_data, 231 GClosureNotify destroy_data); 232 GLIB_AVAILABLE_IN_ALL 233 GClosure* g_cclosure_new_swap (GCallback callback_func, 234 gpointer user_data, 235 GClosureNotify destroy_data); 236 GLIB_AVAILABLE_IN_ALL 237 GClosure* g_signal_type_cclosure_new (GType itype, 238 guint struct_offset); 239 240 241 /* --- prototypes --- */ 242 GLIB_AVAILABLE_IN_ALL 243 GClosure* g_closure_ref (GClosure *closure); 244 GLIB_AVAILABLE_IN_ALL 245 void g_closure_sink (GClosure *closure); 246 GLIB_AVAILABLE_IN_ALL 247 void g_closure_unref (GClosure *closure); 248 /* intimidating */ 249 GLIB_AVAILABLE_IN_ALL 250 GClosure* g_closure_new_simple (guint sizeof_closure, 251 gpointer data); 252 GLIB_AVAILABLE_IN_ALL 253 void g_closure_add_finalize_notifier (GClosure *closure, 254 gpointer notify_data, 255 GClosureNotify notify_func); 256 GLIB_AVAILABLE_IN_ALL 257 void g_closure_remove_finalize_notifier (GClosure *closure, 258 gpointer notify_data, 259 GClosureNotify notify_func); 260 GLIB_AVAILABLE_IN_ALL 261 void g_closure_add_invalidate_notifier (GClosure *closure, 262 gpointer notify_data, 263 GClosureNotify notify_func); 264 GLIB_AVAILABLE_IN_ALL 265 void g_closure_remove_invalidate_notifier (GClosure *closure, 266 gpointer notify_data, 267 GClosureNotify notify_func); 268 GLIB_AVAILABLE_IN_ALL 269 void g_closure_add_marshal_guards (GClosure *closure, 270 gpointer pre_marshal_data, 271 GClosureNotify pre_marshal_notify, 272 gpointer post_marshal_data, 273 GClosureNotify post_marshal_notify); 274 GLIB_AVAILABLE_IN_ALL 275 void g_closure_set_marshal (GClosure *closure, 276 GClosureMarshal marshal); 277 GLIB_AVAILABLE_IN_ALL 278 void g_closure_set_meta_marshal (GClosure *closure, 279 gpointer marshal_data, 280 GClosureMarshal meta_marshal); 281 GLIB_AVAILABLE_IN_ALL 282 void g_closure_invalidate (GClosure *closure); 283 GLIB_AVAILABLE_IN_ALL 284 void g_closure_invoke (GClosure *closure, 285 GValue /*out*/ *return_value, 286 guint n_param_values, 287 const GValue *param_values, 288 gpointer invocation_hint); 289 290 /* FIXME: 291 OK: data_object::destroy -> closure_invalidate(); 292 MIS: closure_invalidate() -> disconnect(closure); 293 MIS: disconnect(closure) -> (unlink) closure_unref(); 294 OK: closure_finalize() -> g_free (data_string); 295 296 random remarks: 297 - need marshaller repo with decent aliasing to base types 298 - provide marshaller collection, virtually covering anything out there 299 */ 300 301 GLIB_AVAILABLE_IN_ALL 302 void g_cclosure_marshal_generic (GClosure *closure, 303 GValue *return_gvalue, 304 guint n_param_values, 305 const GValue *param_values, 306 gpointer invocation_hint, 307 gpointer marshal_data); 308 309 GLIB_AVAILABLE_IN_ALL 310 void g_cclosure_marshal_generic_va (GClosure *closure, 311 GValue *return_value, 312 gpointer instance, 313 va_list args_list, 314 gpointer marshal_data, 315 int n_params, 316 GType *param_types); 317 318 319 G_END_DECLS 320 321 #endif /* __G_CLOSURE_H__ */ 322