1 /* GObject - GLib Type, Object, Parameter and Signal Library
2 * Copyright (C) 2000-2001 Red Hat, Inc.
3 * Copyright (C) 2005 Imendio AB
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.
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.
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.
22 * MT safe with regards to reference counting.
31 #include "gobjectalias.h"
36 * @short_description: Functions as first-class objects
39 * A #GClosure represents a callback supplied by the programmer. It
40 * will generally comprise a function of some kind and a marshaller
41 * used to call it. It is the reponsibility of the marshaller to
42 * convert the arguments for the invocation from #GValue<!-- -->s into
43 * a suitable form, perform the callback on the converted arguments,
44 * and transform the return value back into a #GValue.
46 * In the case of C programs, a closure usually just holds a pointer
47 * to a function and maybe a data argument, and the marshaller
48 * converts between #GValue<!-- --> and native C types. The GObject
49 * library provides the #GCClosure type for this purpose. Bindings for
50 * other languages need marshallers which convert between #GValue<!--
51 * -->s and suitable representations in the runtime of the language in
52 * order to use functions written in that languages as callbacks.
54 * Within GObject, closures play an important role in the
55 * implementation of signals. When a signal is registered, the
56 * @c_marshaller argument to g_signal_new() specifies the default C
57 * marshaller for any closure which is connected to this
58 * signal. GObject provides a number of C marshallers for this
59 * purpose, see the g_cclosure_marshal_*() functions. Additional C
60 * marshallers can be generated with the <link
61 * linkend="glib-genmarshal">glib-genmarshal</link> utility. Closures
62 * can be explicitly connected to signals with
63 * g_signal_connect_closure(), but it usually more convenient to let
64 * GObject create a closure automatically by using one of the
65 * g_signal_connect_*() functions which take a callback function/user
68 * Using closures has a number of important advantages over a simple
69 * callback function/data pointer combination:
72 * Closures allow the callee to get the types of the callback parameters,
73 * which means that language bindings don't have to write individual glue
74 * for each callback type.
77 * The reference counting of #GClosure makes it easy to handle reentrancy
78 * right; if a callback is removed while it is being invoked, the closure
79 * and its parameters won't be freed until the invocation finishes.
82 * g_closure_invalidate() and invalidation notifiers allow callbacks to be
83 * automatically removed when the objects they point to go away.
89 #define CLOSURE_MAX_REF_COUNT ((1 << 15) - 1)
90 #define CLOSURE_MAX_N_GUARDS ((1 << 1) - 1)
91 #define CLOSURE_MAX_N_FNOTIFIERS ((1 << 2) - 1)
92 #define CLOSURE_MAX_N_INOTIFIERS ((1 << 8) - 1)
93 #define CLOSURE_N_MFUNCS(cl) ((cl)->meta_marshal + \
94 ((cl)->n_guards << 1L))
95 /* same as G_CLOSURE_N_NOTIFIERS() (keep in sync) */
96 #define CLOSURE_N_NOTIFIERS(cl) (CLOSURE_N_MFUNCS (cl) + \
97 (cl)->n_fnotifiers + \
105 #define CHANGE_FIELD(_closure, _field, _OP, _value, _must_set, _SET_OLD, _SET_NEW) \
107 ClosureInt *cunion = (ClosureInt*) _closure; \
108 gint new_int, old_int, success; \
112 tmp.vint = old_int = cunion->vint; \
113 _SET_OLD tmp.closure._field; \
114 tmp.closure._field _OP _value; \
115 _SET_NEW tmp.closure._field; \
116 new_int = tmp.vint; \
117 success = g_atomic_int_compare_and_exchange (&cunion->vint, old_int, new_int); \
119 while (!success && _must_set); \
122 #define SWAP(_closure, _field, _value, _oldv) CHANGE_FIELD (_closure, _field, =, _value, TRUE, *(_oldv) =, (void) )
123 #define SET(_closure, _field, _value) CHANGE_FIELD (_closure, _field, =, _value, TRUE, (void), (void) )
124 #define INC(_closure, _field) CHANGE_FIELD (_closure, _field, +=, 1, TRUE, (void), (void) )
125 #define INC_ASSIGN(_closure, _field, _newv) CHANGE_FIELD (_closure, _field, +=, 1, TRUE, (void), *(_newv) = )
126 #define DEC(_closure, _field) CHANGE_FIELD (_closure, _field, -=, 1, TRUE, (void), (void) )
127 #define DEC_ASSIGN(_closure, _field, _newv) CHANGE_FIELD (_closure, _field, -=, 1, TRUE, (void), *(_newv) = )
129 #if 0 /* for non-thread-safe closures */
130 #define SWAP(cl,f,v,o) (void) (*(o) = cl->f, cl->f = v)
131 #define SET(cl,f,v) (void) (cl->f = v)
132 #define INC(cl,f) (void) (cl->f += 1)
133 #define INC_ASSIGN(cl,f,n) (void) (cl->f += 1, *(n) = cl->f)
134 #define DEC(cl,f) (void) (cl->f -= 1)
135 #define DEC_ASSIGN(cl,f,n) (void) (cl->f -= 1, *(n) = cl->f)
146 /* --- functions --- */
148 * g_closure_new_simple:
149 * @sizeof_closure: the size of the structure to allocate, must be at least
150 * <literal>sizeof (GClosure)</literal>
151 * @data: data to store in the @data field of the newly allocated #GClosure
153 * Allocates a struct of the given size and initializes the initial
154 * part as a #GClosure. This function is mainly useful when
155 * implementing new types of closures.
158 * typedef struct _MyClosure MyClosure;
162 * // extra data goes here
166 * my_closure_finalize (gpointer notify_data,
169 * MyClosure *my_closure = (MyClosure *)closure;
171 * // free extra data here
174 * MyClosure *my_closure_new (gpointer data)
177 * MyClosure *my_closure;
179 * closure = g_closure_new_simple (sizeof (MyClosure), data);
180 * my_closure = (MyClosure *) closure;
182 * // initialize extra data here
184 * g_closure_add_finalize_notifier (closure, notify_data,
185 * my_closure_finalize);
190 * Returns: a newly allocated #GClosure
193 g_closure_new_simple (guint sizeof_closure
,
198 g_return_val_if_fail (sizeof_closure
>= sizeof (GClosure
), NULL
);
200 closure
= g_malloc0 (sizeof_closure
);
201 SET (closure
, ref_count
, 1);
202 SET (closure
, meta_marshal
, 0);
203 SET (closure
, n_guards
, 0);
204 SET (closure
, n_fnotifiers
, 0);
205 SET (closure
, n_inotifiers
, 0);
206 SET (closure
, in_inotify
, FALSE
);
207 SET (closure
, floating
, TRUE
);
208 SET (closure
, derivative_flag
, 0);
209 SET (closure
, in_marshal
, FALSE
);
210 SET (closure
, is_invalid
, FALSE
);
211 closure
->marshal
= NULL
;
212 closure
->data
= data
;
213 closure
->notifiers
= NULL
;
214 memset (G_STRUCT_MEMBER_P (closure
, sizeof (*closure
)), 0, sizeof_closure
- sizeof (*closure
));
220 closure_invoke_notifiers (GClosure
*closure
,
224 * meta_marshal n_guards n_guards n_fnotif. n_inotifiers
225 * ->[[meta_marshal][pre_guards][post_guards][fnotifiers][inotifiers]]
227 * CLOSURE_N_MFUNCS(cl) = meta_marshal + n_guards + n_guards;
228 * CLOSURE_N_NOTIFIERS(cl) = CLOSURE_N_MFUNCS(cl) + n_fnotifiers + n_inotifiers
230 * constrains/catches:
231 * - closure->notifiers may be reloacted during callback
232 * - closure->n_fnotifiers and closure->n_inotifiers may change during callback
233 * - i.e. callbacks can be removed/added during invocation
234 * - must prepare for callback removal during FNOTIFY and INOTIFY (done via ->marshal= & ->data=)
235 * - must distinguish (->marshal= & ->data=) for INOTIFY vs. FNOTIFY (via ->in_inotify)
236 * + closure->n_guards is const during PRE_NOTIFY & POST_NOTIFY
237 * + closure->meta_marshal is const for all cases
238 * + none of the callbacks can cause recursion
239 * + closure->n_inotifiers is const 0 during FNOTIFY
243 GClosureNotifyData
*ndata
;
246 while (closure
->n_fnotifiers
)
249 DEC_ASSIGN (closure
, n_fnotifiers
, &n
);
251 ndata
= closure
->notifiers
+ CLOSURE_N_MFUNCS (closure
) + n
;
252 closure
->marshal
= (GClosureMarshal
) ndata
->notify
;
253 closure
->data
= ndata
->data
;
254 ndata
->notify (ndata
->data
, closure
);
256 closure
->marshal
= NULL
;
257 closure
->data
= NULL
;
260 SET (closure
, in_inotify
, TRUE
);
261 while (closure
->n_inotifiers
)
264 DEC_ASSIGN (closure
, n_inotifiers
, &n
);
266 ndata
= closure
->notifiers
+ CLOSURE_N_MFUNCS (closure
) + closure
->n_fnotifiers
+ n
;
267 closure
->marshal
= (GClosureMarshal
) ndata
->notify
;
268 closure
->data
= ndata
->data
;
269 ndata
->notify (ndata
->data
, closure
);
271 closure
->marshal
= NULL
;
272 closure
->data
= NULL
;
273 SET (closure
, in_inotify
, FALSE
);
276 i
= closure
->n_guards
;
277 offs
= closure
->meta_marshal
;
280 ndata
= closure
->notifiers
+ offs
+ i
;
281 ndata
->notify (ndata
->data
, closure
);
285 i
= closure
->n_guards
;
286 offs
= closure
->meta_marshal
+ i
;
289 ndata
= closure
->notifiers
+ offs
+ i
;
290 ndata
->notify (ndata
->data
, closure
);
297 * g_closure_set_meta_marshal:
298 * @closure: a #GClosure
299 * @marshal_data: context-dependent data to pass to @meta_marshal
300 * @meta_marshal: a #GClosureMarshal function
302 * Sets the meta marshaller of @closure. A meta marshaller wraps
303 * @closure->marshal and modifies the way it is called in some
304 * fashion. The most common use of this facility is for C callbacks.
305 * The same marshallers (generated by <link
306 * linkend="glib-genmarshal">glib-genmarshal</link>) are used
307 * everywhere, but the way that we get the callback function
308 * differs. In most cases we want to use @closure->callback, but in
309 * other cases we want to use some different technique to retrieve the
312 * For example, class closures for signals (see
313 * g_signal_type_cclosure_new()) retrieve the callback function from a
314 * fixed offset in the class structure. The meta marshaller retrieves
315 * the right callback and passes it to the marshaller as the
316 * @marshal_data argument.
319 g_closure_set_meta_marshal (GClosure
*closure
,
320 gpointer marshal_data
,
321 GClosureMarshal meta_marshal
)
323 GClosureNotifyData
*notifiers
;
325 g_return_if_fail (closure
!= NULL
);
326 g_return_if_fail (meta_marshal
!= NULL
);
327 g_return_if_fail (closure
->is_invalid
== FALSE
);
328 g_return_if_fail (closure
->in_marshal
== FALSE
);
329 g_return_if_fail (closure
->meta_marshal
== 0);
331 notifiers
= closure
->notifiers
;
332 closure
->notifiers
= g_renew (GClosureNotifyData
, NULL
, CLOSURE_N_NOTIFIERS (closure
) + 1);
335 /* usually the meta marshal will be setup right after creation, so the
336 * g_memmove() should be rare-case scenario
338 g_memmove (closure
->notifiers
+ 1, notifiers
, CLOSURE_N_NOTIFIERS (closure
) * sizeof (notifiers
[0]));
341 closure
->notifiers
[0].data
= marshal_data
;
342 closure
->notifiers
[0].notify
= (GClosureNotify
) meta_marshal
;
343 SET (closure
, meta_marshal
, 1);
347 * g_closure_add_marshal_guards:
348 * @closure: a #GClosure
349 * @pre_marshal_data: data to pass to @pre_marshal_notify
350 * @pre_marshal_notify: a function to call before the closure callback
351 * @post_marshal_data: data to pass to @post_marshal_notify
352 * @post_marshal_notify: a function to call after the closure callback
354 * Adds a pair of notifiers which get invoked before and after the
355 * closure callback, respectively. This is typically used to protect
356 * the extra arguments for the duration of the callback. See
357 * g_object_watch_closure() for an example of marshal guards.
360 g_closure_add_marshal_guards (GClosure
*closure
,
361 gpointer pre_marshal_data
,
362 GClosureNotify pre_marshal_notify
,
363 gpointer post_marshal_data
,
364 GClosureNotify post_marshal_notify
)
368 g_return_if_fail (closure
!= NULL
);
369 g_return_if_fail (pre_marshal_notify
!= NULL
);
370 g_return_if_fail (post_marshal_notify
!= NULL
);
371 g_return_if_fail (closure
->is_invalid
== FALSE
);
372 g_return_if_fail (closure
->in_marshal
== FALSE
);
373 g_return_if_fail (closure
->n_guards
< CLOSURE_MAX_N_GUARDS
);
375 closure
->notifiers
= g_renew (GClosureNotifyData
, closure
->notifiers
, CLOSURE_N_NOTIFIERS (closure
) + 2);
376 if (closure
->n_inotifiers
)
377 closure
->notifiers
[(CLOSURE_N_MFUNCS (closure
) +
378 closure
->n_fnotifiers
+
379 closure
->n_inotifiers
+ 1)] = closure
->notifiers
[(CLOSURE_N_MFUNCS (closure
) +
380 closure
->n_fnotifiers
+ 0)];
381 if (closure
->n_inotifiers
> 1)
382 closure
->notifiers
[(CLOSURE_N_MFUNCS (closure
) +
383 closure
->n_fnotifiers
+
384 closure
->n_inotifiers
)] = closure
->notifiers
[(CLOSURE_N_MFUNCS (closure
) +
385 closure
->n_fnotifiers
+ 1)];
386 if (closure
->n_fnotifiers
)
387 closure
->notifiers
[(CLOSURE_N_MFUNCS (closure
) +
388 closure
->n_fnotifiers
+ 1)] = closure
->notifiers
[CLOSURE_N_MFUNCS (closure
) + 0];
389 if (closure
->n_fnotifiers
> 1)
390 closure
->notifiers
[(CLOSURE_N_MFUNCS (closure
) +
391 closure
->n_fnotifiers
)] = closure
->notifiers
[CLOSURE_N_MFUNCS (closure
) + 1];
392 if (closure
->n_guards
)
393 closure
->notifiers
[(closure
->meta_marshal
+
395 closure
->n_guards
+ 1)] = closure
->notifiers
[closure
->meta_marshal
+ closure
->n_guards
];
396 i
= closure
->n_guards
;
397 closure
->notifiers
[closure
->meta_marshal
+ i
].data
= pre_marshal_data
;
398 closure
->notifiers
[closure
->meta_marshal
+ i
].notify
= pre_marshal_notify
;
399 closure
->notifiers
[closure
->meta_marshal
+ i
+ 1].data
= post_marshal_data
;
400 closure
->notifiers
[closure
->meta_marshal
+ i
+ 1].notify
= post_marshal_notify
;
401 INC (closure
, n_guards
);
405 * g_closure_add_finalize_notifier:
406 * @closure: a #GClosure
407 * @notify_data: data to pass to @notify_func
408 * @notify_func: the callback function to register
410 * Registers a finalization notifier which will be called when the
411 * reference count of @closure goes down to 0. Multiple finalization
412 * notifiers on a single closure are invoked in unspecified order. If
413 * a single call to g_closure_unref() results in the closure being
414 * both invalidated and finalized, then the invalidate notifiers will
415 * be run before the finalize notifiers.
418 g_closure_add_finalize_notifier (GClosure
*closure
,
419 gpointer notify_data
,
420 GClosureNotify notify_func
)
424 g_return_if_fail (closure
!= NULL
);
425 g_return_if_fail (notify_func
!= NULL
);
426 g_return_if_fail (closure
->n_fnotifiers
< CLOSURE_MAX_N_FNOTIFIERS
);
428 closure
->notifiers
= g_renew (GClosureNotifyData
, closure
->notifiers
, CLOSURE_N_NOTIFIERS (closure
) + 1);
429 if (closure
->n_inotifiers
)
430 closure
->notifiers
[(CLOSURE_N_MFUNCS (closure
) +
431 closure
->n_fnotifiers
+
432 closure
->n_inotifiers
)] = closure
->notifiers
[(CLOSURE_N_MFUNCS (closure
) +
433 closure
->n_fnotifiers
+ 0)];
434 i
= CLOSURE_N_MFUNCS (closure
) + closure
->n_fnotifiers
;
435 closure
->notifiers
[i
].data
= notify_data
;
436 closure
->notifiers
[i
].notify
= notify_func
;
437 INC (closure
, n_fnotifiers
);
441 * g_closure_add_invalidate_notifier:
442 * @closure: a #GClosure
443 * @notify_data: data to pass to @notify_func
444 * @notify_func: the callback function to register
446 * Registers an invalidation notifier which will be called when the
447 * @closure is invalidated with g_closure_invalidate(). Invalidation
448 * notifiers are invoked before finalization notifiers, in an
452 g_closure_add_invalidate_notifier (GClosure
*closure
,
453 gpointer notify_data
,
454 GClosureNotify notify_func
)
458 g_return_if_fail (closure
!= NULL
);
459 g_return_if_fail (notify_func
!= NULL
);
460 g_return_if_fail (closure
->is_invalid
== FALSE
);
461 g_return_if_fail (closure
->n_inotifiers
< CLOSURE_MAX_N_INOTIFIERS
);
463 closure
->notifiers
= g_renew (GClosureNotifyData
, closure
->notifiers
, CLOSURE_N_NOTIFIERS (closure
) + 1);
464 i
= CLOSURE_N_MFUNCS (closure
) + closure
->n_fnotifiers
+ closure
->n_inotifiers
;
465 closure
->notifiers
[i
].data
= notify_data
;
466 closure
->notifiers
[i
].notify
= notify_func
;
467 INC (closure
, n_inotifiers
);
470 static inline gboolean
471 closure_try_remove_inotify (GClosure
*closure
,
472 gpointer notify_data
,
473 GClosureNotify notify_func
)
475 GClosureNotifyData
*ndata
, *nlast
;
477 nlast
= closure
->notifiers
+ CLOSURE_N_NOTIFIERS (closure
) - 1;
478 for (ndata
= nlast
+ 1 - closure
->n_inotifiers
; ndata
<= nlast
; ndata
++)
479 if (ndata
->notify
== notify_func
&& ndata
->data
== notify_data
)
481 DEC (closure
, n_inotifiers
);
490 static inline gboolean
491 closure_try_remove_fnotify (GClosure
*closure
,
492 gpointer notify_data
,
493 GClosureNotify notify_func
)
495 GClosureNotifyData
*ndata
, *nlast
;
497 nlast
= closure
->notifiers
+ CLOSURE_N_NOTIFIERS (closure
) - closure
->n_inotifiers
- 1;
498 for (ndata
= nlast
+ 1 - closure
->n_fnotifiers
; ndata
<= nlast
; ndata
++)
499 if (ndata
->notify
== notify_func
&& ndata
->data
== notify_data
)
501 DEC (closure
, n_fnotifiers
);
504 if (closure
->n_inotifiers
)
505 closure
->notifiers
[(CLOSURE_N_MFUNCS (closure
) +
506 closure
->n_fnotifiers
)] = closure
->notifiers
[(CLOSURE_N_MFUNCS (closure
) +
507 closure
->n_fnotifiers
+
508 closure
->n_inotifiers
)];
516 * @closure: #GClosure to increment the reference count on
518 * Increments the reference count on a closure to force it staying
519 * alive while the caller holds a pointer to it.
521 * Returns: The @closure passed in, for convenience
524 g_closure_ref (GClosure
*closure
)
527 g_return_val_if_fail (closure
!= NULL
, NULL
);
528 g_return_val_if_fail (closure
->ref_count
> 0, NULL
);
529 g_return_val_if_fail (closure
->ref_count
< CLOSURE_MAX_REF_COUNT
, NULL
);
531 INC_ASSIGN (closure
, ref_count
, &new_ref_count
);
532 g_return_val_if_fail (new_ref_count
> 1, NULL
);
538 * g_closure_invalidate:
539 * @closure: GClosure to invalidate
541 * Sets a flag on the closure to indicate that its calling
542 * environment has become invalid, and thus causes any future
543 * invocations of g_closure_invoke() on this @closure to be
544 * ignored. Also, invalidation notifiers installed on the closure will
545 * be called at this point. Note that unless you are holding a
546 * reference to the closure yourself, the invalidation notifiers may
547 * unref the closure and cause it to be destroyed, so if you need to
548 * access the closure after calling g_closure_invalidate(), make sure
549 * that you've previously called g_closure_ref().
551 * Note that g_closure_invalidate() will also be called when the
552 * reference count of a closure drops to zero (unless it has already
553 * been invalidated before).
556 g_closure_invalidate (GClosure
*closure
)
558 g_return_if_fail (closure
!= NULL
);
560 if (!closure
->is_invalid
)
562 gboolean was_invalid
;
563 g_closure_ref (closure
); /* preserve floating flag */
564 SWAP (closure
, is_invalid
, TRUE
, &was_invalid
);
565 /* invalidate only once */
567 closure_invoke_notifiers (closure
, INOTIFY
);
568 g_closure_unref (closure
);
574 * @closure: #GClosure to decrement the reference count on
576 * Decrements the reference count of a closure after it was previously
577 * incremented by the same caller. If no other callers are using the
578 * closure, then the closure will be destroyed and freed.
581 g_closure_unref (GClosure
*closure
)
585 g_return_if_fail (closure
!= NULL
);
586 g_return_if_fail (closure
->ref_count
> 0);
588 if (closure
->ref_count
== 1) /* last unref, invalidate first */
589 g_closure_invalidate (closure
);
591 DEC_ASSIGN (closure
, ref_count
, &new_ref_count
);
593 if (new_ref_count
== 0)
595 closure_invoke_notifiers (closure
, FNOTIFY
);
596 g_free (closure
->notifiers
);
603 * @closure: #GClosure to decrement the initial reference count on, if it's
606 * Takes over the initial ownership of a closure. Each closure is
607 * initially created in a <firstterm>floating</firstterm> state, which
608 * means that the initial reference count is not owned by any caller.
609 * g_closure_sink() checks to see if the object is still floating, and
610 * if so, unsets the floating state and decreases the reference
611 * count. If the closure is not floating, g_closure_sink() does
612 * nothing. The reason for the existance of the floating state is to
613 * prevent cumbersome code sequences like:
615 * closure = g_cclosure_new (cb_func, cb_data);
616 * g_source_set_closure (source, closure);
617 * g_closure_unref (closure); // XXX GObject doesn't really need this
619 * Because g_source_set_closure() (and similar functions) take ownership of the
620 * initial reference count, if it is unowned, we instead can write:
622 * g_source_set_closure (source, g_cclosure_new (cb_func, cb_data));
625 * Generally, this function is used together with g_closure_ref(). Ane example
626 * of storing a closure for later notification looks like:
628 * static GClosure *notify_closure = NULL;
630 * foo_notify_set_closure (GClosure *closure)
632 * if (notify_closure)
633 * g_closure_unref (notify_closure);
634 * notify_closure = closure;
635 * if (notify_closure)
637 * g_closure_ref (notify_closure);
638 * g_closure_sink (notify_closure);
643 * Because g_closure_sink() may decrement the reference count of a closure
644 * (if it hasn't been called on @closure yet) just like g_closure_unref(),
645 * g_closure_ref() should be called prior to this function.
648 g_closure_sink (GClosure
*closure
)
650 g_return_if_fail (closure
!= NULL
);
651 g_return_if_fail (closure
->ref_count
> 0);
653 /* floating is basically a kludge to avoid creating closures
654 * with a ref_count of 0. so the intial ref_count a closure has
655 * is unowned. with invoking g_closure_sink() code may
656 * indicate that it takes over that intiial ref_count.
658 if (closure
->floating
)
660 gboolean was_floating
;
661 SWAP (closure
, floating
, FALSE
, &was_floating
);
662 /* unref floating flag only once */
664 g_closure_unref (closure
);
669 * g_closure_remove_invalidate_notifier:
670 * @closure: a #GClosure
671 * @notify_data: data which was passed to g_closure_add_invalidate_notifier()
672 * when registering @notify_func
673 * @notify_func: the callback function to remove
675 * Removes an invalidation notifier.
677 * Notice that notifiers are automatically removed after they are run.
680 g_closure_remove_invalidate_notifier (GClosure
*closure
,
681 gpointer notify_data
,
682 GClosureNotify notify_func
)
684 g_return_if_fail (closure
!= NULL
);
685 g_return_if_fail (notify_func
!= NULL
);
687 if (closure
->is_invalid
&& closure
->in_inotify
&& /* account removal of notify_func() while it's called */
688 ((gpointer
) closure
->marshal
) == ((gpointer
) notify_func
) &&
689 closure
->data
== notify_data
)
690 closure
->marshal
= NULL
;
691 else if (!closure_try_remove_inotify (closure
, notify_data
, notify_func
))
692 g_warning (G_STRLOC
": unable to remove uninstalled invalidation notifier: %p (%p)",
693 notify_func
, notify_data
);
697 * g_closure_remove_finalize_notifier:
698 * @closure: a #GClosure
699 * @notify_data: data which was passed to g_closure_add_finalize_notifier()
700 * when registering @notify_func
701 * @notify_func: the callback function to remove
703 * Removes a finalization notifier.
705 * Notice that notifiers are automatically removed after they are run.
708 g_closure_remove_finalize_notifier (GClosure
*closure
,
709 gpointer notify_data
,
710 GClosureNotify notify_func
)
712 g_return_if_fail (closure
!= NULL
);
713 g_return_if_fail (notify_func
!= NULL
);
715 if (closure
->is_invalid
&& !closure
->in_inotify
&& /* account removal of notify_func() while it's called */
716 ((gpointer
) closure
->marshal
) == ((gpointer
) notify_func
) &&
717 closure
->data
== notify_data
)
718 closure
->marshal
= NULL
;
719 else if (!closure_try_remove_fnotify (closure
, notify_data
, notify_func
))
720 g_warning (G_STRLOC
": unable to remove uninstalled finalization notifier: %p (%p)",
721 notify_func
, notify_data
);
726 * @closure: a #GClosure
727 * @return_value: a #GValue to store the return value. May be %NULL if the
728 * callback of @closure doesn't return a value.
729 * @n_param_values: the length of the @param_values array
730 * @param_values: an array of #GValue<!-- -->s holding the arguments on
731 * which to invoke the callback of @closure
732 * @invocation_hint: a context-dependent invocation hint
734 * Invokes the closure, i.e. executes the callback represented by the @closure.
737 g_closure_invoke (GClosure
*closure
,
738 GValue
/*out*/ *return_value
,
739 guint n_param_values
,
740 const GValue
*param_values
,
741 gpointer invocation_hint
)
743 g_return_if_fail (closure
!= NULL
);
745 g_closure_ref (closure
); /* preserve floating flag */
746 if (!closure
->is_invalid
)
748 GClosureMarshal marshal
;
749 gpointer marshal_data
;
750 gboolean in_marshal
= closure
->in_marshal
;
752 g_return_if_fail (closure
->marshal
|| closure
->meta_marshal
);
754 SET (closure
, in_marshal
, TRUE
);
755 if (closure
->meta_marshal
)
757 marshal_data
= closure
->notifiers
[0].data
;
758 marshal
= (GClosureMarshal
) closure
->notifiers
[0].notify
;
763 marshal
= closure
->marshal
;
766 closure_invoke_notifiers (closure
, PRE_NOTIFY
);
769 n_param_values
, param_values
,
773 closure_invoke_notifiers (closure
, POST_NOTIFY
);
774 SET (closure
, in_marshal
, in_marshal
);
776 g_closure_unref (closure
);
780 * g_closure_set_marshal:
781 * @closure: a #GClosure
782 * @marshal: a #GClosureMarshal function
784 * Sets the marshaller of @closure. The <literal>marshal_data</literal>
785 * of @marshal provides a way for a meta marshaller to provide additional
786 * information to the marshaller. (See g_closure_set_meta_marshal().) For
787 * GObject's C predefined marshallers (the g_cclosure_marshal_*()
788 * functions), what it provides is a callback function to use instead of
789 * @closure->callback.
792 g_closure_set_marshal (GClosure
*closure
,
793 GClosureMarshal marshal
)
795 g_return_if_fail (closure
!= NULL
);
796 g_return_if_fail (marshal
!= NULL
);
798 if (closure
->marshal
&& closure
->marshal
!= marshal
)
799 g_warning ("attempt to override closure->marshal (%p) with new marshal (%p)",
800 closure
->marshal
, marshal
);
802 closure
->marshal
= marshal
;
807 * @callback_func: the function to invoke
808 * @user_data: user data to pass to @callback_func
809 * @destroy_data: destroy notify to be called when @user_data is no longer used
811 * Creates a new closure which invokes @callback_func with @user_data as
812 * the last parameter.
814 * Returns: a new #GCClosure
817 g_cclosure_new (GCallback callback_func
,
819 GClosureNotify destroy_data
)
823 g_return_val_if_fail (callback_func
!= NULL
, NULL
);
825 closure
= g_closure_new_simple (sizeof (GCClosure
), user_data
);
827 g_closure_add_finalize_notifier (closure
, user_data
, destroy_data
);
828 ((GCClosure
*) closure
)->callback
= (gpointer
) callback_func
;
834 * g_cclosure_new_swap:
835 * @callback_func: the function to invoke
836 * @user_data: user data to pass to @callback_func
837 * @destroy_data: destroy notify to be called when @user_data is no longer used
839 * Creates a new closure which invokes @callback_func with @user_data as
840 * the first parameter.
842 * Returns: a new #GCClosure
845 g_cclosure_new_swap (GCallback callback_func
,
847 GClosureNotify destroy_data
)
851 g_return_val_if_fail (callback_func
!= NULL
, NULL
);
853 closure
= g_closure_new_simple (sizeof (GCClosure
), user_data
);
855 g_closure_add_finalize_notifier (closure
, user_data
, destroy_data
);
856 ((GCClosure
*) closure
)->callback
= (gpointer
) callback_func
;
857 SET (closure
, derivative_flag
, TRUE
);
863 g_type_class_meta_marshal (GClosure
*closure
,
864 GValue
/*out*/ *return_value
,
865 guint n_param_values
,
866 const GValue
*param_values
,
867 gpointer invocation_hint
,
868 gpointer marshal_data
)
872 /* GType itype = (GType) closure->data; */
873 guint offset
= GPOINTER_TO_UINT (marshal_data
);
875 class = G_TYPE_INSTANCE_GET_CLASS (g_value_peek_pointer (param_values
+ 0), itype
, GTypeClass
);
876 callback
= G_STRUCT_MEMBER (gpointer
, class, offset
);
878 closure
->marshal (closure
,
880 n_param_values
, param_values
,
886 g_type_iface_meta_marshal (GClosure
*closure
,
887 GValue
/*out*/ *return_value
,
888 guint n_param_values
,
889 const GValue
*param_values
,
890 gpointer invocation_hint
,
891 gpointer marshal_data
)
895 GType itype
= (GType
) closure
->data
;
896 guint offset
= GPOINTER_TO_UINT (marshal_data
);
898 class = G_TYPE_INSTANCE_GET_INTERFACE (g_value_peek_pointer (param_values
+ 0), itype
, GTypeClass
);
899 callback
= G_STRUCT_MEMBER (gpointer
, class, offset
);
901 closure
->marshal (closure
,
903 n_param_values
, param_values
,
909 * g_signal_type_cclosure_new:
910 * @itype: the #GType identifier of an interface or classed type
911 * @struct_offset: the offset of the member function of @itype's class
912 * structure which is to be invoked by the new closure
914 * Creates a new closure which invokes the function found at the offset
915 * @struct_offset in the class structure of the interface or classed type
916 * identified by @itype.
918 * Returns: a new #GCClosure
921 g_signal_type_cclosure_new (GType itype
,
926 g_return_val_if_fail (G_TYPE_IS_CLASSED (itype
) || G_TYPE_IS_INTERFACE (itype
), NULL
);
927 g_return_val_if_fail (struct_offset
>= sizeof (GTypeClass
), NULL
);
929 closure
= g_closure_new_simple (sizeof (GClosure
), (gpointer
) itype
);
930 if (G_TYPE_IS_INTERFACE (itype
))
931 g_closure_set_meta_marshal (closure
, GUINT_TO_POINTER (struct_offset
), g_type_iface_meta_marshal
);
933 g_closure_set_meta_marshal (closure
, GUINT_TO_POINTER (struct_offset
), g_type_class_meta_marshal
);
940 * g_cclosure_marshal_VOID__VOID:
941 * @closure: the #GClosure to which the marshaller belongs
942 * @return_value: ignored
944 * @param_values: a #GValue array holding only the instance
945 * @invocation_hint: the invocation hint given as the last argument
946 * to g_closure_invoke()
947 * @marshal_data: additional data specified when registering the marshaller
949 * A marshaller for a #GCClosure with a callback of type
950 * <literal>void (*callback) (gpointer instance, gpointer user_data)</literal>.
954 * g_cclosure_marshal_VOID__BOOLEAN:
955 * @closure: the #GClosure to which the marshaller belongs
956 * @return_value: ignored
958 * @param_values: a #GValue array holding the instance and the #gboolean parameter
959 * @invocation_hint: the invocation hint given as the last argument
960 * to g_closure_invoke()
961 * @marshal_data: additional data specified when registering the marshaller
963 * A marshaller for a #GCClosure with a callback of type
964 * <literal>void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)</literal>.
968 * g_cclosure_marshal_VOID__CHAR:
969 * @closure: the #GClosure to which the marshaller belongs
970 * @return_value: ignored
972 * @param_values: a #GValue array holding the instance and the #gchar parameter
973 * @invocation_hint: the invocation hint given as the last argument
974 * to g_closure_invoke()
975 * @marshal_data: additional data specified when registering the marshaller
977 * A marshaller for a #GCClosure with a callback of type
978 * <literal>void (*callback) (gpointer instance, gchar arg1, gpointer user_data)</literal>.
982 * g_cclosure_marshal_VOID__UCHAR:
983 * @closure: the #GClosure to which the marshaller belongs
984 * @return_value: ignored
986 * @param_values: a #GValue array holding the instance and the #guchar parameter
987 * @invocation_hint: the invocation hint given as the last argument
988 * to g_closure_invoke()
989 * @marshal_data: additional data specified when registering the marshaller
991 * A marshaller for a #GCClosure with a callback of type
992 * <literal>void (*callback) (gpointer instance, guchar arg1, gpointer user_data)</literal>.
996 * g_cclosure_marshal_VOID__INT:
997 * @closure: the #GClosure to which the marshaller belongs
998 * @return_value: ignored
1000 * @param_values: a #GValue array holding the instance and the #gint parameter
1001 * @invocation_hint: the invocation hint given as the last argument
1002 * to g_closure_invoke()
1003 * @marshal_data: additional data specified when registering the marshaller
1005 * A marshaller for a #GCClosure with a callback of type
1006 * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal>.
1010 * g_cclosure_marshal_VOID__UINT:
1011 * @closure: the #GClosure to which the marshaller belongs
1012 * @return_value: ignored
1013 * @n_param_values: 2
1014 * @param_values: a #GValue array holding the instance and the #guint parameter
1015 * @invocation_hint: the invocation hint given as the last argument
1016 * to g_closure_invoke()
1017 * @marshal_data: additional data specified when registering the marshaller
1019 * A marshaller for a #GCClosure with a callback of type
1020 * <literal>void (*callback) (gpointer instance, guint arg1, gpointer user_data)</literal>.
1024 * g_cclosure_marshal_VOID__LONG:
1025 * @closure: the #GClosure to which the marshaller belongs
1026 * @return_value: ignored
1027 * @n_param_values: 2
1028 * @param_values: a #GValue array holding the instance and the #glong parameter
1029 * @invocation_hint: the invocation hint given as the last argument
1030 * to g_closure_invoke()
1031 * @marshal_data: additional data specified when registering the marshaller
1033 * A marshaller for a #GCClosure with a callback of type
1034 * <literal>void (*callback) (gpointer instance, glong arg1, gpointer user_data)</literal>.
1038 * g_cclosure_marshal_VOID__ULONG:
1039 * @closure: the #GClosure to which the marshaller belongs
1040 * @return_value: ignored
1041 * @n_param_values: 2
1042 * @param_values: a #GValue array holding the instance and the #gulong parameter
1043 * @invocation_hint: the invocation hint given as the last argument
1044 * to g_closure_invoke()
1045 * @marshal_data: additional data specified when registering the marshaller
1047 * A marshaller for a #GCClosure with a callback of type
1048 * <literal>void (*callback) (gpointer instance, gulong arg1, gpointer user_data)</literal>.
1052 * g_cclosure_marshal_VOID__ENUM:
1053 * @closure: the #GClosure to which the marshaller belongs
1054 * @return_value: ignored
1055 * @n_param_values: 2
1056 * @param_values: a #GValue array holding the instance and the enumeration parameter
1057 * @invocation_hint: the invocation hint given as the last argument
1058 * to g_closure_invoke()
1059 * @marshal_data: additional data specified when registering the marshaller
1061 * A marshaller for a #GCClosure with a callback of type
1062 * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes an enumeration type..
1066 * g_cclosure_marshal_VOID__FLAGS:
1067 * @closure: the #GClosure to which the marshaller belongs
1068 * @return_value: ignored
1069 * @n_param_values: 2
1070 * @param_values: a #GValue array holding the instance and the flags parameter
1071 * @invocation_hint: the invocation hint given as the last argument
1072 * to g_closure_invoke()
1073 * @marshal_data: additional data specified when registering the marshaller
1075 * A marshaller for a #GCClosure with a callback of type
1076 * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes a flags type.
1080 * g_cclosure_marshal_VOID__FLOAT:
1081 * @closure: the #GClosure to which the marshaller belongs
1082 * @return_value: ignored
1083 * @n_param_values: 2
1084 * @param_values: a #GValue array holding the instance and the #gfloat parameter
1085 * @invocation_hint: the invocation hint given as the last argument
1086 * to g_closure_invoke()
1087 * @marshal_data: additional data specified when registering the marshaller
1089 * A marshaller for a #GCClosure with a callback of type
1090 * <literal>void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)</literal>.
1094 * g_cclosure_marshal_VOID__DOUBLE:
1095 * @closure: the #GClosure to which the marshaller belongs
1096 * @return_value: ignored
1097 * @n_param_values: 2
1098 * @param_values: a #GValue array holding the instance and the #gdouble parameter
1099 * @invocation_hint: the invocation hint given as the last argument
1100 * to g_closure_invoke()
1101 * @marshal_data: additional data specified when registering the marshaller
1103 * A marshaller for a #GCClosure with a callback of type
1104 * <literal>void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)</literal>.
1108 * g_cclosure_marshal_VOID__STRING:
1109 * @closure: the #GClosure to which the marshaller belongs
1110 * @return_value: ignored
1111 * @n_param_values: 2
1112 * @param_values: a #GValue array holding the instance and the #gchar* parameter
1113 * @invocation_hint: the invocation hint given as the last argument
1114 * to g_closure_invoke()
1115 * @marshal_data: additional data specified when registering the marshaller
1117 * A marshaller for a #GCClosure with a callback of type
1118 * <literal>void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)</literal>.
1122 * g_cclosure_marshal_VOID__PARAM:
1123 * @closure: the #GClosure to which the marshaller belongs
1124 * @return_value: ignored
1125 * @n_param_values: 2
1126 * @param_values: a #GValue array holding the instance and the #GParamSpec* parameter
1127 * @invocation_hint: the invocation hint given as the last argument
1128 * to g_closure_invoke()
1129 * @marshal_data: additional data specified when registering the marshaller
1131 * A marshaller for a #GCClosure with a callback of type
1132 * <literal>void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)</literal>.
1136 * g_cclosure_marshal_VOID__BOXED:
1137 * @closure: the #GClosure to which the marshaller belongs
1138 * @return_value: ignored
1139 * @n_param_values: 2
1140 * @param_values: a #GValue array holding the instance and the #GBoxed* parameter
1141 * @invocation_hint: the invocation hint given as the last argument
1142 * to g_closure_invoke()
1143 * @marshal_data: additional data specified when registering the marshaller
1145 * A marshaller for a #GCClosure with a callback of type
1146 * <literal>void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)</literal>.
1150 * g_cclosure_marshal_VOID__POINTER:
1151 * @closure: the #GClosure to which the marshaller belongs
1152 * @return_value: ignored
1153 * @n_param_values: 2
1154 * @param_values: a #GValue array holding the instance and the #gpointer parameter
1155 * @invocation_hint: the invocation hint given as the last argument
1156 * to g_closure_invoke()
1157 * @marshal_data: additional data specified when registering the marshaller
1159 * A marshaller for a #GCClosure with a callback of type
1160 * <literal>void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)</literal>.
1164 * g_cclosure_marshal_VOID__OBJECT:
1165 * @closure: the #GClosure to which the marshaller belongs
1166 * @return_value: ignored
1167 * @n_param_values: 2
1168 * @param_values: a #GValue array holding the instance and the #GObject* parameter
1169 * @invocation_hint: the invocation hint given as the last argument
1170 * to g_closure_invoke()
1171 * @marshal_data: additional data specified when registering the marshaller
1173 * A marshaller for a #GCClosure with a callback of type
1174 * <literal>void (*callback) (gpointer instance, GOBject *arg1, gpointer user_data)</literal>.
1178 * g_cclosure_marshal_VOID__UINT_POINTER:
1179 * @closure: the #GClosure to which the marshaller belongs
1180 * @return_value: ignored
1181 * @n_param_values: 3
1182 * @param_values: a #GValue array holding instance, arg1 and arg2
1183 * @invocation_hint: the invocation hint given as the last argument
1184 * to g_closure_invoke()
1185 * @marshal_data: additional data specified when registering the marshaller
1187 * A marshaller for a #GCClosure with a callback of type
1188 * <literal>void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)</literal>.
1192 * g_cclosure_marshal_BOOLEAN__FLAGS:
1193 * @closure: the #GClosure to which the marshaller belongs
1194 * @return_value: a #GValue which can store the returned #gboolean
1195 * @n_param_values: 2
1196 * @param_values: a #GValue array holding instance and arg1
1197 * @invocation_hint: the invocation hint given as the last argument
1198 * to g_closure_invoke()
1199 * @marshal_data: additional data specified when registering the marshaller
1201 * A marshaller for a #GCClosure with a callback of type
1202 * <literal>gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter
1203 * denotes a flags type.
1207 * g_cclosure_marshal_BOOL__FLAGS:
1209 * Another name for g_cclosure_marshal_BOOLEAN__FLAGS().
1212 * g_cclosure_marshal_STRING__OBJECT_POINTER:
1213 * @closure: the #GClosure to which the marshaller belongs
1214 * @return_value: a #GValue, which can store the returned string
1215 * @n_param_values: 3
1216 * @param_values: a #GValue array holding instance, arg1 and arg2
1217 * @invocation_hint: the invocation hint given as the last argument
1218 * to g_closure_invoke()
1219 * @marshal_data: additional data specified when registering the marshaller
1221 * A marshaller for a #GCClosure with a callback of type
1222 * <literal>gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)</literal>.
1225 #define __G_CLOSURE_C__
1226 #include "gobjectaliasdef.c"