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