/
gclosure.c
1956 lines (1779 loc) · 63.9 KB
/
gclosure.c
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/* GObject - GLib Type, Object, Parameter and Signal Library
* Copyright (C) 2000-2001 Red Hat, Inc.
* Copyright (C) 2005 Imendio AB
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General
* Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
*/
/*
* MT safe with regards to reference counting.
*/
#include "config.h"
#include "../glib/gvalgrind.h"
#include <string.h>
#include <ffi.h>
#include "gclosure.h"
#include "gboxed.h"
#include "gobject.h"
#include "genums.h"
#include "gvalue.h"
#include "gvaluetypes.h"
#include "gtype-private.h"
/**
* SECTION:gclosure
* @short_description: Functions as first-class objects
* @title: Closures
*
* A #GClosure represents a callback supplied by the programmer. It
* will generally comprise a function of some kind and a marshaller
* used to call it. It is the responsibility of the marshaller to
* convert the arguments for the invocation from #GValues into
* a suitable form, perform the callback on the converted arguments,
* and transform the return value back into a #GValue.
*
* In the case of C programs, a closure usually just holds a pointer
* to a function and maybe a data argument, and the marshaller
* converts between #GValue and native C types. The GObject
* library provides the #GCClosure type for this purpose. Bindings for
* other languages need marshallers which convert between #GValues
* and suitable representations in the runtime of the language in
* order to use functions written in that language as callbacks. Use
* g_closure_set_marshal() to set the marshaller on such a custom
* closure implementation.
*
* Within GObject, closures play an important role in the
* implementation of signals. When a signal is registered, the
* @c_marshaller argument to g_signal_new() specifies the default C
* marshaller for any closure which is connected to this
* signal. GObject provides a number of C marshallers for this
* purpose, see the g_cclosure_marshal_*() functions. Additional C
* marshallers can be generated with the [glib-genmarshal][glib-genmarshal]
* utility. Closures can be explicitly connected to signals with
* g_signal_connect_closure(), but it usually more convenient to let
* GObject create a closure automatically by using one of the
* g_signal_connect_*() functions which take a callback function/user
* data pair.
*
* Using closures has a number of important advantages over a simple
* callback function/data pointer combination:
*
* - Closures allow the callee to get the types of the callback parameters,
* which means that language bindings don't have to write individual glue
* for each callback type.
*
* - The reference counting of #GClosure makes it easy to handle reentrancy
* right; if a callback is removed while it is being invoked, the closure
* and its parameters won't be freed until the invocation finishes.
*
* - g_closure_invalidate() and invalidation notifiers allow callbacks to be
* automatically removed when the objects they point to go away.
*/
#define CLOSURE_MAX_REF_COUNT ((1 << 15) - 1)
#define CLOSURE_MAX_N_GUARDS ((1 << 1) - 1)
#define CLOSURE_MAX_N_FNOTIFIERS ((1 << 2) - 1)
#define CLOSURE_MAX_N_INOTIFIERS ((1 << 8) - 1)
#define CLOSURE_N_MFUNCS(cl) (((cl)->n_guards << 1L))
/* same as G_CLOSURE_N_NOTIFIERS() (keep in sync) */
#define CLOSURE_N_NOTIFIERS(cl) (CLOSURE_N_MFUNCS (cl) + \
(cl)->n_fnotifiers + \
(cl)->n_inotifiers)
typedef union {
GClosure closure;
volatile gint vint;
} ClosureInt;
#define CHANGE_FIELD(_closure, _field, _OP, _value, _must_set, _SET_OLD, _SET_NEW) \
G_STMT_START { \
ClosureInt *cunion = (ClosureInt*) _closure; \
gint new_int, old_int, success; \
do \
{ \
ClosureInt tmp; \
tmp.vint = old_int = cunion->vint; \
_SET_OLD tmp.closure._field; \
tmp.closure._field _OP _value; \
_SET_NEW tmp.closure._field; \
new_int = tmp.vint; \
success = g_atomic_int_compare_and_exchange (&cunion->vint, old_int, new_int); \
} \
while (!success && _must_set); \
} G_STMT_END
#define SWAP(_closure, _field, _value, _oldv) CHANGE_FIELD (_closure, _field, =, _value, TRUE, *(_oldv) =, (void) )
#define SET(_closure, _field, _value) CHANGE_FIELD (_closure, _field, =, _value, TRUE, (void), (void) )
#define INC(_closure, _field) CHANGE_FIELD (_closure, _field, +=, 1, TRUE, (void), (void) )
#define INC_ASSIGN(_closure, _field, _newv) CHANGE_FIELD (_closure, _field, +=, 1, TRUE, (void), *(_newv) = )
#define DEC(_closure, _field) CHANGE_FIELD (_closure, _field, -=, 1, TRUE, (void), (void) )
#define DEC_ASSIGN(_closure, _field, _newv) CHANGE_FIELD (_closure, _field, -=, 1, TRUE, (void), *(_newv) = )
#if 0 /* for non-thread-safe closures */
#define SWAP(cl,f,v,o) (void) (*(o) = cl->f, cl->f = v)
#define SET(cl,f,v) (void) (cl->f = v)
#define INC(cl,f) (void) (cl->f += 1)
#define INC_ASSIGN(cl,f,n) (void) (cl->f += 1, *(n) = cl->f)
#define DEC(cl,f) (void) (cl->f -= 1)
#define DEC_ASSIGN(cl,f,n) (void) (cl->f -= 1, *(n) = cl->f)
#endif
enum {
FNOTIFY,
INOTIFY,
PRE_NOTIFY,
POST_NOTIFY
};
/* --- functions --- */
/**
* g_closure_new_simple:
* @sizeof_closure: the size of the structure to allocate, must be at least
* `sizeof (GClosure)`
* @data: data to store in the @data field of the newly allocated #GClosure
*
* Allocates a struct of the given size and initializes the initial
* part as a #GClosure. This function is mainly useful when
* implementing new types of closures.
*
* |[<!-- language="C" -->
* typedef struct _MyClosure MyClosure;
* struct _MyClosure
* {
* GClosure closure;
* // extra data goes here
* };
*
* static void
* my_closure_finalize (gpointer notify_data,
* GClosure *closure)
* {
* MyClosure *my_closure = (MyClosure *)closure;
*
* // free extra data here
* }
*
* MyClosure *my_closure_new (gpointer data)
* {
* GClosure *closure;
* MyClosure *my_closure;
*
* closure = g_closure_new_simple (sizeof (MyClosure), data);
* my_closure = (MyClosure *) closure;
*
* // initialize extra data here
*
* g_closure_add_finalize_notifier (closure, notify_data,
* my_closure_finalize);
* return my_closure;
* }
* ]|
*
* Returns: (transfer none): a floating reference to a new #GClosure
*/
GClosure*
g_closure_new_simple (guint sizeof_closure,
gpointer data)
{
GClosure *closure;
gint private_size;
gchar *allocated;
g_return_val_if_fail (sizeof_closure >= sizeof (GClosure), NULL);
private_size = sizeof (GRealClosure) - sizeof (GClosure);
#ifdef ENABLE_VALGRIND
/* See comments in gtype.c about what's going on here... */
if (RUNNING_ON_VALGRIND)
{
private_size += sizeof (gpointer);
allocated = g_malloc0 (private_size + sizeof_closure + sizeof (gpointer));
*(gpointer *) (allocated + private_size + sizeof_closure) = allocated + sizeof (gpointer);
VALGRIND_MALLOCLIKE_BLOCK (allocated + private_size, sizeof_closure + sizeof (gpointer), 0, TRUE);
VALGRIND_MALLOCLIKE_BLOCK (allocated + sizeof (gpointer), private_size - sizeof (gpointer), 0, TRUE);
}
else
#endif
allocated = g_malloc0 (private_size + sizeof_closure);
closure = (GClosure *) (allocated + private_size);
SET (closure, ref_count, 1);
SET (closure, floating, TRUE);
closure->data = data;
return closure;
}
static inline void
closure_invoke_notifiers (GClosure *closure,
guint notify_type)
{
/* notifier layout:
* n_guards n_guards n_fnotif. n_inotifiers
* ->[[pre_guards][post_guards][fnotifiers][inotifiers]]
*
* CLOSURE_N_MFUNCS(cl) = n_guards + n_guards;
* CLOSURE_N_NOTIFIERS(cl) = CLOSURE_N_MFUNCS(cl) + n_fnotifiers + n_inotifiers
*
* constrains/catches:
* - closure->notifiers may be reloacted during callback
* - closure->n_fnotifiers and closure->n_inotifiers may change during callback
* - i.e. callbacks can be removed/added during invocation
* - must prepare for callback removal during FNOTIFY and INOTIFY (done via ->marshal= & ->data=)
* - must distinguish (->marshal= & ->data=) for INOTIFY vs. FNOTIFY (via ->in_inotify)
* + closure->n_guards is const during PRE_NOTIFY & POST_NOTIFY
* + none of the callbacks can cause recursion
* + closure->n_inotifiers is const 0 during FNOTIFY
*/
switch (notify_type)
{
GClosureNotifyData *ndata;
guint i, offs;
case FNOTIFY:
while (closure->n_fnotifiers)
{
guint n;
DEC_ASSIGN (closure, n_fnotifiers, &n);
ndata = closure->notifiers + CLOSURE_N_MFUNCS (closure) + n;
closure->marshal = (GClosureMarshal) ndata->notify;
closure->data = ndata->data;
ndata->notify (ndata->data, closure);
}
closure->marshal = NULL;
closure->data = NULL;
break;
case INOTIFY:
SET (closure, in_inotify, TRUE);
while (closure->n_inotifiers)
{
guint n;
DEC_ASSIGN (closure, n_inotifiers, &n);
ndata = closure->notifiers + CLOSURE_N_MFUNCS (closure) + closure->n_fnotifiers + n;
closure->marshal = (GClosureMarshal) ndata->notify;
closure->data = ndata->data;
ndata->notify (ndata->data, closure);
}
closure->marshal = NULL;
closure->data = NULL;
SET (closure, in_inotify, FALSE);
break;
case PRE_NOTIFY:
i = closure->n_guards;
offs = 0;
while (i--)
{
ndata = closure->notifiers + offs + i;
ndata->notify (ndata->data, closure);
}
break;
case POST_NOTIFY:
i = closure->n_guards;
offs = i;
while (i--)
{
ndata = closure->notifiers + offs + i;
ndata->notify (ndata->data, closure);
}
break;
}
}
static void
g_closure_set_meta_va_marshal (GClosure *closure,
GVaClosureMarshal va_meta_marshal)
{
GRealClosure *real_closure;
g_return_if_fail (closure != NULL);
g_return_if_fail (va_meta_marshal != NULL);
g_return_if_fail (closure->is_invalid == FALSE);
g_return_if_fail (closure->in_marshal == FALSE);
real_closure = G_REAL_CLOSURE (closure);
g_return_if_fail (real_closure->meta_marshal != NULL);
real_closure->va_meta_marshal = va_meta_marshal;
}
/**
* g_closure_set_meta_marshal: (skip)
* @closure: a #GClosure
* @marshal_data: (closure meta_marshal): context-dependent data to pass
* to @meta_marshal
* @meta_marshal: a #GClosureMarshal function
*
* Sets the meta marshaller of @closure. A meta marshaller wraps
* @closure->marshal and modifies the way it is called in some
* fashion. The most common use of this facility is for C callbacks.
* The same marshallers (generated by [glib-genmarshal][glib-genmarshal]),
* are used everywhere, but the way that we get the callback function
* differs. In most cases we want to use @closure->callback, but in
* other cases we want to use some different technique to retrieve the
* callback function.
*
* For example, class closures for signals (see
* g_signal_type_cclosure_new()) retrieve the callback function from a
* fixed offset in the class structure. The meta marshaller retrieves
* the right callback and passes it to the marshaller as the
* @marshal_data argument.
*/
void
g_closure_set_meta_marshal (GClosure *closure,
gpointer marshal_data,
GClosureMarshal meta_marshal)
{
GRealClosure *real_closure;
g_return_if_fail (closure != NULL);
g_return_if_fail (meta_marshal != NULL);
g_return_if_fail (closure->is_invalid == FALSE);
g_return_if_fail (closure->in_marshal == FALSE);
real_closure = G_REAL_CLOSURE (closure);
g_return_if_fail (real_closure->meta_marshal == NULL);
real_closure->meta_marshal = meta_marshal;
real_closure->meta_marshal_data = marshal_data;
}
/**
* g_closure_add_marshal_guards: (skip)
* @closure: a #GClosure
* @pre_marshal_data: (closure pre_marshal_notify): data to pass
* to @pre_marshal_notify
* @pre_marshal_notify: a function to call before the closure callback
* @post_marshal_data: (closure post_marshal_notify): data to pass
* to @post_marshal_notify
* @post_marshal_notify: a function to call after the closure callback
*
* Adds a pair of notifiers which get invoked before and after the
* closure callback, respectively. This is typically used to protect
* the extra arguments for the duration of the callback. See
* g_object_watch_closure() for an example of marshal guards.
*/
void
g_closure_add_marshal_guards (GClosure *closure,
gpointer pre_marshal_data,
GClosureNotify pre_marshal_notify,
gpointer post_marshal_data,
GClosureNotify post_marshal_notify)
{
guint i;
g_return_if_fail (closure != NULL);
g_return_if_fail (pre_marshal_notify != NULL);
g_return_if_fail (post_marshal_notify != NULL);
g_return_if_fail (closure->is_invalid == FALSE);
g_return_if_fail (closure->in_marshal == FALSE);
g_return_if_fail (closure->n_guards < CLOSURE_MAX_N_GUARDS);
closure->notifiers = g_renew (GClosureNotifyData, closure->notifiers, CLOSURE_N_NOTIFIERS (closure) + 2);
if (closure->n_inotifiers)
closure->notifiers[(CLOSURE_N_MFUNCS (closure) +
closure->n_fnotifiers +
closure->n_inotifiers + 1)] = closure->notifiers[(CLOSURE_N_MFUNCS (closure) +
closure->n_fnotifiers + 0)];
if (closure->n_inotifiers > 1)
closure->notifiers[(CLOSURE_N_MFUNCS (closure) +
closure->n_fnotifiers +
closure->n_inotifiers)] = closure->notifiers[(CLOSURE_N_MFUNCS (closure) +
closure->n_fnotifiers + 1)];
if (closure->n_fnotifiers)
closure->notifiers[(CLOSURE_N_MFUNCS (closure) +
closure->n_fnotifiers + 1)] = closure->notifiers[CLOSURE_N_MFUNCS (closure) + 0];
if (closure->n_fnotifiers > 1)
closure->notifiers[(CLOSURE_N_MFUNCS (closure) +
closure->n_fnotifiers)] = closure->notifiers[CLOSURE_N_MFUNCS (closure) + 1];
if (closure->n_guards)
closure->notifiers[(closure->n_guards +
closure->n_guards + 1)] = closure->notifiers[closure->n_guards];
i = closure->n_guards;
closure->notifiers[i].data = pre_marshal_data;
closure->notifiers[i].notify = pre_marshal_notify;
closure->notifiers[i + 1].data = post_marshal_data;
closure->notifiers[i + 1].notify = post_marshal_notify;
INC (closure, n_guards);
}
/**
* g_closure_add_finalize_notifier: (skip)
* @closure: a #GClosure
* @notify_data: (closure notify_func): data to pass to @notify_func
* @notify_func: the callback function to register
*
* Registers a finalization notifier which will be called when the
* reference count of @closure goes down to 0. Multiple finalization
* notifiers on a single closure are invoked in unspecified order. If
* a single call to g_closure_unref() results in the closure being
* both invalidated and finalized, then the invalidate notifiers will
* be run before the finalize notifiers.
*/
void
g_closure_add_finalize_notifier (GClosure *closure,
gpointer notify_data,
GClosureNotify notify_func)
{
guint i;
g_return_if_fail (closure != NULL);
g_return_if_fail (notify_func != NULL);
g_return_if_fail (closure->n_fnotifiers < CLOSURE_MAX_N_FNOTIFIERS);
closure->notifiers = g_renew (GClosureNotifyData, closure->notifiers, CLOSURE_N_NOTIFIERS (closure) + 1);
if (closure->n_inotifiers)
closure->notifiers[(CLOSURE_N_MFUNCS (closure) +
closure->n_fnotifiers +
closure->n_inotifiers)] = closure->notifiers[(CLOSURE_N_MFUNCS (closure) +
closure->n_fnotifiers + 0)];
i = CLOSURE_N_MFUNCS (closure) + closure->n_fnotifiers;
closure->notifiers[i].data = notify_data;
closure->notifiers[i].notify = notify_func;
INC (closure, n_fnotifiers);
}
/**
* g_closure_add_invalidate_notifier: (skip)
* @closure: a #GClosure
* @notify_data: (closure notify_func): data to pass to @notify_func
* @notify_func: the callback function to register
*
* Registers an invalidation notifier which will be called when the
* @closure is invalidated with g_closure_invalidate(). Invalidation
* notifiers are invoked before finalization notifiers, in an
* unspecified order.
*/
void
g_closure_add_invalidate_notifier (GClosure *closure,
gpointer notify_data,
GClosureNotify notify_func)
{
guint i;
g_return_if_fail (closure != NULL);
g_return_if_fail (notify_func != NULL);
g_return_if_fail (closure->is_invalid == FALSE);
g_return_if_fail (closure->n_inotifiers < CLOSURE_MAX_N_INOTIFIERS);
closure->notifiers = g_renew (GClosureNotifyData, closure->notifiers, CLOSURE_N_NOTIFIERS (closure) + 1);
i = CLOSURE_N_MFUNCS (closure) + closure->n_fnotifiers + closure->n_inotifiers;
closure->notifiers[i].data = notify_data;
closure->notifiers[i].notify = notify_func;
INC (closure, n_inotifiers);
}
static inline gboolean
closure_try_remove_inotify (GClosure *closure,
gpointer notify_data,
GClosureNotify notify_func)
{
GClosureNotifyData *ndata, *nlast;
nlast = closure->notifiers + CLOSURE_N_NOTIFIERS (closure) - 1;
for (ndata = nlast + 1 - closure->n_inotifiers; ndata <= nlast; ndata++)
if (ndata->notify == notify_func && ndata->data == notify_data)
{
DEC (closure, n_inotifiers);
if (ndata < nlast)
*ndata = *nlast;
return TRUE;
}
return FALSE;
}
static inline gboolean
closure_try_remove_fnotify (GClosure *closure,
gpointer notify_data,
GClosureNotify notify_func)
{
GClosureNotifyData *ndata, *nlast;
nlast = closure->notifiers + CLOSURE_N_NOTIFIERS (closure) - closure->n_inotifiers - 1;
for (ndata = nlast + 1 - closure->n_fnotifiers; ndata <= nlast; ndata++)
if (ndata->notify == notify_func && ndata->data == notify_data)
{
DEC (closure, n_fnotifiers);
if (ndata < nlast)
*ndata = *nlast;
if (closure->n_inotifiers)
closure->notifiers[(CLOSURE_N_MFUNCS (closure) +
closure->n_fnotifiers)] = closure->notifiers[(CLOSURE_N_MFUNCS (closure) +
closure->n_fnotifiers +
closure->n_inotifiers)];
return TRUE;
}
return FALSE;
}
/**
* g_closure_ref:
* @closure: #GClosure to increment the reference count on
*
* Increments the reference count on a closure to force it staying
* alive while the caller holds a pointer to it.
*
* Returns: (transfer none): The @closure passed in, for convenience
*/
GClosure*
g_closure_ref (GClosure *closure)
{
guint new_ref_count;
g_return_val_if_fail (closure != NULL, NULL);
g_return_val_if_fail (closure->ref_count > 0, NULL);
g_return_val_if_fail (closure->ref_count < CLOSURE_MAX_REF_COUNT, NULL);
INC_ASSIGN (closure, ref_count, &new_ref_count);
g_return_val_if_fail (new_ref_count > 1, NULL);
return closure;
}
/**
* g_closure_invalidate:
* @closure: #GClosure to invalidate
*
* Sets a flag on the closure to indicate that its calling
* environment has become invalid, and thus causes any future
* invocations of g_closure_invoke() on this @closure to be
* ignored. Also, invalidation notifiers installed on the closure will
* be called at this point. Note that unless you are holding a
* reference to the closure yourself, the invalidation notifiers may
* unref the closure and cause it to be destroyed, so if you need to
* access the closure after calling g_closure_invalidate(), make sure
* that you've previously called g_closure_ref().
*
* Note that g_closure_invalidate() will also be called when the
* reference count of a closure drops to zero (unless it has already
* been invalidated before).
*/
void
g_closure_invalidate (GClosure *closure)
{
g_return_if_fail (closure != NULL);
if (!closure->is_invalid)
{
gboolean was_invalid;
g_closure_ref (closure); /* preserve floating flag */
SWAP (closure, is_invalid, TRUE, &was_invalid);
/* invalidate only once */
if (!was_invalid)
closure_invoke_notifiers (closure, INOTIFY);
g_closure_unref (closure);
}
}
/**
* g_closure_unref:
* @closure: #GClosure to decrement the reference count on
*
* Decrements the reference count of a closure after it was previously
* incremented by the same caller. If no other callers are using the
* closure, then the closure will be destroyed and freed.
*/
void
g_closure_unref (GClosure *closure)
{
guint new_ref_count;
g_return_if_fail (closure != NULL);
g_return_if_fail (closure->ref_count > 0);
if (closure->ref_count == 1) /* last unref, invalidate first */
g_closure_invalidate (closure);
DEC_ASSIGN (closure, ref_count, &new_ref_count);
if (new_ref_count == 0)
{
closure_invoke_notifiers (closure, FNOTIFY);
g_free (closure->notifiers);
#ifdef ENABLE_VALGRIND
/* See comments in gtype.c about what's going on here... */
if (RUNNING_ON_VALGRIND)
{
gchar *allocated;
allocated = (gchar *) G_REAL_CLOSURE (closure);
allocated -= sizeof (gpointer);
g_free (allocated);
VALGRIND_FREELIKE_BLOCK (allocated + sizeof (gpointer), 0);
VALGRIND_FREELIKE_BLOCK (closure, 0);
}
else
#endif
g_free (G_REAL_CLOSURE (closure));
}
}
/**
* g_closure_sink:
* @closure: #GClosure to decrement the initial reference count on, if it's
* still being held
*
* Takes over the initial ownership of a closure. Each closure is
* initially created in a "floating" state, which means that the initial
* reference count is not owned by any caller. g_closure_sink() checks
* to see if the object is still floating, and if so, unsets the
* floating state and decreases the reference count. If the closure
* is not floating, g_closure_sink() does nothing. The reason for the
* existence of the floating state is to prevent cumbersome code
* sequences like:
* |[<!-- language="C" -->
* closure = g_cclosure_new (cb_func, cb_data);
* g_source_set_closure (source, closure);
* g_closure_unref (closure); // GObject doesn't really need this
* ]|
* Because g_source_set_closure() (and similar functions) take ownership of the
* initial reference count, if it is unowned, we instead can write:
* |[<!-- language="C" -->
* g_source_set_closure (source, g_cclosure_new (cb_func, cb_data));
* ]|
*
* Generally, this function is used together with g_closure_ref(). Ane example
* of storing a closure for later notification looks like:
* |[<!-- language="C" -->
* static GClosure *notify_closure = NULL;
* void
* foo_notify_set_closure (GClosure *closure)
* {
* if (notify_closure)
* g_closure_unref (notify_closure);
* notify_closure = closure;
* if (notify_closure)
* {
* g_closure_ref (notify_closure);
* g_closure_sink (notify_closure);
* }
* }
* ]|
*
* Because g_closure_sink() may decrement the reference count of a closure
* (if it hasn't been called on @closure yet) just like g_closure_unref(),
* g_closure_ref() should be called prior to this function.
*/
void
g_closure_sink (GClosure *closure)
{
g_return_if_fail (closure != NULL);
g_return_if_fail (closure->ref_count > 0);
/* floating is basically a kludge to avoid creating closures
* with a ref_count of 0. so the initial ref_count a closure has
* is unowned. with invoking g_closure_sink() code may
* indicate that it takes over that intiial ref_count.
*/
if (closure->floating)
{
gboolean was_floating;
SWAP (closure, floating, FALSE, &was_floating);
/* unref floating flag only once */
if (was_floating)
g_closure_unref (closure);
}
}
/**
* g_closure_remove_invalidate_notifier: (skip)
* @closure: a #GClosure
* @notify_data: data which was passed to g_closure_add_invalidate_notifier()
* when registering @notify_func
* @notify_func: the callback function to remove
*
* Removes an invalidation notifier.
*
* Notice that notifiers are automatically removed after they are run.
*/
void
g_closure_remove_invalidate_notifier (GClosure *closure,
gpointer notify_data,
GClosureNotify notify_func)
{
g_return_if_fail (closure != NULL);
g_return_if_fail (notify_func != NULL);
if (closure->is_invalid && closure->in_inotify && /* account removal of notify_func() while it's called */
((gpointer) closure->marshal) == ((gpointer) notify_func) &&
closure->data == notify_data)
closure->marshal = NULL;
else if (!closure_try_remove_inotify (closure, notify_data, notify_func))
g_warning (G_STRLOC ": unable to remove uninstalled invalidation notifier: %p (%p)",
notify_func, notify_data);
}
/**
* g_closure_remove_finalize_notifier: (skip)
* @closure: a #GClosure
* @notify_data: data which was passed to g_closure_add_finalize_notifier()
* when registering @notify_func
* @notify_func: the callback function to remove
*
* Removes a finalization notifier.
*
* Notice that notifiers are automatically removed after they are run.
*/
void
g_closure_remove_finalize_notifier (GClosure *closure,
gpointer notify_data,
GClosureNotify notify_func)
{
g_return_if_fail (closure != NULL);
g_return_if_fail (notify_func != NULL);
if (closure->is_invalid && !closure->in_inotify && /* account removal of notify_func() while it's called */
((gpointer) closure->marshal) == ((gpointer) notify_func) &&
closure->data == notify_data)
closure->marshal = NULL;
else if (!closure_try_remove_fnotify (closure, notify_data, notify_func))
g_warning (G_STRLOC ": unable to remove uninstalled finalization notifier: %p (%p)",
notify_func, notify_data);
}
/**
* g_closure_invoke:
* @closure: a #GClosure
* @return_value: (optional) (out): a #GValue to store the return
* value. May be %NULL if the callback of @closure
* doesn't return a value.
* @n_param_values: the length of the @param_values array
* @param_values: (array length=n_param_values): an array of
* #GValues holding the arguments on which to
* invoke the callback of @closure
* @invocation_hint: (nullable): a context-dependent invocation hint
*
* Invokes the closure, i.e. executes the callback represented by the @closure.
*/
void
g_closure_invoke (GClosure *closure,
GValue /*out*/ *return_value,
guint n_param_values,
const GValue *param_values,
gpointer invocation_hint)
{
GRealClosure *real_closure;
g_return_if_fail (closure != NULL);
real_closure = G_REAL_CLOSURE (closure);
g_closure_ref (closure); /* preserve floating flag */
if (!closure->is_invalid)
{
GClosureMarshal marshal;
gpointer marshal_data;
gboolean in_marshal = closure->in_marshal;
g_return_if_fail (closure->marshal || real_closure->meta_marshal);
SET (closure, in_marshal, TRUE);
if (real_closure->meta_marshal)
{
marshal_data = real_closure->meta_marshal_data;
marshal = real_closure->meta_marshal;
}
else
{
marshal_data = NULL;
marshal = closure->marshal;
}
if (!in_marshal)
closure_invoke_notifiers (closure, PRE_NOTIFY);
marshal (closure,
return_value,
n_param_values, param_values,
invocation_hint,
marshal_data);
if (!in_marshal)
closure_invoke_notifiers (closure, POST_NOTIFY);
SET (closure, in_marshal, in_marshal);
}
g_closure_unref (closure);
}
gboolean
_g_closure_supports_invoke_va (GClosure *closure)
{
GRealClosure *real_closure;
g_return_val_if_fail (closure != NULL, FALSE);
real_closure = G_REAL_CLOSURE (closure);
return
real_closure->va_marshal != NULL &&
(real_closure->meta_marshal == NULL ||
real_closure->va_meta_marshal != NULL);
}
void
_g_closure_invoke_va (GClosure *closure,
GValue /*out*/ *return_value,
gpointer instance,
va_list args,
int n_params,
GType *param_types)
{
GRealClosure *real_closure;
g_return_if_fail (closure != NULL);
real_closure = G_REAL_CLOSURE (closure);
g_closure_ref (closure); /* preserve floating flag */
if (!closure->is_invalid)
{
GVaClosureMarshal marshal;
gpointer marshal_data;
gboolean in_marshal = closure->in_marshal;
g_return_if_fail (closure->marshal || real_closure->meta_marshal);
SET (closure, in_marshal, TRUE);
if (real_closure->va_meta_marshal)
{
marshal_data = real_closure->meta_marshal_data;
marshal = real_closure->va_meta_marshal;
}
else
{
marshal_data = NULL;
marshal = real_closure->va_marshal;
}
if (!in_marshal)
closure_invoke_notifiers (closure, PRE_NOTIFY);
marshal (closure,
return_value,
instance, args,
marshal_data,
n_params, param_types);
if (!in_marshal)
closure_invoke_notifiers (closure, POST_NOTIFY);
SET (closure, in_marshal, in_marshal);
}
g_closure_unref (closure);
}
/**
* g_closure_set_marshal: (skip)
* @closure: a #GClosure
* @marshal: a #GClosureMarshal function
*
* Sets the marshaller of @closure. The `marshal_data`
* of @marshal provides a way for a meta marshaller to provide additional
* information to the marshaller. (See g_closure_set_meta_marshal().) For
* GObject's C predefined marshallers (the g_cclosure_marshal_*()
* functions), what it provides is a callback function to use instead of
* @closure->callback.
*/
void
g_closure_set_marshal (GClosure *closure,
GClosureMarshal marshal)
{
g_return_if_fail (closure != NULL);
g_return_if_fail (marshal != NULL);
if (closure->marshal && closure->marshal != marshal)
g_warning ("attempt to override closure->marshal (%p) with new marshal (%p)",
closure->marshal, marshal);
else
closure->marshal = marshal;
}
void
_g_closure_set_va_marshal (GClosure *closure,
GVaClosureMarshal marshal)
{
GRealClosure *real_closure;
g_return_if_fail (closure != NULL);
g_return_if_fail (marshal != NULL);
real_closure = G_REAL_CLOSURE (closure);
if (real_closure->va_marshal && real_closure->va_marshal != marshal)
g_warning ("attempt to override closure->va_marshal (%p) with new marshal (%p)",
real_closure->va_marshal, marshal);
else
real_closure->va_marshal = marshal;
}
/**
* g_cclosure_new: (skip)
* @callback_func: the function to invoke
* @user_data: (closure callback_func): user data to pass to @callback_func
* @destroy_data: destroy notify to be called when @user_data is no longer used
*
* Creates a new closure which invokes @callback_func with @user_data as
* the last parameter.
*
* @destroy_data will be called as a finalize notifier on the #GClosure.
*
* Returns: (transfer none): a floating reference to a new #GCClosure
*/
GClosure*
g_cclosure_new (GCallback callback_func,
gpointer user_data,
GClosureNotify destroy_data)
{
GClosure *closure;
g_return_val_if_fail (callback_func != NULL, NULL);
closure = g_closure_new_simple (sizeof (GCClosure), user_data);
if (destroy_data)
g_closure_add_finalize_notifier (closure, user_data, destroy_data);
((GCClosure*) closure)->callback = (gpointer) callback_func;
return closure;
}
/**
* g_cclosure_new_swap: (skip)
* @callback_func: the function to invoke
* @user_data: (closure callback_func): user data to pass to @callback_func
* @destroy_data: destroy notify to be called when @user_data is no longer used
*
* Creates a new closure which invokes @callback_func with @user_data as
* the first parameter.
*
* @destroy_data will be called as a finalize notifier on the #GClosure.
*
* Returns: (transfer none): a floating reference to a new #GCClosure
*/
GClosure*
g_cclosure_new_swap (GCallback callback_func,
gpointer user_data,
GClosureNotify destroy_data)
{
GClosure *closure;
g_return_val_if_fail (callback_func != NULL, NULL);
closure = g_closure_new_simple (sizeof (GCClosure), user_data);
if (destroy_data)
g_closure_add_finalize_notifier (closure, user_data, destroy_data);
((GCClosure*) closure)->callback = (gpointer) callback_func;
SET (closure, derivative_flag, TRUE);
return closure;
}
static void
g_type_class_meta_marshal (GClosure *closure,
GValue /*out*/ *return_value,
guint n_param_values,
const GValue *param_values,
gpointer invocation_hint,
gpointer marshal_data)
{
GTypeClass *class;
gpointer callback;