1 /* GObject - GLib Type, Object, Parameter and Signal Library
2 * Copyright (C) 2000-2001 Red Hat, Inc.
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
8 *
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General
15 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
16 *
17 * this code is based on the original GtkSignal implementation
18 * for the Gtk+ library by Peter Mattis <petm@xcf.berkeley.edu>
19 */
20
21 /*
22 * MT safe
23 */
24
25 #include "config.h"
26
27 #include <string.h>
28 #include <signal.h>
29
30 #include "gsignal.h"
31 #include "gtype-private.h"
32 #include "gbsearcharray.h"
33 #include "gvaluecollector.h"
34 #include "gvaluetypes.h"
35 #include "gobject.h"
36 #include "genums.h"
37 #include "gobject_trace.h"
38
39
40 /**
41 * SECTION:signals
42 * @short_description: A means for customization of object behaviour
43 * and a general purpose notification mechanism
44 * @title: Signals
45 *
46 * The basic concept of the signal system is that of the emission
47 * of a signal. Signals are introduced per-type and are identified
48 * through strings. Signals introduced for a parent type are available
49 * in derived types as well, so basically they are a per-type facility
50 * that is inherited.
51 *
52 * A signal emission mainly involves invocation of a certain set of
53 * callbacks in precisely defined manner. There are two main categories
54 * of such callbacks, per-object ones and user provided ones.
55 * (Although signals can deal with any kind of instantiatable type, I'm
56 * referring to those types as "object types" in the following, simply
57 * because that is the context most users will encounter signals in.)
58 * The per-object callbacks are most often referred to as "object method
59 * handler" or "default (signal) handler", while user provided callbacks are
60 * usually just called "signal handler".
61 *
62 * The object method handler is provided at signal creation time (this most
63 * frequently happens at the end of an object class' creation), while user
64 * provided handlers are frequently connected and disconnected to/from a
65 * certain signal on certain object instances.
66 *
67 * A signal emission consists of five stages, unless prematurely stopped:
68 *
69 * 1. Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals
70 *
71 * 2. Invocation of normal user-provided signal handlers (where the @after
72 * flag is not set)
73 *
74 * 3. Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals
75 *
76 * 4. Invocation of user provided signal handlers (where the @after flag is set)
77 *
78 * 5. Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals
79
80 * The user-provided signal handlers are called in the order they were
81 * connected in.
82 *
83 * All handlers may prematurely stop a signal emission, and any number of
84 * handlers may be connected, disconnected, blocked or unblocked during
85 * a signal emission.
86 *
87 * There are certain criteria for skipping user handlers in stages 2 and 4
88 * of a signal emission.
89 *
90 * First, user handlers may be blocked. Blocked handlers are omitted during
91 * callback invocation, to return from the blocked state, a handler has to
92 * get unblocked exactly the same amount of times it has been blocked before.
93 *
94 * Second, upon emission of a %G_SIGNAL_DETAILED signal, an additional
95 * @detail argument passed in to g_signal_emit() has to match the detail
96 * argument of the signal handler currently subject to invocation.
97 * Specification of no detail argument for signal handlers (omission of the
98 * detail part of the signal specification upon connection) serves as a
99 * wildcard and matches any detail argument passed in to emission.
100 */
101
102
103 #define REPORT_BUG "please report occurrence circumstances to gtk-devel-list@gnome.org"
104
105 /* --- typedefs --- */
106 typedef struct _SignalNode SignalNode;
107 typedef struct _SignalKey SignalKey;
108 typedef struct _Emission Emission;
109 typedef struct _Handler Handler;
110 typedef struct _HandlerList HandlerList;
111 typedef struct _HandlerMatch HandlerMatch;
112 typedef enum
113 {
114 EMISSION_STOP,
115 EMISSION_RUN,
116 EMISSION_HOOK,
117 EMISSION_RESTART
118 } EmissionState;
119
120
121 /* --- prototypes --- */
122 static inline guint signal_id_lookup (GQuark quark,
123 GType itype);
124 static void signal_destroy_R (SignalNode *signal_node);
125 static inline HandlerList* handler_list_ensure (guint signal_id,
126 gpointer instance);
127 static inline HandlerList* handler_list_lookup (guint signal_id,
128 gpointer instance);
129 static inline Handler* handler_new (gboolean after);
130 static void handler_insert (guint signal_id,
131 gpointer instance,
132 Handler *handler);
133 static Handler* handler_lookup (gpointer instance,
134 gulong handler_id,
135 GClosure *closure,
136 guint *signal_id_p);
137 static inline HandlerMatch* handler_match_prepend (HandlerMatch *list,
138 Handler *handler,
139 guint signal_id);
140 static inline HandlerMatch* handler_match_free1_R (HandlerMatch *node,
141 gpointer instance);
142 static HandlerMatch* handlers_find (gpointer instance,
143 GSignalMatchType mask,
144 guint signal_id,
145 GQuark detail,
146 GClosure *closure,
147 gpointer func,
148 gpointer data,
149 gboolean one_and_only);
150 static inline void handler_ref (Handler *handler);
151 static inline void handler_unref_R (guint signal_id,
152 gpointer instance,
153 Handler *handler);
154 static gint handler_lists_cmp (gconstpointer node1,
155 gconstpointer node2);
156 static inline void emission_push (Emission **emission_list_p,
157 Emission *emission);
158 static inline void emission_pop (Emission **emission_list_p,
159 Emission *emission);
160 static inline Emission* emission_find (Emission *emission_list,
161 guint signal_id,
162 GQuark detail,
163 gpointer instance);
164 static gint class_closures_cmp (gconstpointer node1,
165 gconstpointer node2);
166 static gint signal_key_cmp (gconstpointer node1,
167 gconstpointer node2);
168 static gboolean signal_emit_unlocked_R (SignalNode *node,
169 GQuark detail,
170 gpointer instance,
171 GValue *return_value,
172 const GValue *instance_and_params);
173 static void add_invalid_closure_notify (Handler *handler,
174 gpointer instance);
175 static void remove_invalid_closure_notify (Handler *handler,
176 gpointer instance);
177 static void invalid_closure_notify (gpointer data,
178 GClosure *closure);
179 static const gchar * type_debug_name (GType type);
180 static void node_check_deprecated (const SignalNode *node);
181 static void node_update_single_va_closure (SignalNode *node);
182
183
184 /* --- structures --- */
185 typedef struct
186 {
187 GSignalAccumulator func;
188 gpointer data;
189 } SignalAccumulator;
190 typedef struct
191 {
192 GHook hook;
193 GQuark detail;
194 } SignalHook;
195 #define SIGNAL_HOOK(hook) ((SignalHook*) (hook))
196
197 struct _SignalNode
198 {
199 /* permanent portion */
200 guint signal_id;
201 GType itype;
202 const gchar *name;
203 guint destroyed : 1;
204
205 /* reinitializable portion */
206 guint flags : 9;
207 guint n_params : 8;
208 guint single_va_closure_is_valid : 1;
209 guint single_va_closure_is_after : 1;
210 GType *param_types; /* mangled with G_SIGNAL_TYPE_STATIC_SCOPE flag */
211 GType return_type; /* mangled with G_SIGNAL_TYPE_STATIC_SCOPE flag */
212 GBSearchArray *class_closure_bsa;
213 SignalAccumulator *accumulator;
214 GSignalCMarshaller c_marshaller;
215 GSignalCVaMarshaller va_marshaller;
216 GHookList *emission_hooks;
217
218 GClosure *single_va_closure;
219 };
220
221 #define SINGLE_VA_CLOSURE_EMPTY_MAGIC GINT_TO_POINTER(1) /* indicates single_va_closure is valid but empty */
222
223 struct _SignalKey
224 {
225 GType itype;
226 GQuark quark;
227 guint signal_id;
228 };
229
230 struct _Emission
231 {
232 Emission *next;
233 gpointer instance;
234 GSignalInvocationHint ihint;
235 EmissionState state;
236 GType chain_type;
237 };
238
239 struct _HandlerList
240 {
241 guint signal_id;
242 Handler *handlers;
243 Handler *tail_before; /* normal signal handlers are appended here */
244 Handler *tail_after; /* CONNECT_AFTER handlers are appended here */
245 };
246
247 struct _Handler
248 {
249 gulong sequential_number;
250 Handler *next;
251 Handler *prev;
252 GQuark detail;
253 guint ref_count;
254 guint block_count : 16;
255 #define HANDLER_MAX_BLOCK_COUNT (1 << 16)
256 guint after : 1;
257 guint has_invalid_closure_notify : 1;
258 GClosure *closure;
259 };
260 struct _HandlerMatch
261 {
262 Handler *handler;
263 HandlerMatch *next;
264 guint signal_id;
265 };
266
267 typedef struct
268 {
269 GType instance_type; /* 0 for default closure */
270 GClosure *closure;
271 } ClassClosure;
272
273
274 /* --- variables --- */
275 static GBSearchArray *g_signal_key_bsa = NULL;
276 static const GBSearchConfig g_signal_key_bconfig = {
277 sizeof (SignalKey),
278 signal_key_cmp,
279 G_BSEARCH_ARRAY_ALIGN_POWER2,
280 };
281 static GBSearchConfig g_signal_hlbsa_bconfig = {
282 sizeof (HandlerList),
283 handler_lists_cmp,
284 0,
285 };
286 static GBSearchConfig g_class_closure_bconfig = {
287 sizeof (ClassClosure),
288 class_closures_cmp,
289 0,
290 };
291 static GHashTable *g_handler_list_bsa_ht = NULL;
292 static Emission *g_recursive_emissions = NULL;
293 static Emission *g_restart_emissions = NULL;
294 static gulong g_handler_sequential_number = 1;
295 G_LOCK_DEFINE_STATIC (g_signal_mutex);
296 #define SIGNAL_LOCK() G_LOCK (g_signal_mutex)
297 #define SIGNAL_UNLOCK() G_UNLOCK (g_signal_mutex)
298
299
300 /* --- signal nodes --- */
301 static guint g_n_signal_nodes = 0;
302 static SignalNode **g_signal_nodes = NULL;
303
304 static inline SignalNode*
305 LOOKUP_SIGNAL_NODE (guint signal_id)
306 {
307 if (signal_id < g_n_signal_nodes)
308 return g_signal_nodes[signal_id];
309 else
310 return NULL;
311 }
312
313
314 /* --- functions --- */
315 static inline guint
316 signal_id_lookup (GQuark quark,
317 GType itype)
318 {
319 GType *ifaces, type = itype;
320 SignalKey key;
321 guint n_ifaces;
322
323 key.quark = quark;
324
325 /* try looking up signals for this type and its ancestors */
326 do
327 {
328 SignalKey *signal_key;
329
330 key.itype = type;
331 signal_key = g_bsearch_array_lookup (g_signal_key_bsa, &g_signal_key_bconfig, &key);
332
333 if (signal_key)
334 return signal_key->signal_id;
335
336 type = g_type_parent (type);
337 }
338 while (type);
339
340 /* no luck, try interfaces it exports */
341 ifaces = g_type_interfaces (itype, &n_ifaces);
342 while (n_ifaces--)
343 {
344 SignalKey *signal_key;
345
346 key.itype = ifaces[n_ifaces];
347 signal_key = g_bsearch_array_lookup (g_signal_key_bsa, &g_signal_key_bconfig, &key);
348
349 if (signal_key)
350 {
351 g_free (ifaces);
352 return signal_key->signal_id;
353 }
354 }
355 g_free (ifaces);
356
357 return 0;
358 }
359
360 static gint
361 class_closures_cmp (gconstpointer node1,
362 gconstpointer node2)
363 {
364 const ClassClosure *c1 = node1, *c2 = node2;
365
366 return G_BSEARCH_ARRAY_CMP (c1->instance_type, c2->instance_type);
367 }
368
369 static gint
370 handler_lists_cmp (gconstpointer node1,
371 gconstpointer node2)
372 {
373 const HandlerList *hlist1 = node1, *hlist2 = node2;
374
375 return G_BSEARCH_ARRAY_CMP (hlist1->signal_id, hlist2->signal_id);
376 }
377
378 static inline HandlerList*
379 handler_list_ensure (guint signal_id,
380 gpointer instance)
381 {
382 GBSearchArray *hlbsa = g_hash_table_lookup (g_handler_list_bsa_ht, instance);
383 HandlerList key;
384
385 key.signal_id = signal_id;
386 key.handlers = NULL;
387 key.tail_before = NULL;
388 key.tail_after = NULL;
389 if (!hlbsa)
390 {
391 hlbsa = g_bsearch_array_create (&g_signal_hlbsa_bconfig);
392 hlbsa = g_bsearch_array_insert (hlbsa, &g_signal_hlbsa_bconfig, &key);
393 g_hash_table_insert (g_handler_list_bsa_ht, instance, hlbsa);
394 }
395 else
396 {
397 GBSearchArray *o = hlbsa;
398
399 hlbsa = g_bsearch_array_insert (o, &g_signal_hlbsa_bconfig, &key);
400 if (hlbsa != o)
401 g_hash_table_insert (g_handler_list_bsa_ht, instance, hlbsa);
402 }
403 return g_bsearch_array_lookup (hlbsa, &g_signal_hlbsa_bconfig, &key);
404 }
405
406 static inline HandlerList*
407 handler_list_lookup (guint signal_id,
408 gpointer instance)
409 {
410 GBSearchArray *hlbsa = g_hash_table_lookup (g_handler_list_bsa_ht, instance);
411 HandlerList key;
412
413 key.signal_id = signal_id;
414
415 return hlbsa ? g_bsearch_array_lookup (hlbsa, &g_signal_hlbsa_bconfig, &key) : NULL;
416 }
417
418 static Handler*
419 handler_lookup (gpointer instance,
420 gulong handler_id,
421 GClosure *closure,
422 guint *signal_id_p)
423 {
424 GBSearchArray *hlbsa = g_hash_table_lookup (g_handler_list_bsa_ht, instance);
425
426 if (hlbsa)
427 {
428 guint i;
429
430 for (i = 0; i < hlbsa->n_nodes; i++)
431 {
432 HandlerList *hlist = g_bsearch_array_get_nth (hlbsa, &g_signal_hlbsa_bconfig, i);
433 Handler *handler;
434
435 for (handler = hlist->handlers; handler; handler = handler->next)
436 if (closure ? (handler->closure == closure) : (handler->sequential_number == handler_id))
437 {
438 if (signal_id_p)
439 *signal_id_p = hlist->signal_id;
440
441 return handler;
442 }
443 }
444 }
445
446 return NULL;
447 }
448
449 static inline HandlerMatch*
450 handler_match_prepend (HandlerMatch *list,
451 Handler *handler,
452 guint signal_id)
453 {
454 HandlerMatch *node;
455
456 node = g_slice_new (HandlerMatch);
457 #ifdef GSTREAMER_LITE
458 if (node == NULL) {
459 return NULL;
460 }
461 #endif // GSTREAMER_LITE
462 node->handler = handler;
463 node->next = list;
464 node->signal_id = signal_id;
465 handler_ref (handler);
466
467 return node;
468 }
469 static inline HandlerMatch*
470 handler_match_free1_R (HandlerMatch *node,
471 gpointer instance)
472 {
473 HandlerMatch *next = node->next;
474
475 handler_unref_R (node->signal_id, instance, node->handler);
476 g_slice_free (HandlerMatch, node);
477
478 return next;
479 }
480
481 static HandlerMatch*
482 handlers_find (gpointer instance,
483 GSignalMatchType mask,
484 guint signal_id,
485 GQuark detail,
486 GClosure *closure,
487 gpointer func,
488 gpointer data,
489 gboolean one_and_only)
490 {
491 HandlerMatch *mlist = NULL;
492
493 if (mask & G_SIGNAL_MATCH_ID)
494 {
495 HandlerList *hlist = handler_list_lookup (signal_id, instance);
496 Handler *handler;
497 SignalNode *node = NULL;
498
499 if (mask & G_SIGNAL_MATCH_FUNC)
500 {
501 node = LOOKUP_SIGNAL_NODE (signal_id);
502 if (!node || !node->c_marshaller)
503 return NULL;
504 }
505
506 mask = ~mask;
507 for (handler = hlist ? hlist->handlers : NULL; handler; handler = handler->next)
508 if (handler->sequential_number &&
509 ((mask & G_SIGNAL_MATCH_DETAIL) || handler->detail == detail) &&
510 ((mask & G_SIGNAL_MATCH_CLOSURE) || handler->closure == closure) &&
511 ((mask & G_SIGNAL_MATCH_DATA) || handler->closure->data == data) &&
512 ((mask & G_SIGNAL_MATCH_UNBLOCKED) || handler->block_count == 0) &&
513 ((mask & G_SIGNAL_MATCH_FUNC) || (handler->closure->marshal == node->c_marshaller &&
514 G_REAL_CLOSURE (handler->closure)->meta_marshal == NULL &&
515 ((GCClosure*) handler->closure)->callback == func)))
516 {
517 mlist = handler_match_prepend (mlist, handler, signal_id);
518 if (one_and_only)
519 return mlist;
520 }
521 }
522 else
523 {
524 GBSearchArray *hlbsa = g_hash_table_lookup (g_handler_list_bsa_ht, instance);
525
526 mask = ~mask;
527 if (hlbsa)
528 {
529 guint i;
530
531 for (i = 0; i < hlbsa->n_nodes; i++)
532 {
533 HandlerList *hlist = g_bsearch_array_get_nth (hlbsa, &g_signal_hlbsa_bconfig, i);
534 SignalNode *node = NULL;
535 Handler *handler;
536
537 if (!(mask & G_SIGNAL_MATCH_FUNC))
538 {
539 node = LOOKUP_SIGNAL_NODE (hlist->signal_id);
540 #ifndef GSTREAMER_LITE
541 if (!node->c_marshaller)
542 #else // GSTREAMER_LITE
543 if (!node || !node->c_marshaller)
544 #endif // GSTREAMER_LITE
545 continue;
546 }
547
548 for (handler = hlist->handlers; handler; handler = handler->next)
549 if (handler->sequential_number &&
550 ((mask & G_SIGNAL_MATCH_DETAIL) || handler->detail == detail) &&
551 ((mask & G_SIGNAL_MATCH_CLOSURE) || handler->closure == closure) &&
552 ((mask & G_SIGNAL_MATCH_DATA) || handler->closure->data == data) &&
553 ((mask & G_SIGNAL_MATCH_UNBLOCKED) || handler->block_count == 0) &&
554 ((mask & G_SIGNAL_MATCH_FUNC) || (handler->closure->marshal == node->c_marshaller &&
555 G_REAL_CLOSURE (handler->closure)->meta_marshal == NULL &&
556 ((GCClosure*) handler->closure)->callback == func)))
557 {
558 mlist = handler_match_prepend (mlist, handler, hlist->signal_id);
559 if (one_and_only)
560 return mlist;
561 }
562 }
563 }
564 }
565
566 return mlist;
567 }
568
569 static inline Handler*
570 handler_new (gboolean after)
571 {
572 Handler *handler = g_slice_new (Handler);
573 #ifndef G_DISABLE_CHECKS
574 if (g_handler_sequential_number < 1)
575 g_error (G_STRLOC ": handler id overflow, %s", REPORT_BUG);
576 #endif
577
578 handler->sequential_number = g_handler_sequential_number++;
579 handler->prev = NULL;
580 handler->next = NULL;
581 handler->detail = 0;
582 handler->ref_count = 1;
583 handler->block_count = 0;
584 handler->after = after != FALSE;
585 handler->closure = NULL;
586 handler->has_invalid_closure_notify = 0;
587
588 return handler;
589 }
590
591 static inline void
592 handler_ref (Handler *handler)
593 {
594 g_return_if_fail (handler->ref_count > 0);
595
596 handler->ref_count++;
597 }
598
599 static inline void
600 handler_unref_R (guint signal_id,
601 gpointer instance,
602 Handler *handler)
603 {
604 g_return_if_fail (handler->ref_count > 0);
605
606 handler->ref_count--;
607
608 if (G_UNLIKELY (handler->ref_count == 0))
609 {
610 HandlerList *hlist = NULL;
611
612 if (handler->next)
613 handler->next->prev = handler->prev;
614 if (handler->prev) /* watch out for g_signal_handlers_destroy()! */
615 handler->prev->next = handler->next;
616 else
617 {
618 hlist = handler_list_lookup (signal_id, instance);
619 hlist->handlers = handler->next;
620 }
621
622 if (instance)
623 {
624 /* check if we are removing the handler pointed to by tail_before */
625 if (!handler->after && (!handler->next || handler->next->after))
626 {
627 if (!hlist)
628 hlist = handler_list_lookup (signal_id, instance);
629 if (hlist)
630 {
631 g_assert (hlist->tail_before == handler); /* paranoid */
632 hlist->tail_before = handler->prev;
633 }
634 }
635
636 /* check if we are removing the handler pointed to by tail_after */
637 if (!handler->next)
638 {
639 if (!hlist)
640 hlist = handler_list_lookup (signal_id, instance);
641 if (hlist)
642 {
643 g_assert (hlist->tail_after == handler); /* paranoid */
644 hlist->tail_after = handler->prev;
645 }
646 }
647 }
648
649 SIGNAL_UNLOCK ();
650 g_closure_unref (handler->closure);
651 SIGNAL_LOCK ();
652 g_slice_free (Handler, handler);
653 }
654 }
655
656 static void
657 handler_insert (guint signal_id,
658 gpointer instance,
659 Handler *handler)
660 {
661 HandlerList *hlist;
662
663 g_assert (handler->prev == NULL && handler->next == NULL); /* paranoid */
664
665 hlist = handler_list_ensure (signal_id, instance);
666 if (!hlist->handlers)
667 {
668 hlist->handlers = handler;
669 if (!handler->after)
670 hlist->tail_before = handler;
671 }
672 else if (handler->after)
673 {
674 handler->prev = hlist->tail_after;
675 hlist->tail_after->next = handler;
676 }
677 else
678 {
679 if (hlist->tail_before)
680 {
681 handler->next = hlist->tail_before->next;
682 if (handler->next)
683 handler->next->prev = handler;
684 handler->prev = hlist->tail_before;
685 hlist->tail_before->next = handler;
686 }
687 else /* insert !after handler into a list of only after handlers */
688 {
689 handler->next = hlist->handlers;
690 if (handler->next)
691 handler->next->prev = handler;
692 hlist->handlers = handler;
693 }
694 hlist->tail_before = handler;
695 }
696
697 if (!handler->next)
698 hlist->tail_after = handler;
699 }
700
701 static void
702 node_update_single_va_closure (SignalNode *node)
703 {
704 GClosure *closure = NULL;
705 gboolean is_after = FALSE;
706
707 /* Fast path single-handler without boxing the arguments in GValues */
708 if (G_TYPE_IS_OBJECT (node->itype) &&
709 (node->flags & (G_SIGNAL_MUST_COLLECT)) == 0 &&
710 (node->emission_hooks == NULL || node->emission_hooks->hooks == NULL))
711 {
712 GSignalFlags run_type;
713 ClassClosure * cc;
714 GBSearchArray *bsa = node->class_closure_bsa;
715
716 if (bsa == NULL || bsa->n_nodes == 0)
717 closure = SINGLE_VA_CLOSURE_EMPTY_MAGIC;
718 else if (bsa->n_nodes == 1)
719 {
720 /* Look for default class closure (can't support non-default as it
721 chains up using GValues */
722 cc = g_bsearch_array_get_nth (bsa, &g_class_closure_bconfig, 0);
723 if (cc->instance_type == 0)
724 {
725 run_type = node->flags & (G_SIGNAL_RUN_FIRST|G_SIGNAL_RUN_LAST|G_SIGNAL_RUN_CLEANUP);
726 /* Only support *one* of run-first or run-last, not multiple or cleanup */
727 if (run_type == G_SIGNAL_RUN_FIRST ||
728 run_type == G_SIGNAL_RUN_LAST)
729 {
730 closure = cc->closure;
731 is_after = (run_type == G_SIGNAL_RUN_LAST);
732 }
733 }
734 }
735 }
736
737 node->single_va_closure_is_valid = TRUE;
738 node->single_va_closure = closure;
739 node->single_va_closure_is_after = is_after;
740 }
741
742 static inline void
743 emission_push (Emission **emission_list_p,
744 Emission *emission)
745 {
746 emission->next = *emission_list_p;
747 *emission_list_p = emission;
748 }
749
750 static inline void
751 emission_pop (Emission **emission_list_p,
752 Emission *emission)
753 {
754 Emission *node, *last = NULL;
755
756 for (node = *emission_list_p; node; last = node, node = last->next)
757 if (node == emission)
758 {
759 if (last)
760 last->next = node->next;
761 else
762 *emission_list_p = node->next;
763 return;
764 }
765 g_assert_not_reached ();
766 }
767
768 static inline Emission*
769 emission_find (Emission *emission_list,
770 guint signal_id,
771 GQuark detail,
772 gpointer instance)
773 {
774 Emission *emission;
775
776 for (emission = emission_list; emission; emission = emission->next)
777 if (emission->instance == instance &&
778 emission->ihint.signal_id == signal_id &&
779 emission->ihint.detail == detail)
780 return emission;
781 return NULL;
782 }
783
784 static inline Emission*
785 emission_find_innermost (gpointer instance)
786 {
787 Emission *emission, *s = NULL, *c = NULL;
788
789 for (emission = g_restart_emissions; emission; emission = emission->next)
790 if (emission->instance == instance)
791 {
792 s = emission;
793 break;
794 }
795 for (emission = g_recursive_emissions; emission; emission = emission->next)
796 if (emission->instance == instance)
797 {
798 c = emission;
799 break;
800 }
801 if (!s)
802 return c;
803 else if (!c)
804 return s;
805 else
806 return G_HAVE_GROWING_STACK ? MAX (c, s) : MIN (c, s);
807 }
808
809 static gint
810 signal_key_cmp (gconstpointer node1,
811 gconstpointer node2)
812 {
813 const SignalKey *key1 = node1, *key2 = node2;
814
815 if (key1->itype == key2->itype)
816 return G_BSEARCH_ARRAY_CMP (key1->quark, key2->quark);
817 else
818 return G_BSEARCH_ARRAY_CMP (key1->itype, key2->itype);
819 }
820
821 void
822 _g_signal_init (void)
823 {
824 SIGNAL_LOCK ();
825 if (!g_n_signal_nodes)
826 {
827 /* setup handler list binary searchable array hash table (in german, that'd be one word ;) */
828 g_handler_list_bsa_ht = g_hash_table_new (g_direct_hash, NULL);
829 g_signal_key_bsa = g_bsearch_array_create (&g_signal_key_bconfig);
830
831 /* invalid (0) signal_id */
832 g_n_signal_nodes = 1;
833 g_signal_nodes = g_renew (SignalNode*, g_signal_nodes, g_n_signal_nodes);
834 g_signal_nodes[0] = NULL;
835 }
836 SIGNAL_UNLOCK ();
837 }
838
839 void
840 _g_signals_destroy (GType itype)
841 {
842 guint i;
843
844 SIGNAL_LOCK ();
845 for (i = 1; i < g_n_signal_nodes; i++)
846 {
847 SignalNode *node = g_signal_nodes[i];
848
849 if (node->itype == itype)
850 {
851 if (node->destroyed)
852 g_warning (G_STRLOC ": signal \"%s\" of type '%s' already destroyed",
853 node->name,
854 type_debug_name (node->itype));
855 else
856 signal_destroy_R (node);
857 }
858 }
859 SIGNAL_UNLOCK ();
860 }
861
862 /**
863 * g_signal_stop_emission:
864 * @instance: (type GObject.Object): the object whose signal handlers you wish to stop.
865 * @signal_id: the signal identifier, as returned by g_signal_lookup().
866 * @detail: the detail which the signal was emitted with.
867 *
868 * Stops a signal's current emission.
869 *
870 * This will prevent the default method from running, if the signal was
871 * %G_SIGNAL_RUN_LAST and you connected normally (i.e. without the "after"
872 * flag).
873 *
874 * Prints a warning if used on a signal which isn't being emitted.
875 */
876 void
877 g_signal_stop_emission (gpointer instance,
878 guint signal_id,
879 GQuark detail)
880 {
881 SignalNode *node;
882
883 g_return_if_fail (G_TYPE_CHECK_INSTANCE (instance));
884 g_return_if_fail (signal_id > 0);
885
886 SIGNAL_LOCK ();
887 node = LOOKUP_SIGNAL_NODE (signal_id);
888 if (node && detail && !(node->flags & G_SIGNAL_DETAILED))
889 {
890 g_warning ("%s: signal id '%u' does not support detail (%u)", G_STRLOC, signal_id, detail);
891 SIGNAL_UNLOCK ();
892 return;
893 }
894 if (node && g_type_is_a (G_TYPE_FROM_INSTANCE (instance), node->itype))
895 {
896 Emission *emission_list = node->flags & G_SIGNAL_NO_RECURSE ? g_restart_emissions : g_recursive_emissions;
897 Emission *emission = emission_find (emission_list, signal_id, detail, instance);
898
899 if (emission)
900 {
901 if (emission->state == EMISSION_HOOK)
902 g_warning (G_STRLOC ": emission of signal \"%s\" for instance '%p' cannot be stopped from emission hook",
903 node->name, instance);
904 else if (emission->state == EMISSION_RUN)
905 emission->state = EMISSION_STOP;
906 }
907 else
908 g_warning (G_STRLOC ": no emission of signal \"%s\" to stop for instance '%p'",
909 node->name, instance);
910 }
911 else
912 g_warning ("%s: signal id '%u' is invalid for instance '%p'", G_STRLOC, signal_id, instance);
913 SIGNAL_UNLOCK ();
914 }
915
916 static void
917 signal_finalize_hook (GHookList *hook_list,
918 GHook *hook)
919 {
920 GDestroyNotify destroy = hook->destroy;
921
922 if (destroy)
923 {
924 hook->destroy = NULL;
925 SIGNAL_UNLOCK ();
926 destroy (hook->data);
927 SIGNAL_LOCK ();
928 }
929 }
930
931 /**
932 * g_signal_add_emission_hook:
933 * @signal_id: the signal identifier, as returned by g_signal_lookup().
934 * @detail: the detail on which to call the hook.
935 * @hook_func: a #GSignalEmissionHook function.
936 * @hook_data: user data for @hook_func.
937 * @data_destroy: a #GDestroyNotify for @hook_data.
938 *
939 * Adds an emission hook for a signal, which will get called for any emission
940 * of that signal, independent of the instance. This is possible only
941 * for signals which don't have #G_SIGNAL_NO_HOOKS flag set.
942 *
943 * Returns: the hook id, for later use with g_signal_remove_emission_hook().
944 */
945 gulong
946 g_signal_add_emission_hook (guint signal_id,
947 GQuark detail,
948 GSignalEmissionHook hook_func,
949 gpointer hook_data,
950 GDestroyNotify data_destroy)
951 {
952 static gulong seq_hook_id = 1;
953 SignalNode *node;
954 GHook *hook;
955 SignalHook *signal_hook;
956
957 g_return_val_if_fail (signal_id > 0, 0);
958 g_return_val_if_fail (hook_func != NULL, 0);
959
960 SIGNAL_LOCK ();
961 node = LOOKUP_SIGNAL_NODE (signal_id);
962 if (!node || node->destroyed)
963 {
964 g_warning ("%s: invalid signal id '%u'", G_STRLOC, signal_id);
965 SIGNAL_UNLOCK ();
966 return 0;
967 }
968 if (node->flags & G_SIGNAL_NO_HOOKS)
969 {
970 g_warning ("%s: signal id '%u' does not support emission hooks (G_SIGNAL_NO_HOOKS flag set)", G_STRLOC, signal_id);
971 SIGNAL_UNLOCK ();
972 return 0;
973 }
974 if (detail && !(node->flags & G_SIGNAL_DETAILED))
975 {
976 g_warning ("%s: signal id '%u' does not support detail (%u)", G_STRLOC, signal_id, detail);
977 SIGNAL_UNLOCK ();
978 return 0;
979 }
980 node->single_va_closure_is_valid = FALSE;
981 if (!node->emission_hooks)
982 {
983 node->emission_hooks = g_new (GHookList, 1);
984 g_hook_list_init (node->emission_hooks, sizeof (SignalHook));
985 node->emission_hooks->finalize_hook = signal_finalize_hook;
986 }
987
988 node_check_deprecated (node);
989
990 hook = g_hook_alloc (node->emission_hooks);
991 hook->data = hook_data;
992 hook->func = (gpointer) hook_func;
993 hook->destroy = data_destroy;
994 signal_hook = SIGNAL_HOOK (hook);
995 signal_hook->detail = detail;
996 node->emission_hooks->seq_id = seq_hook_id;
997 g_hook_append (node->emission_hooks, hook);
998 seq_hook_id = node->emission_hooks->seq_id;
999
1000 SIGNAL_UNLOCK ();
1001
1002 return hook->hook_id;
1003 }
1004
1005 /**
1006 * g_signal_remove_emission_hook:
1007 * @signal_id: the id of the signal
1008 * @hook_id: the id of the emission hook, as returned by
1009 * g_signal_add_emission_hook()
1010 *
1011 * Deletes an emission hook.
1012 */
1013 void
1014 g_signal_remove_emission_hook (guint signal_id,
1015 gulong hook_id)
1016 {
1017 SignalNode *node;
1018
1019 g_return_if_fail (signal_id > 0);
1020 g_return_if_fail (hook_id > 0);
1021
1022 SIGNAL_LOCK ();
1023 node = LOOKUP_SIGNAL_NODE (signal_id);
1024 if (!node || node->destroyed)
1025 {
1026 g_warning ("%s: invalid signal id '%u'", G_STRLOC, signal_id);
1027 goto out;
1028 }
1029 else if (!node->emission_hooks || !g_hook_destroy (node->emission_hooks, hook_id))
1030 g_warning ("%s: signal \"%s\" had no hook (%lu) to remove", G_STRLOC, node->name, hook_id);
1031
1032 node->single_va_closure_is_valid = FALSE;
1033
1034 out:
1035 SIGNAL_UNLOCK ();
1036 }
1037
1038 static inline guint
1039 signal_parse_name (const gchar *name,
1040 GType itype,
1041 GQuark *detail_p,
1042 gboolean force_quark)
1043 {
1044 const gchar *colon = strchr (name, ':');
1045 guint signal_id;
1046
1047 if (!colon)
1048 {
1049 signal_id = signal_id_lookup (g_quark_try_string (name), itype);
1050 if (signal_id && detail_p)
1051 *detail_p = 0;
1052 }
1053 else if (colon[1] == ':')
1054 {
1055 gchar buffer[32];
1056 guint l = colon - name;
1057
1058 if (l < 32)
1059 {
1060 memcpy (buffer, name, l);
1061 buffer[l] = 0;
1062 signal_id = signal_id_lookup (g_quark_try_string (buffer), itype);
1063 }
1064 else
1065 {
1066 gchar *signal = g_new (gchar, l + 1);
1067
1068 memcpy (signal, name, l);
1069 signal[l] = 0;
1070 signal_id = signal_id_lookup (g_quark_try_string (signal), itype);
1071 g_free (signal);
1072 }
1073
1074 if (signal_id && detail_p)
1075 *detail_p = colon[2] ? (force_quark ? g_quark_from_string : g_quark_try_string) (colon + 2) : 0;
1076 }
1077 else
1078 signal_id = 0;
1079 return signal_id;
1080 }
1081
1082 /**
1083 * g_signal_parse_name:
1084 * @detailed_signal: a string of the form "signal-name::detail".
1085 * @itype: The interface/instance type that introduced "signal-name".
1086 * @signal_id_p: (out): Location to store the signal id.
1087 * @detail_p: (out): Location to store the detail quark.
1088 * @force_detail_quark: %TRUE forces creation of a #GQuark for the detail.
1089 *
1090 * Internal function to parse a signal name into its @signal_id
1091 * and @detail quark.
1092 *
1093 * Returns: Whether the signal name could successfully be parsed and @signal_id_p and @detail_p contain valid return values.
1094 */
1095 gboolean
1096 g_signal_parse_name (const gchar *detailed_signal,
1097 GType itype,
1098 guint *signal_id_p,
1099 GQuark *detail_p,
1100 gboolean force_detail_quark)
1101 {
1102 SignalNode *node;
1103 GQuark detail = 0;
1104 guint signal_id;
1105
1106 g_return_val_if_fail (detailed_signal != NULL, FALSE);
1107 g_return_val_if_fail (G_TYPE_IS_INSTANTIATABLE (itype) || G_TYPE_IS_INTERFACE (itype), FALSE);
1108
1109 SIGNAL_LOCK ();
1110 signal_id = signal_parse_name (detailed_signal, itype, &detail, force_detail_quark);
1111 SIGNAL_UNLOCK ();
1112
1113 node = signal_id ? LOOKUP_SIGNAL_NODE (signal_id) : NULL;
1114 if (!node || node->destroyed ||
1115 (detail && !(node->flags & G_SIGNAL_DETAILED)))
1116 return FALSE;
1117
1118 if (signal_id_p)
1119 *signal_id_p = signal_id;
1120 if (detail_p)
1121 *detail_p = detail;
1122
1123 return TRUE;
1124 }
1125
1126 /**
1127 * g_signal_stop_emission_by_name:
1128 * @instance: (type GObject.Object): the object whose signal handlers you wish to stop.
1129 * @detailed_signal: a string of the form "signal-name::detail".
1130 *
1131 * Stops a signal's current emission.
1132 *
1133 * This is just like g_signal_stop_emission() except it will look up the
1134 * signal id for you.
1135 */
1136 void
1137 g_signal_stop_emission_by_name (gpointer instance,
1138 const gchar *detailed_signal)
1139 {
1140 guint signal_id;
1141 GQuark detail = 0;
1142 GType itype;
1143
1144 g_return_if_fail (G_TYPE_CHECK_INSTANCE (instance));
1145 g_return_if_fail (detailed_signal != NULL);
1146
1147 SIGNAL_LOCK ();
1148 itype = G_TYPE_FROM_INSTANCE (instance);
1149 signal_id = signal_parse_name (detailed_signal, itype, &detail, TRUE);
1150 if (signal_id)
1151 {
1152 SignalNode *node = LOOKUP_SIGNAL_NODE (signal_id);
1153
1154 if (detail && !(node->flags & G_SIGNAL_DETAILED))
1155 g_warning ("%s: signal '%s' does not support details", G_STRLOC, detailed_signal);
1156 else if (!g_type_is_a (itype, node->itype))
1157 g_warning ("%s: signal '%s' is invalid for instance '%p' of type '%s'",
1158 G_STRLOC, detailed_signal, instance, g_type_name (itype));
1159 else
1160 {
1161 Emission *emission_list = node->flags & G_SIGNAL_NO_RECURSE ? g_restart_emissions : g_recursive_emissions;
1162 Emission *emission = emission_find (emission_list, signal_id, detail, instance);
1163
1164 if (emission)
1165 {
1166 if (emission->state == EMISSION_HOOK)
1167 g_warning (G_STRLOC ": emission of signal \"%s\" for instance '%p' cannot be stopped from emission hook",
1168 node->name, instance);
1169 else if (emission->state == EMISSION_RUN)
1170 emission->state = EMISSION_STOP;
1171 }
1172 else
1173 g_warning (G_STRLOC ": no emission of signal \"%s\" to stop for instance '%p'",
1174 node->name, instance);
1175 }
1176 }
1177 else
1178 g_warning ("%s: signal '%s' is invalid for instance '%p' of type '%s'",
1179 G_STRLOC, detailed_signal, instance, g_type_name (itype));
1180 SIGNAL_UNLOCK ();
1181 }
1182
1183 /**
1184 * g_signal_lookup:
1185 * @name: the signal's name.
1186 * @itype: the type that the signal operates on.
1187 *
1188 * Given the name of the signal and the type of object it connects to, gets
1189 * the signal's identifying integer. Emitting the signal by number is
1190 * somewhat faster than using the name each time.
1191 *
1192 * Also tries the ancestors of the given type.
1193 *
1194 * See g_signal_new() for details on allowed signal names.
1195 *
1196 * Returns: the signal's identifying number, or 0 if no signal was found.
1197 */
1198 guint
1199 g_signal_lookup (const gchar *name,
1200 GType itype)
1201 {
1202 guint signal_id;
1203 g_return_val_if_fail (name != NULL, 0);
1204 g_return_val_if_fail (G_TYPE_IS_INSTANTIATABLE (itype) || G_TYPE_IS_INTERFACE (itype), 0);
1205
1206 SIGNAL_LOCK ();
1207 signal_id = signal_id_lookup (g_quark_try_string (name), itype);
1208 SIGNAL_UNLOCK ();
1209 if (!signal_id)
1210 {
1211 /* give elaborate warnings */
1212 if (!g_type_name (itype))
1213 g_warning (G_STRLOC ": unable to lookup signal \"%s\" for invalid type id '%"G_GSIZE_FORMAT"'",
1214 name, itype);
1215 else if (!G_TYPE_IS_INSTANTIATABLE (itype))
1216 g_warning (G_STRLOC ": unable to lookup signal \"%s\" for non instantiatable type '%s'",
1217 name, g_type_name (itype));
1218 else if (!g_type_class_peek (itype))
1219 g_warning (G_STRLOC ": unable to lookup signal \"%s\" of unloaded type '%s'",
1220 name, g_type_name (itype));
1221 }
1222
1223 return signal_id;
1224 }
1225
1226 /**
1227 * g_signal_list_ids:
1228 * @itype: Instance or interface type.
1229 * @n_ids: Location to store the number of signal ids for @itype.
1230 *
1231 * Lists the signals by id that a certain instance or interface type
1232 * created. Further information about the signals can be acquired through
1233 * g_signal_query().
1234 *
1235 * Returns: (array length=n_ids): Newly allocated array of signal IDs.
1236 */
1237 guint*
1238 g_signal_list_ids (GType itype,
1239 guint *n_ids)
1240 {
1241 SignalKey *keys;
1242 GArray *result;
1243 guint n_nodes;
1244 guint i;
1245
1246 g_return_val_if_fail (G_TYPE_IS_INSTANTIATABLE (itype) || G_TYPE_IS_INTERFACE (itype), NULL);
1247 g_return_val_if_fail (n_ids != NULL, NULL);
1248
1249 SIGNAL_LOCK ();
1250 keys = g_bsearch_array_get_nth (g_signal_key_bsa, &g_signal_key_bconfig, 0);
1251 n_nodes = g_bsearch_array_get_n_nodes (g_signal_key_bsa);
1252 result = g_array_new (FALSE, FALSE, sizeof (guint));
1253 #ifdef GSTREAMER_LITE
1254 if (result == NULL) {
1255 SIGNAL_UNLOCK ();
1256 return NULL;
1257 }
1258 #endif // GSTREAMER_LITE
1259
1260 for (i = 0; i < n_nodes; i++)
1261 if (keys[i].itype == itype)
1262 {
1263 const gchar *name = g_quark_to_string (keys[i].quark);
1264
1265 /* Signal names with "_" in them are aliases to the same
1266 * name with "-" instead of "_".
1267 */
1268 if (!strchr (name, '_'))
1269 g_array_append_val (result, keys[i].signal_id);
1270 }
1271 *n_ids = result->len;
1272 SIGNAL_UNLOCK ();
1273 if (!n_nodes)
1274 {
1275 /* give elaborate warnings */
1276 if (!g_type_name (itype))
1277 g_warning (G_STRLOC ": unable to list signals for invalid type id '%"G_GSIZE_FORMAT"'",
1278 itype);
1279 else if (!G_TYPE_IS_INSTANTIATABLE (itype) && !G_TYPE_IS_INTERFACE (itype))
1280 g_warning (G_STRLOC ": unable to list signals of non instantiatable type '%s'",
1281 g_type_name (itype));
1282 else if (!g_type_class_peek (itype) && !G_TYPE_IS_INTERFACE (itype))
1283 g_warning (G_STRLOC ": unable to list signals of unloaded type '%s'",
1284 g_type_name (itype));
1285 }
1286
1287 return (guint*) g_array_free (result, FALSE);
1288 }
1289
1290 /**
1291 * g_signal_name:
1292 * @signal_id: the signal's identifying number.
1293 *
1294 * Given the signal's identifier, finds its name.
1295 *
1296 * Two different signals may have the same name, if they have differing types.
1297 *
1298 * Returns: the signal name, or %NULL if the signal number was invalid.
1299 */
1300 const gchar *
1301 g_signal_name (guint signal_id)
1302 {
1303 SignalNode *node;
1304 const gchar *name;
1305
1306 SIGNAL_LOCK ();
1307 node = LOOKUP_SIGNAL_NODE (signal_id);
1308 name = node ? node->name : NULL;
1309 SIGNAL_UNLOCK ();
1310
1311 return (char*) name;
1312 }
1313
1314 /**
1315 * g_signal_query:
1316 * @signal_id: The signal id of the signal to query information for.
1317 * @query: (out caller-allocates): A user provided structure that is
1318 * filled in with constant values upon success.
1319 *
1320 * Queries the signal system for in-depth information about a
1321 * specific signal. This function will fill in a user-provided
1322 * structure to hold signal-specific information. If an invalid
1323 * signal id is passed in, the @signal_id member of the #GSignalQuery
1324 * is 0. All members filled into the #GSignalQuery structure should
1325 * be considered constant and have to be left untouched.
1326 */
1327 void
1328 g_signal_query (guint signal_id,
1329 GSignalQuery *query)
1330 {
1331 SignalNode *node;
1332
1333 g_return_if_fail (query != NULL);
1334
1335 SIGNAL_LOCK ();
1336 node = LOOKUP_SIGNAL_NODE (signal_id);
1337 if (!node || node->destroyed)
1338 query->signal_id = 0;
1339 else
1340 {
1341 query->signal_id = node->signal_id;
1342 query->signal_name = node->name;
1343 query->itype = node->itype;
1344 query->signal_flags = node->flags;
1345 query->return_type = node->return_type;
1346 query->n_params = node->n_params;
1347 query->param_types = node->param_types;
1348 }
1349 SIGNAL_UNLOCK ();
1350 }
1351
1352 /**
1353 * g_signal_new:
1354 * @signal_name: the name for the signal
1355 * @itype: the type this signal pertains to. It will also pertain to
1356 * types which are derived from this type.
1357 * @signal_flags: a combination of #GSignalFlags specifying detail of when
1358 * the default handler is to be invoked. You should at least specify
1359 * %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST.
1360 * @class_offset: The offset of the function pointer in the class structure
1361 * for this type. Used to invoke a class method generically. Pass 0 to
1362 * not associate a class method slot with this signal.
1363 * @accumulator: the accumulator for this signal; may be %NULL.
1364 * @accu_data: user data for the @accumulator.
1365 * @c_marshaller: (allow-none): the function to translate arrays of parameter
1366 * values to signal emissions into C language callback invocations or %NULL.
1367 * @return_type: the type of return value, or #G_TYPE_NONE for a signal
1368 * without a return value.
1369 * @n_params: the number of parameter types to follow.
1370 * @...: a list of types, one for each parameter.
1371 *
1372 * Creates a new signal. (This is usually done in the class initializer.)
1373 *
1374 * A signal name consists of segments consisting of ASCII letters and
1375 * digits, separated by either the '-' or '_' character. The first
1376 * character of a signal name must be a letter. Names which violate these
1377 * rules lead to undefined behaviour of the GSignal system.
1378 *
1379 * When registering a signal and looking up a signal, either separator can
1380 * be used, but they cannot be mixed.
1381 *
1382 * If 0 is used for @class_offset subclasses cannot override the class handler
1383 * in their class_init method by doing super_class->signal_handler = my_signal_handler.
1384 * Instead they will have to use g_signal_override_class_handler().
1385 *
1386 * If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as
1387 * the marshaller for this signal.
1388 *
1389 * Returns: the signal id
1390 */
1391 guint
1392 g_signal_new (const gchar *signal_name,
1393 GType itype,
1394 GSignalFlags signal_flags,
1395 guint class_offset,
1396 GSignalAccumulator accumulator,
1397 gpointer accu_data,
1398 GSignalCMarshaller c_marshaller,
1399 GType return_type,
1400 guint n_params,
1401 ...)
1402 {
1403 va_list args;
1404 guint signal_id;
1405
1406 g_return_val_if_fail (signal_name != NULL, 0);
1407
1408 va_start (args, n_params);
1409
1410 signal_id = g_signal_new_valist (signal_name, itype, signal_flags,
1411 class_offset ? g_signal_type_cclosure_new (itype, class_offset) : NULL,
1412 accumulator, accu_data, c_marshaller,
1413 return_type, n_params, args);
1414
1415 va_end (args);
1416
1417 return signal_id;
1418 }
1419
1420 /**
1421 * g_signal_new_class_handler:
1422 * @signal_name: the name for the signal
1423 * @itype: the type this signal pertains to. It will also pertain to
1424 * types which are derived from this type.
1425 * @signal_flags: a combination of #GSignalFlags specifying detail of when
1426 * the default handler is to be invoked. You should at least specify
1427 * %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST.
1428 * @class_handler: a #GCallback which acts as class implementation of
1429 * this signal. Used to invoke a class method generically. Pass %NULL to
1430 * not associate a class method with this signal.
1431 * @accumulator: the accumulator for this signal; may be %NULL.
1432 * @accu_data: user data for the @accumulator.
1433 * @c_marshaller: (allow-none): the function to translate arrays of parameter
1434 * values to signal emissions into C language callback invocations or %NULL.
1435 * @return_type: the type of return value, or #G_TYPE_NONE for a signal
1436 * without a return value.
1437 * @n_params: the number of parameter types to follow.
1438 * @...: a list of types, one for each parameter.
1439 *
1440 * Creates a new signal. (This is usually done in the class initializer.)
1441 *
1442 * This is a variant of g_signal_new() that takes a C callback instead
1443 * off a class offset for the signal's class handler. This function
1444 * doesn't need a function pointer exposed in the class structure of
1445 * an object definition, instead the function pointer is passed
1446 * directly and can be overriden by derived classes with
1447 * g_signal_override_class_closure() or
1448 * g_signal_override_class_handler()and chained to with
1449 * g_signal_chain_from_overridden() or
1450 * g_signal_chain_from_overridden_handler().
1451 *
1452 * See g_signal_new() for information about signal names.
1453 *
1454 * If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as
1455 * the marshaller for this signal.
1456 *
1457 * Returns: the signal id
1458 *
1459 * Since: 2.18
1460 */
1461 guint
1462 g_signal_new_class_handler (const gchar *signal_name,
1463 GType itype,
1464 GSignalFlags signal_flags,
1465 GCallback class_handler,
1466 GSignalAccumulator accumulator,
1467 gpointer accu_data,
1468 GSignalCMarshaller c_marshaller,
1469 GType return_type,
1470 guint n_params,
1471 ...)
1472 {
1473 va_list args;
1474 guint signal_id;
1475
1476 g_return_val_if_fail (signal_name != NULL, 0);
1477
1478 va_start (args, n_params);
1479
1480 signal_id = g_signal_new_valist (signal_name, itype, signal_flags,
1481 class_handler ? g_cclosure_new (class_handler, NULL, NULL) : NULL,
1482 accumulator, accu_data, c_marshaller,
1483 return_type, n_params, args);
1484
1485 va_end (args);
1486
1487 return signal_id;
1488 }
1489
1490 static inline ClassClosure*
1491 signal_find_class_closure (SignalNode *node,
1492 GType itype)
1493 {
1494 GBSearchArray *bsa = node->class_closure_bsa;
1495 ClassClosure *cc;
1496
1497 if (bsa)
1498 {
1499 ClassClosure key;
1500
1501 /* cc->instance_type is 0 for default closure */
1502
1503 key.instance_type = itype;
1504 cc = g_bsearch_array_lookup (bsa, &g_class_closure_bconfig, &key);
1505 while (!cc && key.instance_type)
1506 {
1507 key.instance_type = g_type_parent (key.instance_type);
1508 cc = g_bsearch_array_lookup (bsa, &g_class_closure_bconfig, &key);
1509 }
1510 }
1511 else
1512 cc = NULL;
1513 return cc;
1514 }
1515
1516 static inline GClosure*
1517 signal_lookup_closure (SignalNode *node,
1518 GTypeInstance *instance)
1519 {
1520 ClassClosure *cc;
1521
1522 if (node->class_closure_bsa && g_bsearch_array_get_n_nodes (node->class_closure_bsa) == 1)
1523 {
1524 cc = g_bsearch_array_get_nth (node->class_closure_bsa, &g_class_closure_bconfig, 0);
1525 if (cc && cc->instance_type == 0) /* check for default closure */
1526 return cc->closure;
1527 }
1528 cc = signal_find_class_closure (node, G_TYPE_FROM_INSTANCE (instance));
1529 return cc ? cc->closure : NULL;
1530 }
1531
1532 static void
1533 signal_add_class_closure (SignalNode *node,
1534 GType itype,
1535 GClosure *closure)
1536 {
1537 ClassClosure key;
1538
1539 node->single_va_closure_is_valid = FALSE;
1540
1541 if (!node->class_closure_bsa)
1542 node->class_closure_bsa = g_bsearch_array_create (&g_class_closure_bconfig);
1543 key.instance_type = itype;
1544 key.closure = g_closure_ref (closure);
1545 node->class_closure_bsa = g_bsearch_array_insert (node->class_closure_bsa,
1546 &g_class_closure_bconfig,
1547 &key);
1548 g_closure_sink (closure);
1549 if (node->c_marshaller && closure && G_CLOSURE_NEEDS_MARSHAL (closure))
1550 {
1551 g_closure_set_marshal (closure, node->c_marshaller);
1552 if (node->va_marshaller)
1553 _g_closure_set_va_marshal (closure, node->va_marshaller);
1554 }
1555 }
1556
1557 /**
1558 * g_signal_newv:
1559 * @signal_name: the name for the signal
1560 * @itype: the type this signal pertains to. It will also pertain to
1561 * types which are derived from this type
1562 * @signal_flags: a combination of #GSignalFlags specifying detail of when
1563 * the default handler is to be invoked. You should at least specify
1564 * %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST
1565 * @class_closure: (allow-none): The closure to invoke on signal emission;
1566 * may be %NULL
1567 * @accumulator: (allow-none): the accumulator for this signal; may be %NULL
1568 * @accu_data: user data for the @accumulator
1569 * @c_marshaller: (allow-none): the function to translate arrays of
1570 * parameter values to signal emissions into C language callback
1571 * invocations or %NULL
1572 * @return_type: the type of return value, or #G_TYPE_NONE for a signal
1573 * without a return value
1574 * @n_params: the length of @param_types
1575 * @param_types: (array length=n_params): an array of types, one for
1576 * each parameter
1577 *
1578 * Creates a new signal. (This is usually done in the class initializer.)
1579 *
1580 * See g_signal_new() for details on allowed signal names.
1581 *
1582 * If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as
1583 * the marshaller for this signal.
1584 *
1585 * Returns: the signal id
1586 */
1587 guint
1588 g_signal_newv (const gchar *signal_name,
1589 GType itype,
1590 GSignalFlags signal_flags,
1591 GClosure *class_closure,
1592 GSignalAccumulator accumulator,
1593 gpointer accu_data,
1594 GSignalCMarshaller c_marshaller,
1595 GType return_type,
1596 guint n_params,
1597 GType *param_types)
1598 {
1599 gchar *name;
1600 guint signal_id, i;
1601 SignalNode *node;
1602 GSignalCMarshaller builtin_c_marshaller;
1603 GSignalCVaMarshaller va_marshaller;
1604
1605 g_return_val_if_fail (signal_name != NULL, 0);
1606 g_return_val_if_fail (G_TYPE_IS_INSTANTIATABLE (itype) || G_TYPE_IS_INTERFACE (itype), 0);
1607 if (n_params)
1608 g_return_val_if_fail (param_types != NULL, 0);
1609 g_return_val_if_fail ((return_type & G_SIGNAL_TYPE_STATIC_SCOPE) == 0, 0);
1610 if (return_type == (G_TYPE_NONE & ~G_SIGNAL_TYPE_STATIC_SCOPE))
1611 g_return_val_if_fail (accumulator == NULL, 0);
1612 if (!accumulator)
1613 g_return_val_if_fail (accu_data == NULL, 0);
1614
1615 name = g_strdup (signal_name);
1616 g_strdelimit (name, G_STR_DELIMITERS ":^", '_'); /* FIXME do character checks like for types */
1617
1618 SIGNAL_LOCK ();
1619
1620 signal_id = signal_id_lookup (g_quark_try_string (name), itype);
1621 node = LOOKUP_SIGNAL_NODE (signal_id);
1622 if (node && !node->destroyed)
1623 {
1624 g_warning (G_STRLOC ": signal \"%s\" already exists in the '%s' %s",
1625 name,
1626 type_debug_name (node->itype),
1627 G_TYPE_IS_INTERFACE (node->itype) ? "interface" : "class ancestry");
1628 g_free (name);
1629 SIGNAL_UNLOCK ();
1630 return 0;
1631 }
1632 if (node && node->itype != itype)
1633 {
1634 g_warning (G_STRLOC ": signal \"%s\" for type '%s' was previously created for type '%s'",
1635 name,
1636 type_debug_name (itype),
1637 type_debug_name (node->itype));
1638 g_free (name);
1639 SIGNAL_UNLOCK ();
1640 return 0;
1641 }
1642 for (i = 0; i < n_params; i++)
1643 if (!G_TYPE_IS_VALUE (param_types[i] & ~G_SIGNAL_TYPE_STATIC_SCOPE))
1644 {
1645 g_warning (G_STRLOC ": parameter %d of type '%s' for signal \"%s::%s\" is not a value type",
1646 i + 1, type_debug_name (param_types[i]), type_debug_name (itype), name);
1647 g_free (name);
1648 SIGNAL_UNLOCK ();
1649 return 0;
1650 }
1651 if (return_type != G_TYPE_NONE && !G_TYPE_IS_VALUE (return_type & ~G_SIGNAL_TYPE_STATIC_SCOPE))
1652 {
1653 g_warning (G_STRLOC ": return value of type '%s' for signal \"%s::%s\" is not a value type",
1654 type_debug_name (return_type), type_debug_name (itype), name);
1655 g_free (name);
1656 SIGNAL_UNLOCK ();
1657 return 0;
1658 }
1659 if (return_type != G_TYPE_NONE &&
1660 (signal_flags & (G_SIGNAL_RUN_FIRST | G_SIGNAL_RUN_LAST | G_SIGNAL_RUN_CLEANUP)) == G_SIGNAL_RUN_FIRST)
1661 {
1662 g_warning (G_STRLOC ": signal \"%s::%s\" has return type '%s' and is only G_SIGNAL_RUN_FIRST",
1663 type_debug_name (itype), name, type_debug_name (return_type));
1664 g_free (name);
1665 SIGNAL_UNLOCK ();
1666 return 0;
1667 }
1668
1669 /* setup permanent portion of signal node */
1670 if (!node)
1671 {
1672 SignalKey key;
1673
1674 signal_id = g_n_signal_nodes++;
1675 node = g_new (SignalNode, 1);
1676 node->signal_id = signal_id;
1677 g_signal_nodes = g_renew (SignalNode*, g_signal_nodes, g_n_signal_nodes);
1678 g_signal_nodes[signal_id] = node;
1679 node->itype = itype;
1680 node->name = name;
1681 key.itype = itype;
1682 key.quark = g_quark_from_string (node->name);
1683 key.signal_id = signal_id;
1684 g_signal_key_bsa = g_bsearch_array_insert (g_signal_key_bsa, &g_signal_key_bconfig, &key);
1685 g_strdelimit (name, "_", '-');
1686 node->name = g_intern_string (name);
1687 key.quark = g_quark_from_string (name);
1688 g_signal_key_bsa = g_bsearch_array_insert (g_signal_key_bsa, &g_signal_key_bconfig, &key);
1689
1690 TRACE(GOBJECT_SIGNAL_NEW(signal_id, name, itype));
1691 }
1692 node->destroyed = FALSE;
1693
1694 /* setup reinitializable portion */
1695 node->single_va_closure_is_valid = FALSE;
1696 node->flags = signal_flags & G_SIGNAL_FLAGS_MASK;
1697 node->n_params = n_params;
1698 node->param_types = g_memdup (param_types, sizeof (GType) * n_params);
1699 node->return_type = return_type;
1700 node->class_closure_bsa = NULL;
1701 if (accumulator)
1702 {
1703 node->accumulator = g_new (SignalAccumulator, 1);
1704 node->accumulator->func = accumulator;
1705 node->accumulator->data = accu_data;
1706 }
1707 else
1708 node->accumulator = NULL;
1709
1710 builtin_c_marshaller = NULL;
1711 va_marshaller = NULL;
1712
1713 /* Pick up built-in va marshallers for standard types, and
1714 instead of generic marshaller if no marshaller specified */
1715 if (n_params == 0 && return_type == G_TYPE_NONE)
1716 {
1717 builtin_c_marshaller = g_cclosure_marshal_VOID__VOID;
1718 va_marshaller = g_cclosure_marshal_VOID__VOIDv;
1719 }
1720 else if (n_params == 1 && return_type == G_TYPE_NONE)
1721 {
1722 #define ADD_CHECK(__type__) \
1723 else if (g_type_is_a (param_types[0] & ~G_SIGNAL_TYPE_STATIC_SCOPE, G_TYPE_ ##__type__)) \
1724 { \
1725 builtin_c_marshaller = g_cclosure_marshal_VOID__ ## __type__; \
1726 va_marshaller = g_cclosure_marshal_VOID__ ## __type__ ##v; \
1727 }
1728
1729 if (0) {}
1730 ADD_CHECK (BOOLEAN)
1731 ADD_CHECK (CHAR)
1732 ADD_CHECK (UCHAR)
1733 ADD_CHECK (INT)
1734 ADD_CHECK (UINT)
1735 ADD_CHECK (LONG)
1736 ADD_CHECK (ULONG)
1737 ADD_CHECK (ENUM)
1738 ADD_CHECK (FLAGS)
1739 ADD_CHECK (FLOAT)
1740 ADD_CHECK (DOUBLE)
1741 ADD_CHECK (STRING)
1742 ADD_CHECK (PARAM)
1743 ADD_CHECK (BOXED)
1744 ADD_CHECK (POINTER)
1745 ADD_CHECK (OBJECT)
1746 ADD_CHECK (VARIANT)
1747 }
1748
1749 if (c_marshaller == NULL)
1750 {
1751 if (builtin_c_marshaller)
1752 c_marshaller = builtin_c_marshaller;
1753 else
1754 {
1755 c_marshaller = g_cclosure_marshal_generic;
1756 va_marshaller = g_cclosure_marshal_generic_va;
1757 }
1758 }
1759
1760 node->c_marshaller = c_marshaller;
1761 node->va_marshaller = va_marshaller;
1762 node->emission_hooks = NULL;
1763 if (class_closure)
1764 signal_add_class_closure (node, 0, class_closure);
1765
1766 SIGNAL_UNLOCK ();
1767
1768 g_free (name);
1769
1770 return signal_id;
1771 }
1772
1773 void
1774 g_signal_set_va_marshaller (guint signal_id,
1775 GType instance_type,
1776 GSignalCVaMarshaller va_marshaller)
1777 {
1778 SignalNode *node;
1779
1780 g_return_if_fail (signal_id > 0);
1781 g_return_if_fail (va_marshaller != NULL);
1782
1783 SIGNAL_LOCK ();
1784 node = LOOKUP_SIGNAL_NODE (signal_id);
1785 if (node)
1786 {
1787 node->va_marshaller = va_marshaller;
1788 if (node->class_closure_bsa)
1789 {
1790 ClassClosure *cc = g_bsearch_array_get_nth (node->class_closure_bsa, &g_class_closure_bconfig, 0);
1791 if (cc->closure->marshal == node->c_marshaller)
1792 _g_closure_set_va_marshal (cc->closure, va_marshaller);
1793 }
1794
1795 node->single_va_closure_is_valid = FALSE;
1796 }
1797
1798 SIGNAL_UNLOCK ();
1799 }
1800
1801
1802 /**
1803 * g_signal_new_valist:
1804 * @signal_name: the name for the signal
1805 * @itype: the type this signal pertains to. It will also pertain to
1806 * types which are derived from this type.
1807 * @signal_flags: a combination of #GSignalFlags specifying detail of when
1808 * the default handler is to be invoked. You should at least specify
1809 * %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST.
1810 * @class_closure: The closure to invoke on signal emission; may be %NULL.
1811 * @accumulator: the accumulator for this signal; may be %NULL.
1812 * @accu_data: user data for the @accumulator.
1813 * @c_marshaller: (allow-none): the function to translate arrays of parameter
1814 * values to signal emissions into C language callback invocations or %NULL.
1815 * @return_type: the type of return value, or #G_TYPE_NONE for a signal
1816 * without a return value.
1817 * @n_params: the number of parameter types in @args.
1818 * @args: va_list of #GType, one for each parameter.
1819 *
1820 * Creates a new signal. (This is usually done in the class initializer.)
1821 *
1822 * See g_signal_new() for details on allowed signal names.
1823 *
1824 * If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as
1825 * the marshaller for this signal.
1826 *
1827 * Returns: the signal id
1828 */
1829 guint
1830 g_signal_new_valist (const gchar *signal_name,
1831 GType itype,
1832 GSignalFlags signal_flags,
1833 GClosure *class_closure,
1834 GSignalAccumulator accumulator,
1835 gpointer accu_data,
1836 GSignalCMarshaller c_marshaller,
1837 GType return_type,
1838 guint n_params,
1839 va_list args)
1840 {
1841 GType *param_types;
1842 guint i;
1843 guint signal_id;
1844
1845 if (n_params > 0)
1846 {
1847 param_types = g_new (GType, n_params);
1848
1849 for (i = 0; i < n_params; i++)
1850 param_types[i] = va_arg (args, GType);
1851 }
1852 else
1853 param_types = NULL;
1854
1855 signal_id = g_signal_newv (signal_name, itype, signal_flags,
1856 class_closure, accumulator, accu_data, c_marshaller,
1857 return_type, n_params, param_types);
1858 g_free (param_types);
1859
1860 return signal_id;
1861 }
1862
1863 static void
1864 signal_destroy_R (SignalNode *signal_node)
1865 {
1866 SignalNode node = *signal_node;
1867
1868 signal_node->destroyed = TRUE;
1869
1870 /* reentrancy caution, zero out real contents first */
1871 signal_node->single_va_closure_is_valid = FALSE;
1872 signal_node->n_params = 0;
1873 signal_node->param_types = NULL;
1874 signal_node->return_type = 0;
1875 signal_node->class_closure_bsa = NULL;
1876 signal_node->accumulator = NULL;
1877 signal_node->c_marshaller = NULL;
1878 signal_node->va_marshaller = NULL;
1879 signal_node->emission_hooks = NULL;
1880
1881 #ifdef G_ENABLE_DEBUG
1882 /* check current emissions */
1883 {
1884 Emission *emission;
1885
1886 for (emission = (node.flags & G_SIGNAL_NO_RECURSE) ? g_restart_emissions : g_recursive_emissions;
1887 emission; emission = emission->next)
1888 if (emission->ihint.signal_id == node.signal_id)
1889 g_critical (G_STRLOC ": signal \"%s\" being destroyed is currently in emission (instance '%p')",
1890 node.name, emission->instance);
1891 }
1892 #endif
1893
1894 /* free contents that need to
1895 */
1896 SIGNAL_UNLOCK ();
1897 g_free (node.param_types);
1898 if (node.class_closure_bsa)
1899 {
1900 guint i;
1901
1902 for (i = 0; i < node.class_closure_bsa->n_nodes; i++)
1903 {
1904 ClassClosure *cc = g_bsearch_array_get_nth (node.class_closure_bsa, &g_class_closure_bconfig, i);
1905
1906 g_closure_unref (cc->closure);
1907 }
1908 g_bsearch_array_free (node.class_closure_bsa, &g_class_closure_bconfig);
1909 }
1910 g_free (node.accumulator);
1911 if (node.emission_hooks)
1912 {
1913 g_hook_list_clear (node.emission_hooks);
1914 g_free (node.emission_hooks);
1915 }
1916 SIGNAL_LOCK ();
1917 }
1918
1919 /**
1920 * g_signal_override_class_closure:
1921 * @signal_id: the signal id
1922 * @instance_type: the instance type on which to override the class closure
1923 * for the signal.
1924 * @class_closure: the closure.
1925 *
1926 * Overrides the class closure (i.e. the default handler) for the given signal
1927 * for emissions on instances of @instance_type. @instance_type must be derived
1928 * from the type to which the signal belongs.
1929 *
1930 * See g_signal_chain_from_overridden() and
1931 * g_signal_chain_from_overridden_handler() for how to chain up to the
1932 * parent class closure from inside the overridden one.
1933 */
1934 void
1935 g_signal_override_class_closure (guint signal_id,
1936 GType instance_type,
1937 GClosure *class_closure)
1938 {
1939 SignalNode *node;
1940
1941 g_return_if_fail (signal_id > 0);
1942 g_return_if_fail (class_closure != NULL);
1943
1944 SIGNAL_LOCK ();
1945 node = LOOKUP_SIGNAL_NODE (signal_id);
1946 node_check_deprecated (node);
1947 #ifndef GSTREAMER_LITE
1948 if (!g_type_is_a (instance_type, node->itype))
1949 #else // GSTREAMER_LITE
1950 if (node == NULL || !g_type_is_a (instance_type, node->itype))
1951 #endif // GSTREAMER_LITE
1952 g_warning ("%s: type '%s' cannot be overridden for signal id '%u'", G_STRLOC, type_debug_name (instance_type), signal_id);
1953 else
1954 {
1955 ClassClosure *cc = signal_find_class_closure (node, instance_type);
1956
1957 if (cc && cc->instance_type == instance_type)
1958 g_warning ("%s: type '%s' is already overridden for signal id '%u'", G_STRLOC, type_debug_name (instance_type), signal_id);
1959 else
1960 signal_add_class_closure (node, instance_type, class_closure);
1961 }
1962 SIGNAL_UNLOCK ();
1963 }
1964
1965 /**
1966 * g_signal_override_class_handler:
1967 * @signal_name: the name for the signal
1968 * @instance_type: the instance type on which to override the class handler
1969 * for the signal.
1970 * @class_handler: the handler.
1971 *
1972 * Overrides the class closure (i.e. the default handler) for the
1973 * given signal for emissions on instances of @instance_type with
1974 * callback @class_handler. @instance_type must be derived from the
1975 * type to which the signal belongs.
1976 *
1977 * See g_signal_chain_from_overridden() and
1978 * g_signal_chain_from_overridden_handler() for how to chain up to the
1979 * parent class closure from inside the overridden one.
1980 *
1981 * Since: 2.18
1982 */
1983 void
1984 g_signal_override_class_handler (const gchar *signal_name,
1985 GType instance_type,
1986 GCallback class_handler)
1987 {
1988 guint signal_id;
1989
1990 g_return_if_fail (signal_name != NULL);
1991 g_return_if_fail (instance_type != G_TYPE_NONE);
1992 g_return_if_fail (class_handler != NULL);
1993
1994 signal_id = g_signal_lookup (signal_name, instance_type);
1995
1996 if (signal_id)
1997 g_signal_override_class_closure (signal_id, instance_type,
1998 g_cclosure_new (class_handler, NULL, NULL));
1999 else
2000 g_warning ("%s: signal name '%s' is invalid for type id '%"G_GSIZE_FORMAT"'",
2001 G_STRLOC, signal_name, instance_type);
2002
2003 }
2004
2005 /**
2006 * g_signal_chain_from_overridden:
2007 * @instance_and_params: (array) the argument list of the signal emission.
2008 * The first element in the array is a #GValue for the instance the signal
2009 * is being emitted on. The rest are any arguments to be passed to the signal.
2010 * @return_value: Location for the return value.
2011 *
2012 * Calls the original class closure of a signal. This function should only
2013 * be called from an overridden class closure; see
2014 * g_signal_override_class_closure() and
2015 * g_signal_override_class_handler().
2016 */
2017 void
2018 g_signal_chain_from_overridden (const GValue *instance_and_params,
2019 GValue *return_value)
2020 {
2021 GType chain_type = 0, restore_type = 0;
2022 Emission *emission = NULL;
2023 GClosure *closure = NULL;
2024 guint n_params = 0;
2025 gpointer instance;
2026
2027 g_return_if_fail (instance_and_params != NULL);
2028 instance = g_value_peek_pointer (instance_and_params);
2029 g_return_if_fail (G_TYPE_CHECK_INSTANCE (instance));
2030
2031 SIGNAL_LOCK ();
2032 emission = emission_find_innermost (instance);
2033 if (emission)
2034 {
2035 SignalNode *node = LOOKUP_SIGNAL_NODE (emission->ihint.signal_id);
2036
2037 g_assert (node != NULL); /* paranoid */
2038
2039 /* we should probably do the same parameter checks as g_signal_emit() here.
2040 */
2041 if (emission->chain_type != G_TYPE_NONE)
2042 {
2043 ClassClosure *cc = signal_find_class_closure (node, emission->chain_type);
2044
2045 g_assert (cc != NULL); /* closure currently in call stack */
2046
2047 n_params = node->n_params;
2048 restore_type = cc->instance_type;
2049 cc = signal_find_class_closure (node, g_type_parent (cc->instance_type));
2050 if (cc && cc->instance_type != restore_type)
2051 {
2052 closure = cc->closure;
2053 chain_type = cc->instance_type;
2054 }
2055 }
2056 else
2057 g_warning ("%s: signal id '%u' cannot be chained from current emission stage for instance '%p'", G_STRLOC, node->signal_id, instance);
2058 }
2059 else
2060 g_warning ("%s: no signal is currently being emitted for instance '%p'", G_STRLOC, instance);
2061
2062 if (closure)
2063 {
2064 emission->chain_type = chain_type;
2065 SIGNAL_UNLOCK ();
2066 g_closure_invoke (closure,
2067 return_value,
2068 n_params + 1,
2069 instance_and_params,
2070 &emission->ihint);
2071 SIGNAL_LOCK ();
2072 emission->chain_type = restore_type;
2073 }
2074 SIGNAL_UNLOCK ();
2075 }
2076
2077 /**
2078 * g_signal_chain_from_overridden_handler: (skip)
2079 * @instance: the instance the signal is being emitted on.
2080 * @...: parameters to be passed to the parent class closure, followed by a
2081 * location for the return value. If the return type of the signal
2082 * is #G_TYPE_NONE, the return value location can be omitted.
2083 *
2084 * Calls the original class closure of a signal. This function should
2085 * only be called from an overridden class closure; see
2086 * g_signal_override_class_closure() and
2087 * g_signal_override_class_handler().
2088 *
2089 * Since: 2.18
2090 */
2091 void
2092 g_signal_chain_from_overridden_handler (gpointer instance,
2093 ...)
2094 {
2095 GType chain_type = 0, restore_type = 0;
2096 Emission *emission = NULL;
2097 GClosure *closure = NULL;
2098 SignalNode *node;
2099 guint n_params = 0;
2100
2101 g_return_if_fail (G_TYPE_CHECK_INSTANCE (instance));
2102
2103 SIGNAL_LOCK ();
2104 emission = emission_find_innermost (instance);
2105 if (emission)
2106 {
2107 node = LOOKUP_SIGNAL_NODE (emission->ihint.signal_id);
2108
2109 g_assert (node != NULL); /* paranoid */
2110
2111 /* we should probably do the same parameter checks as g_signal_emit() here.
2112 */
2113 if (emission->chain_type != G_TYPE_NONE)
2114 {
2115 ClassClosure *cc = signal_find_class_closure (node, emission->chain_type);
2116
2117 g_assert (cc != NULL); /* closure currently in call stack */
2118
2119 n_params = node->n_params;
2120 restore_type = cc->instance_type;
2121 cc = signal_find_class_closure (node, g_type_parent (cc->instance_type));
2122 if (cc && cc->instance_type != restore_type)
2123 {
2124 closure = cc->closure;
2125 chain_type = cc->instance_type;
2126 }
2127 }
2128 else
2129 g_warning ("%s: signal id '%u' cannot be chained from current emission stage for instance '%p'", G_STRLOC, node->signal_id, instance);
2130 }
2131 else
2132 g_warning ("%s: no signal is currently being emitted for instance '%p'", G_STRLOC, instance);
2133
2134 if (closure)
2135 {
2136 GValue *instance_and_params;
2137 GType signal_return_type;
2138 GValue *param_values;
2139 va_list var_args;
2140 guint i;
2141
2142 va_start (var_args, instance);
2143
2144 signal_return_type = node->return_type;
2145 instance_and_params = g_alloca (sizeof (GValue) * (n_params + 1));
2146 memset (instance_and_params, 0, sizeof (GValue) * (n_params + 1));
2147 param_values = instance_and_params + 1;
2148
2149 for (i = 0; i < node->n_params; i++)
2150 {
2151 gchar *error;
2152 GType ptype = node->param_types[i] & ~G_SIGNAL_TYPE_STATIC_SCOPE;
2153 gboolean static_scope = node->param_types[i] & G_SIGNAL_TYPE_STATIC_SCOPE;
2154
2155 SIGNAL_UNLOCK ();
2156 G_VALUE_COLLECT_INIT (param_values + i, ptype,
2157 var_args,
2158 static_scope ? G_VALUE_NOCOPY_CONTENTS : 0,
2159 &error);
2160 if (error)
2161 {
2162 g_warning ("%s: %s", G_STRLOC, error);
2163 g_free (error);
2164
2165 /* we purposely leak the value here, it might not be
2166 * in a sane state if an error condition occoured
2167 */
2168 while (i--)
2169 g_value_unset (param_values + i);
2170
2171 va_end (var_args);
2172 return;
2173 }
2174 SIGNAL_LOCK ();
2175 }
2176
2177 SIGNAL_UNLOCK ();
2178 instance_and_params->g_type = 0;
2179 g_value_init_from_instance (instance_and_params, instance);
2180 SIGNAL_LOCK ();
2181
2182 emission->chain_type = chain_type;
2183 SIGNAL_UNLOCK ();
2184
2185 if (signal_return_type == G_TYPE_NONE)
2186 {
2187 g_closure_invoke (closure,
2188 NULL,
2189 n_params + 1,
2190 instance_and_params,
2191 &emission->ihint);
2192 }
2193 else
2194 {
2195 GValue return_value = G_VALUE_INIT;
2196 gchar *error = NULL;
2197 GType rtype = signal_return_type & ~G_SIGNAL_TYPE_STATIC_SCOPE;
2198 gboolean static_scope = signal_return_type & G_SIGNAL_TYPE_STATIC_SCOPE;
2199
2200 g_value_init (&return_value, rtype);
2201
2202 g_closure_invoke (closure,
2203 &return_value,
2204 n_params + 1,
2205 instance_and_params,
2206 &emission->ihint);
2207
2208 G_VALUE_LCOPY (&return_value,
2209 var_args,
2210 static_scope ? G_VALUE_NOCOPY_CONTENTS : 0,
2211 &error);
2212 if (!error)
2213 {
2214 g_value_unset (&return_value);
2215 }
2216 else
2217 {
2218 g_warning ("%s: %s", G_STRLOC, error);
2219 g_free (error);
2220
2221 /* we purposely leak the value here, it might not be
2222 * in a sane state if an error condition occurred
2223 */
2224 }
2225 }
2226
2227 for (i = 0; i < n_params; i++)
2228 g_value_unset (param_values + i);
2229 g_value_unset (instance_and_params);
2230
2231 va_end (var_args);
2232
2233 SIGNAL_LOCK ();
2234 emission->chain_type = restore_type;
2235 }
2236 SIGNAL_UNLOCK ();
2237 }
2238
2239 /**
2240 * g_signal_get_invocation_hint:
2241 * @instance: (type GObject.Object): the instance to query
2242 *
2243 * Returns the invocation hint of the innermost signal emission of instance.
2244 *
2245 * Returns: (transfer none): the invocation hint of the innermost signal emission.
2246 */
2247 GSignalInvocationHint*
2248 g_signal_get_invocation_hint (gpointer instance)
2249 {
2250 Emission *emission = NULL;
2251
2252 g_return_val_if_fail (G_TYPE_CHECK_INSTANCE (instance), NULL);
2253
2254 SIGNAL_LOCK ();
2255 emission = emission_find_innermost (instance);
2256 SIGNAL_UNLOCK ();
2257
2258 return emission ? &emission->ihint : NULL;
2259 }
2260
2261 /**
2262 * g_signal_connect_closure_by_id:
2263 * @instance: (type GObject.Object): the instance to connect to.
2264 * @signal_id: the id of the signal.
2265 * @detail: the detail.
2266 * @closure: the closure to connect.
2267 * @after: whether the handler should be called before or after the
2268 * default handler of the signal.
2269 *
2270 * Connects a closure to a signal for a particular object.
2271 *
2272 * Returns: the handler id (always greater than 0 for successful connections)
2273 */
2274 gulong
2275 g_signal_connect_closure_by_id (gpointer instance,
2276 guint signal_id,
2277 GQuark detail,
2278 GClosure *closure,
2279 gboolean after)
2280 {
2281 SignalNode *node;
2282 gulong handler_seq_no = 0;
2283
2284 g_return_val_if_fail (G_TYPE_CHECK_INSTANCE (instance), 0);
2285 g_return_val_if_fail (signal_id > 0, 0);
2286 g_return_val_if_fail (closure != NULL, 0);
2287
2288 SIGNAL_LOCK ();
2289 node = LOOKUP_SIGNAL_NODE (signal_id);
2290 if (node)
2291 {
2292 if (detail && !(node->flags & G_SIGNAL_DETAILED))
2293 g_warning ("%s: signal id '%u' does not support detail (%u)", G_STRLOC, signal_id, detail);
2294 else if (!g_type_is_a (G_TYPE_FROM_INSTANCE (instance), node->itype))
2295 g_warning ("%s: signal id '%u' is invalid for instance '%p'", G_STRLOC, signal_id, instance);
2296 else
2297 {
2298 Handler *handler = handler_new (after);
2299
2300 handler_seq_no = handler->sequential_number;
2301 handler->detail = detail;
2302 handler->closure = g_closure_ref (closure);
2303 g_closure_sink (closure);
2304 add_invalid_closure_notify (handler, instance);
2305 handler_insert (signal_id, instance, handler);
2306 if (node->c_marshaller && G_CLOSURE_NEEDS_MARSHAL (closure))
2307 {
2308 g_closure_set_marshal (closure, node->c_marshaller);
2309 if (node->va_marshaller)
2310 _g_closure_set_va_marshal (closure, node->va_marshaller);
2311 }
2312 }
2313 }
2314 else
2315 g_warning ("%s: signal id '%u' is invalid for instance '%p'", G_STRLOC, signal_id, instance);
2316 SIGNAL_UNLOCK ();
2317
2318 return handler_seq_no;
2319 }
2320
2321 /**
2322 * g_signal_connect_closure:
2323 * @instance: (type GObject.Object): the instance to connect to.
2324 * @detailed_signal: a string of the form "signal-name::detail".
2325 * @closure: the closure to connect.
2326 * @after: whether the handler should be called before or after the
2327 * default handler of the signal.
2328 *
2329 * Connects a closure to a signal for a particular object.
2330 *
2331 * Returns: the handler id (always greater than 0 for successful connections)
2332 */
2333 gulong
2334 g_signal_connect_closure (gpointer instance,
2335 const gchar *detailed_signal,
2336 GClosure *closure,
2337 gboolean after)
2338 {
2339 guint signal_id;
2340 gulong handler_seq_no = 0;
2341 GQuark detail = 0;
2342 GType itype;
2343
2344 g_return_val_if_fail (G_TYPE_CHECK_INSTANCE (instance), 0);
2345 g_return_val_if_fail (detailed_signal != NULL, 0);
2346 g_return_val_if_fail (closure != NULL, 0);
2347
2348 SIGNAL_LOCK ();
2349 itype = G_TYPE_FROM_INSTANCE (instance);
2350 signal_id = signal_parse_name (detailed_signal, itype, &detail, TRUE);
2351 if (signal_id)
2352 {
2353 SignalNode *node = LOOKUP_SIGNAL_NODE (signal_id);
2354
2355 if (detail && !(node->flags & G_SIGNAL_DETAILED))
2356 g_warning ("%s: signal '%s' does not support details", G_STRLOC, detailed_signal);
2357 else if (!g_type_is_a (itype, node->itype))
2358 g_warning ("%s: signal '%s' is invalid for instance '%p' of type '%s'",
2359 G_STRLOC, detailed_signal, instance, g_type_name (itype));
2360 else
2361 {
2362 Handler *handler = handler_new (after);
2363
2364 handler_seq_no = handler->sequential_number;
2365 handler->detail = detail;
2366 handler->closure = g_closure_ref (closure);
2367 g_closure_sink (closure);
2368 add_invalid_closure_notify (handler, instance);
2369 handler_insert (signal_id, instance, handler);
2370 if (node->c_marshaller && G_CLOSURE_NEEDS_MARSHAL (handler->closure))
2371 {
2372 g_closure_set_marshal (handler->closure, node->c_marshaller);
2373 if (node->va_marshaller)
2374 _g_closure_set_va_marshal (handler->closure, node->va_marshaller);
2375 }
2376 }
2377 }
2378 else
2379 g_warning ("%s: signal '%s' is invalid for instance '%p' of type '%s'",
2380 G_STRLOC, detailed_signal, instance, g_type_name (itype));
2381 SIGNAL_UNLOCK ();
2382
2383 return handler_seq_no;
2384 }
2385
2386 static void
2387 node_check_deprecated (const SignalNode *node)
2388 {
2389 static const gchar * g_enable_diagnostic = NULL;
2390
2391 if (G_UNLIKELY (!g_enable_diagnostic))
2392 {
2393 g_enable_diagnostic = g_getenv ("G_ENABLE_DIAGNOSTIC");
2394 if (!g_enable_diagnostic)
2395 g_enable_diagnostic = "0";
2396 }
2397
2398 if (g_enable_diagnostic[0] == '1')
2399 {
2400 if (node->flags & G_SIGNAL_DEPRECATED)
2401 {
2402 g_warning ("The signal %s::%s is deprecated and shouldn't be used "
2403 "anymore. It will be removed in a future version.",
2404 type_debug_name (node->itype), node->name);
2405 }
2406 }
2407 }
2408
2409 /**
2410 * g_signal_connect_data:
2411 * @instance: (type GObject.Object): the instance to connect to.
2412 * @detailed_signal: a string of the form "signal-name::detail".
2413 * @c_handler: the #GCallback to connect.
2414 * @data: data to pass to @c_handler calls.
2415 * @destroy_data: a #GClosureNotify for @data.
2416 * @connect_flags: a combination of #GConnectFlags.
2417 *
2418 * Connects a #GCallback function to a signal for a particular object. Similar
2419 * to g_signal_connect(), but allows to provide a #GClosureNotify for the data
2420 * which will be called when the signal handler is disconnected and no longer
2421 * used. Specify @connect_flags if you need `..._after()` or
2422 * `..._swapped()` variants of this function.
2423 *
2424 * Returns: the handler id (always greater than 0 for successful connections)
2425 */
2426 gulong
2427 g_signal_connect_data (gpointer instance,
2428 const gchar *detailed_signal,
2429 GCallback c_handler,
2430 gpointer data,
2431 GClosureNotify destroy_data,
2432 GConnectFlags connect_flags)
2433 {
2434 guint signal_id;
2435 gulong handler_seq_no = 0;
2436 GQuark detail = 0;
2437 GType itype;
2438 gboolean swapped, after;
2439
2440 g_return_val_if_fail (G_TYPE_CHECK_INSTANCE (instance), 0);
2441 g_return_val_if_fail (detailed_signal != NULL, 0);
2442 g_return_val_if_fail (c_handler != NULL, 0);
2443
2444 swapped = (connect_flags & G_CONNECT_SWAPPED) != FALSE;
2445 after = (connect_flags & G_CONNECT_AFTER) != FALSE;
2446
2447 SIGNAL_LOCK ();
2448 itype = G_TYPE_FROM_INSTANCE (instance);
2449 signal_id = signal_parse_name (detailed_signal, itype, &detail, TRUE);
2450 if (signal_id)
2451 {
2452 SignalNode *node = LOOKUP_SIGNAL_NODE (signal_id);
2453
2454 node_check_deprecated (node);
2455
2456 if (detail && !(node->flags & G_SIGNAL_DETAILED))
2457 g_warning ("%s: signal '%s' does not support details", G_STRLOC, detailed_signal);
2458 else if (!g_type_is_a (itype, node->itype))
2459 g_warning ("%s: signal '%s' is invalid for instance '%p' of type '%s'",
2460 G_STRLOC, detailed_signal, instance, g_type_name (itype));
2461 else
2462 {
2463 Handler *handler = handler_new (after);
2464
2465 handler_seq_no = handler->sequential_number;
2466 handler->detail = detail;
2467 handler->closure = g_closure_ref ((swapped ? g_cclosure_new_swap : g_cclosure_new) (c_handler, data, destroy_data));
2468 g_closure_sink (handler->closure);
2469 handler_insert (signal_id, instance, handler);
2470 if (node->c_marshaller && G_CLOSURE_NEEDS_MARSHAL (handler->closure))
2471 {
2472 g_closure_set_marshal (handler->closure, node->c_marshaller);
2473 if (node->va_marshaller)
2474 _g_closure_set_va_marshal (handler->closure, node->va_marshaller);
2475 }
2476 }
2477 }
2478 else
2479 g_warning ("%s: signal '%s' is invalid for instance '%p' of type '%s'",
2480 G_STRLOC, detailed_signal, instance, g_type_name (itype));
2481 SIGNAL_UNLOCK ();
2482
2483 return handler_seq_no;
2484 }
2485
2486 /**
2487 * g_signal_handler_block:
2488 * @instance: (type GObject.Object): The instance to block the signal handler of.
2489 * @handler_id: Handler id of the handler to be blocked.
2490 *
2491 * Blocks a handler of an instance so it will not be called during any
2492 * signal emissions unless it is unblocked again. Thus "blocking" a
2493 * signal handler means to temporarily deactive it, a signal handler
2494 * has to be unblocked exactly the same amount of times it has been
2495 * blocked before to become active again.
2496 *
2497 * The @handler_id has to be a valid signal handler id, connected to a
2498 * signal of @instance.
2499 */
2500 void
2501 g_signal_handler_block (gpointer instance,
2502 gulong handler_id)
2503 {
2504 Handler *handler;
2505
2506 g_return_if_fail (G_TYPE_CHECK_INSTANCE (instance));
2507 g_return_if_fail (handler_id > 0);
2508
2509 SIGNAL_LOCK ();
2510 handler = handler_lookup (instance, handler_id, NULL, NULL);
2511 if (handler)
2512 {
2513 #ifndef G_DISABLE_CHECKS
2514 if (handler->block_count >= HANDLER_MAX_BLOCK_COUNT - 1)
2515 g_error (G_STRLOC ": handler block_count overflow, %s", REPORT_BUG);
2516 #endif
2517 handler->block_count += 1;
2518 }
2519 else
2520 g_warning ("%s: instance '%p' has no handler with id '%lu'", G_STRLOC, instance, handler_id);
2521 SIGNAL_UNLOCK ();
2522 }
2523
2524 /**
2525 * g_signal_handler_unblock:
2526 * @instance: (type GObject.Object): The instance to unblock the signal handler of.
2527 * @handler_id: Handler id of the handler to be unblocked.
2528 *
2529 * Undoes the effect of a previous g_signal_handler_block() call. A
2530 * blocked handler is skipped during signal emissions and will not be
2531 * invoked, unblocking it (for exactly the amount of times it has been
2532 * blocked before) reverts its "blocked" state, so the handler will be
2533 * recognized by the signal system and is called upon future or
2534 * currently ongoing signal emissions (since the order in which
2535 * handlers are called during signal emissions is deterministic,
2536 * whether the unblocked handler in question is called as part of a
2537 * currently ongoing emission depends on how far that emission has
2538 * proceeded yet).
2539 *
2540 * The @handler_id has to be a valid id of a signal handler that is
2541 * connected to a signal of @instance and is currently blocked.
2542 */
2543 void
2544 g_signal_handler_unblock (gpointer instance,
2545 gulong handler_id)
2546 {
2547 Handler *handler;
2548
2549 g_return_if_fail (G_TYPE_CHECK_INSTANCE (instance));
2550 g_return_if_fail (handler_id > 0);
2551
2552 SIGNAL_LOCK ();
2553 handler = handler_lookup (instance, handler_id, NULL, NULL);
2554 if (handler)
2555 {
2556 if (handler->block_count)
2557 handler->block_count -= 1;
2558 else
2559 g_warning (G_STRLOC ": handler '%lu' of instance '%p' is not blocked", handler_id, instance);
2560 }
2561 else
2562 g_warning ("%s: instance '%p' has no handler with id '%lu'", G_STRLOC, instance, handler_id);
2563 SIGNAL_UNLOCK ();
2564 }
2565
2566 /**
2567 * g_signal_handler_disconnect:
2568 * @instance: (type GObject.Object): The instance to remove the signal handler from.
2569 * @handler_id: Handler id of the handler to be disconnected.
2570 *
2571 * Disconnects a handler from an instance so it will not be called during
2572 * any future or currently ongoing emissions of the signal it has been
2573 * connected to. The @handler_id becomes invalid and may be reused.
2574 *
2575 * The @handler_id has to be a valid signal handler id, connected to a
2576 * signal of @instance.
2577 */
2578 void
2579 g_signal_handler_disconnect (gpointer instance,
2580 gulong handler_id)
2581 {
2582 Handler *handler;
2583 guint signal_id;
2584
2585 g_return_if_fail (G_TYPE_CHECK_INSTANCE (instance));
2586 g_return_if_fail (handler_id > 0);
2587
2588 SIGNAL_LOCK ();
2589 handler = handler_lookup (instance, handler_id, NULL, &signal_id);
2590 if (handler)
2591 {
2592 handler->sequential_number = 0;
2593 handler->block_count = 1;
2594 remove_invalid_closure_notify (handler, instance);
2595 handler_unref_R (signal_id, instance, handler);
2596 }
2597 else
2598 g_warning ("%s: instance '%p' has no handler with id '%lu'", G_STRLOC, instance, handler_id);
2599 SIGNAL_UNLOCK ();
2600 }
2601
2602 /**
2603 * g_signal_handler_is_connected:
2604 * @instance: (type GObject.Object): The instance where a signal handler is sought.
2605 * @handler_id: the handler id.
2606 *
2607 * Returns whether @handler_id is the id of a handler connected to @instance.
2608 *
2609 * Returns: whether @handler_id identifies a handler connected to @instance.
2610 */
2611 gboolean
2612 g_signal_handler_is_connected (gpointer instance,
2613 gulong handler_id)
2614 {
2615 Handler *handler;
2616 gboolean connected;
2617
2618 g_return_val_if_fail (G_TYPE_CHECK_INSTANCE (instance), FALSE);
2619
2620 SIGNAL_LOCK ();
2621 handler = handler_lookup (instance, handler_id, NULL, NULL);
2622 connected = handler != NULL;
2623 SIGNAL_UNLOCK ();
2624
2625 return connected;
2626 }
2627
2628 /**
2629 * g_signal_handlers_destroy:
2630 * @instance: (type GObject.Object): The instance whose signal handlers are destroyed
2631 *
2632 * Destroy all signal handlers of a type instance. This function is
2633 * an implementation detail of the #GObject dispose implementation,
2634 * and should not be used outside of the type system.
2635 */
2636 void
2637 g_signal_handlers_destroy (gpointer instance)
2638 {
2639 GBSearchArray *hlbsa;
2640
2641 g_return_if_fail (G_TYPE_CHECK_INSTANCE (instance));
2642
2643 SIGNAL_LOCK ();
2644 hlbsa = g_hash_table_lookup (g_handler_list_bsa_ht, instance);
2645 if (hlbsa)
2646 {
2647 guint i;
2648
2649 /* reentrancy caution, delete instance trace first */
2650 g_hash_table_remove (g_handler_list_bsa_ht, instance);
2651
2652 for (i = 0; i < hlbsa->n_nodes; i++)
2653 {
2654 HandlerList *hlist = g_bsearch_array_get_nth (hlbsa, &g_signal_hlbsa_bconfig, i);
2655 Handler *handler = hlist->handlers;
2656
2657 while (handler)
2658 {
2659 Handler *tmp = handler;
2660
2661 handler = tmp->next;
2662 tmp->block_count = 1;
2663 /* cruel unlink, this works because _all_ handlers vanish */
2664 tmp->next = NULL;
2665 tmp->prev = tmp;
2666 if (tmp->sequential_number)
2667 {
2668 remove_invalid_closure_notify (tmp, instance);
2669 tmp->sequential_number = 0;
2670 handler_unref_R (0, NULL, tmp);
2671 }
2672 }
2673 }
2674 g_bsearch_array_free (hlbsa, &g_signal_hlbsa_bconfig);
2675 }
2676 SIGNAL_UNLOCK ();
2677 }
2678
2679 /**
2680 * g_signal_handler_find:
2681 * @instance: (type GObject.Object): The instance owning the signal handler to be found.
2682 * @mask: Mask indicating which of @signal_id, @detail, @closure, @func
2683 * and/or @data the handler has to match.
2684 * @signal_id: Signal the handler has to be connected to.
2685 * @detail: Signal detail the handler has to be connected to.
2686 * @closure: (allow-none): The closure the handler will invoke.
2687 * @func: The C closure callback of the handler (useless for non-C closures).
2688 * @data: The closure data of the handler's closure.
2689 *
2690 * Finds the first signal handler that matches certain selection criteria.
2691 * The criteria mask is passed as an OR-ed combination of #GSignalMatchType
2692 * flags, and the criteria values are passed as arguments.
2693 * The match @mask has to be non-0 for successful matches.
2694 * If no handler was found, 0 is returned.
2695 *
2696 * Returns: A valid non-0 signal handler id for a successful match.
2697 */
2698 gulong
2699 g_signal_handler_find (gpointer instance,
2700 GSignalMatchType mask,
2701 guint signal_id,
2702 GQuark detail,
2703 GClosure *closure,
2704 gpointer func,
2705 gpointer data)
2706 {
2707 gulong handler_seq_no = 0;
2708
2709 g_return_val_if_fail (G_TYPE_CHECK_INSTANCE (instance), 0);
2710 g_return_val_if_fail ((mask & ~G_SIGNAL_MATCH_MASK) == 0, 0);
2711
2712 if (mask & G_SIGNAL_MATCH_MASK)
2713 {
2714 HandlerMatch *mlist;
2715
2716 SIGNAL_LOCK ();
2717 mlist = handlers_find (instance, mask, signal_id, detail, closure, func, data, TRUE);
2718 if (mlist)
2719 {
2720 handler_seq_no = mlist->handler->sequential_number;
2721 handler_match_free1_R (mlist, instance);
2722 }
2723 SIGNAL_UNLOCK ();
2724 }
2725
2726 return handler_seq_no;
2727 }
2728
2729 static guint
2730 signal_handlers_foreach_matched_R (gpointer instance,
2731 GSignalMatchType mask,
2732 guint signal_id,
2733 GQuark detail,
2734 GClosure *closure,
2735 gpointer func,
2736 gpointer data,
2737 void (*callback) (gpointer instance,
2738 gulong handler_seq_no))
2739 {
2740 HandlerMatch *mlist;
2741 guint n_handlers = 0;
2742
2743 mlist = handlers_find (instance, mask, signal_id, detail, closure, func, data, FALSE);
2744 while (mlist)
2745 {
2746 n_handlers++;
2747 if (mlist->handler->sequential_number)
2748 {
2749 SIGNAL_UNLOCK ();
2750 callback (instance, mlist->handler->sequential_number);
2751 SIGNAL_LOCK ();
2752 }
2753 mlist = handler_match_free1_R (mlist, instance);
2754 }
2755
2756 return n_handlers;
2757 }
2758
2759 /**
2760 * g_signal_handlers_block_matched:
2761 * @instance: (type GObject.Object): The instance to block handlers from.
2762 * @mask: Mask indicating which of @signal_id, @detail, @closure, @func
2763 * and/or @data the handlers have to match.
2764 * @signal_id: Signal the handlers have to be connected to.
2765 * @detail: Signal detail the handlers have to be connected to.
2766 * @closure: (allow-none): The closure the handlers will invoke.
2767 * @func: The C closure callback of the handlers (useless for non-C closures).
2768 * @data: The closure data of the handlers' closures.
2769 *
2770 * Blocks all handlers on an instance that match a certain selection criteria.
2771 * The criteria mask is passed as an OR-ed combination of #GSignalMatchType
2772 * flags, and the criteria values are passed as arguments.
2773 * Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC
2774 * or %G_SIGNAL_MATCH_DATA match flags is required for successful matches.
2775 * If no handlers were found, 0 is returned, the number of blocked handlers
2776 * otherwise.
2777 *
2778 * Returns: The number of handlers that matched.
2779 */
2780 guint
2781 g_signal_handlers_block_matched (gpointer instance,
2782 GSignalMatchType mask,
2783 guint signal_id,
2784 GQuark detail,
2785 GClosure *closure,
2786 gpointer func,
2787 gpointer data)
2788 {
2789 guint n_handlers = 0;
2790
2791 g_return_val_if_fail (G_TYPE_CHECK_INSTANCE (instance), 0);
2792 g_return_val_if_fail ((mask & ~G_SIGNAL_MATCH_MASK) == 0, 0);
2793
2794 if (mask & (G_SIGNAL_MATCH_CLOSURE | G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA))
2795 {
2796 SIGNAL_LOCK ();
2797 n_handlers = signal_handlers_foreach_matched_R (instance, mask, signal_id, detail,
2798 closure, func, data,
2799 g_signal_handler_block);
2800 SIGNAL_UNLOCK ();
2801 }
2802
2803 return n_handlers;
2804 }
2805
2806 /**
2807 * g_signal_handlers_unblock_matched:
2808 * @instance: (type GObject.Object): The instance to unblock handlers from.
2809 * @mask: Mask indicating which of @signal_id, @detail, @closure, @func
2810 * and/or @data the handlers have to match.
2811 * @signal_id: Signal the handlers have to be connected to.
2812 * @detail: Signal detail the handlers have to be connected to.
2813 * @closure: (allow-none): The closure the handlers will invoke.
2814 * @func: The C closure callback of the handlers (useless for non-C closures).
2815 * @data: The closure data of the handlers' closures.
2816 *
2817 * Unblocks all handlers on an instance that match a certain selection
2818 * criteria. The criteria mask is passed as an OR-ed combination of
2819 * #GSignalMatchType flags, and the criteria values are passed as arguments.
2820 * Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC
2821 * or %G_SIGNAL_MATCH_DATA match flags is required for successful matches.
2822 * If no handlers were found, 0 is returned, the number of unblocked handlers
2823 * otherwise. The match criteria should not apply to any handlers that are
2824 * not currently blocked.
2825 *
2826 * Returns: The number of handlers that matched.
2827 */
2828 guint
2829 g_signal_handlers_unblock_matched (gpointer instance,
2830 GSignalMatchType mask,
2831 guint signal_id,
2832 GQuark detail,
2833 GClosure *closure,
2834 gpointer func,
2835 gpointer data)
2836 {
2837 guint n_handlers = 0;
2838
2839 g_return_val_if_fail (G_TYPE_CHECK_INSTANCE (instance), 0);
2840 g_return_val_if_fail ((mask & ~G_SIGNAL_MATCH_MASK) == 0, 0);
2841
2842 if (mask & (G_SIGNAL_MATCH_CLOSURE | G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA))
2843 {
2844 SIGNAL_LOCK ();
2845 n_handlers = signal_handlers_foreach_matched_R (instance, mask, signal_id, detail,
2846 closure, func, data,
2847 g_signal_handler_unblock);
2848 SIGNAL_UNLOCK ();
2849 }
2850
2851 return n_handlers;
2852 }
2853
2854 /**
2855 * g_signal_handlers_disconnect_matched:
2856 * @instance: (type GObject.Object): The instance to remove handlers from.
2857 * @mask: Mask indicating which of @signal_id, @detail, @closure, @func
2858 * and/or @data the handlers have to match.
2859 * @signal_id: Signal the handlers have to be connected to.
2860 * @detail: Signal detail the handlers have to be connected to.
2861 * @closure: (allow-none): The closure the handlers will invoke.
2862 * @func: The C closure callback of the handlers (useless for non-C closures).
2863 * @data: The closure data of the handlers' closures.
2864 *
2865 * Disconnects all handlers on an instance that match a certain
2866 * selection criteria. The criteria mask is passed as an OR-ed
2867 * combination of #GSignalMatchType flags, and the criteria values are
2868 * passed as arguments. Passing at least one of the
2869 * %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC or
2870 * %G_SIGNAL_MATCH_DATA match flags is required for successful
2871 * matches. If no handlers were found, 0 is returned, the number of
2872 * disconnected handlers otherwise.
2873 *
2874 * Returns: The number of handlers that matched.
2875 */
2876 guint
2877 g_signal_handlers_disconnect_matched (gpointer instance,
2878 GSignalMatchType mask,
2879 guint signal_id,
2880 GQuark detail,
2881 GClosure *closure,
2882 gpointer func,
2883 gpointer data)
2884 {
2885 guint n_handlers = 0;
2886
2887 g_return_val_if_fail (G_TYPE_CHECK_INSTANCE (instance), 0);
2888 g_return_val_if_fail ((mask & ~G_SIGNAL_MATCH_MASK) == 0, 0);
2889
2890 if (mask & (G_SIGNAL_MATCH_CLOSURE | G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA))
2891 {
2892 SIGNAL_LOCK ();
2893 n_handlers = signal_handlers_foreach_matched_R (instance, mask, signal_id, detail,
2894 closure, func, data,
2895 g_signal_handler_disconnect);
2896 SIGNAL_UNLOCK ();
2897 }
2898
2899 return n_handlers;
2900 }
2901
2902 /**
2903 * g_signal_has_handler_pending:
2904 * @instance: (type GObject.Object): the object whose signal handlers are sought.
2905 * @signal_id: the signal id.
2906 * @detail: the detail.
2907 * @may_be_blocked: whether blocked handlers should count as match.
2908 *
2909 * Returns whether there are any handlers connected to @instance for the
2910 * given signal id and detail.
2911 *
2912 * One example of when you might use this is when the arguments to the
2913 * signal are difficult to compute. A class implementor may opt to not
2914 * emit the signal if no one is attached anyway, thus saving the cost
2915 * of building the arguments.
2916 *
2917 * Returns: %TRUE if a handler is connected to the signal, %FALSE
2918 * otherwise.
2919 */
2920 gboolean
2921 g_signal_has_handler_pending (gpointer instance,
2922 guint signal_id,
2923 GQuark detail,
2924 gboolean may_be_blocked)
2925 {
2926 HandlerMatch *mlist;
2927 gboolean has_pending;
2928
2929 g_return_val_if_fail (G_TYPE_CHECK_INSTANCE (instance), FALSE);
2930 g_return_val_if_fail (signal_id > 0, FALSE);
2931
2932 SIGNAL_LOCK ();
2933 if (detail)
2934 {
2935 SignalNode *node = LOOKUP_SIGNAL_NODE (signal_id);
2936 #ifndef GSTREAMER_LITE
2937 if (!(node->flags & G_SIGNAL_DETAILED))
2938 #else // GSTREAMER_LITE
2939 if (node == NULL || !(node->flags & G_SIGNAL_DETAILED))
2940 #endif // GSTREAMER_LITE
2941 {
2942 g_warning ("%s: signal id '%u' does not support detail (%u)", G_STRLOC, signal_id, detail);
2943 SIGNAL_UNLOCK ();
2944 return FALSE;
2945 }
2946 }
2947 mlist = handlers_find (instance,
2948 (G_SIGNAL_MATCH_ID | G_SIGNAL_MATCH_DETAIL | (may_be_blocked ? 0 : G_SIGNAL_MATCH_UNBLOCKED)),
2949 signal_id, detail, NULL, NULL, NULL, TRUE);
2950 if (mlist)
2951 {
2952 has_pending = TRUE;
2953 handler_match_free1_R (mlist, instance);
2954 }
2955 else
2956 has_pending = FALSE;
2957 SIGNAL_UNLOCK ();
2958
2959 return has_pending;
2960 }
2961
2962 /**
2963 * g_signal_emitv:
2964 * @instance_and_params: (array): argument list for the signal emission.
2965 * The first element in the array is a #GValue for the instance the signal
2966 * is being emitted on. The rest are any arguments to be passed to the signal.
2967 * @signal_id: the signal id
2968 * @detail: the detail
2969 * @return_value: Location to store the return value of the signal emission.
2970 *
2971 * Emits a signal.
2972 *
2973 * Note that g_signal_emitv() doesn't change @return_value if no handlers are
2974 * connected, in contrast to g_signal_emit() and g_signal_emit_valist().
2975 */
2976 void
2977 g_signal_emitv (const GValue *instance_and_params,
2978 guint signal_id,
2979 GQuark detail,
2980 GValue *return_value)
2981 {
2982 gpointer instance;
2983 SignalNode *node;
2984 #ifdef G_ENABLE_DEBUG
2985 const GValue *param_values;
2986 guint i;
2987 #endif
2988
2989 g_return_if_fail (instance_and_params != NULL);
2990 instance = g_value_peek_pointer (instance_and_params);
2991 g_return_if_fail (G_TYPE_CHECK_INSTANCE (instance));
2992 g_return_if_fail (signal_id > 0);
2993
2994 #ifdef G_ENABLE_DEBUG
2995 param_values = instance_and_params + 1;
2996 #endif
2997
2998 SIGNAL_LOCK ();
2999 node = LOOKUP_SIGNAL_NODE (signal_id);
3000 if (!node || !g_type_is_a (G_TYPE_FROM_INSTANCE (instance), node->itype))
3001 {
3002 g_warning ("%s: signal id '%u' is invalid for instance '%p'", G_STRLOC, signal_id, instance);
3003 SIGNAL_UNLOCK ();
3004 return;
3005 }
3006 #ifdef G_ENABLE_DEBUG
3007 if (detail && !(node->flags & G_SIGNAL_DETAILED))
3008 {
3009 g_warning ("%s: signal id '%u' does not support detail (%u)", G_STRLOC, signal_id, detail);
3010 SIGNAL_UNLOCK ();
3011 return;
3012 }
3013 for (i = 0; i < node->n_params; i++)
3014 if (!G_TYPE_CHECK_VALUE_TYPE (param_values + i, node->param_types[i] & ~G_SIGNAL_TYPE_STATIC_SCOPE))
3015 {
3016 g_critical ("%s: value for '%s' parameter %u for signal \"%s\" is of type '%s'",
3017 G_STRLOC,
3018 type_debug_name (node->param_types[i]),
3019 i,
3020 node->name,
3021 G_VALUE_TYPE_NAME (param_values + i));
3022 SIGNAL_UNLOCK ();
3023 return;
3024 }
3025 if (node->return_type != G_TYPE_NONE)
3026 {
3027 if (!return_value)
3028 {
3029 g_critical ("%s: return value '%s' for signal \"%s\" is (NULL)",
3030 G_STRLOC,
3031 type_debug_name (node->return_type),
3032 node->name);
3033 SIGNAL_UNLOCK ();
3034 return;
3035 }
3036 else if (!node->accumulator && !G_TYPE_CHECK_VALUE_TYPE (return_value, node->return_type & ~G_SIGNAL_TYPE_STATIC_SCOPE))
3037 {
3038 g_critical ("%s: return value '%s' for signal \"%s\" is of type '%s'",
3039 G_STRLOC,
3040 type_debug_name (node->return_type),
3041 node->name,
3042 G_VALUE_TYPE_NAME (return_value));
3043 SIGNAL_UNLOCK ();
3044 return;
3045 }
3046 }
3047 else
3048 return_value = NULL;
3049 #endif /* G_ENABLE_DEBUG */
3050
3051 /* optimize NOP emissions */
3052 if (!node->single_va_closure_is_valid)
3053 node_update_single_va_closure (node);
3054
3055 if (node->single_va_closure != NULL &&
3056 (node->single_va_closure == SINGLE_VA_CLOSURE_EMPTY_MAGIC ||
3057 _g_closure_is_void (node->single_va_closure, instance)))
3058 {
3059 HandlerList* hlist = handler_list_lookup (node->signal_id, instance);
3060 if (hlist == NULL || hlist->handlers == NULL)
3061 {
3062 /* nothing to do to emit this signal */
3063 SIGNAL_UNLOCK ();
3064 /* g_printerr ("omitting emission of \"%s\"\n", node->name); */
3065 return;
3066 }
3067 }
3068
3069 SIGNAL_UNLOCK ();
3070 signal_emit_unlocked_R (node, detail, instance, return_value, instance_and_params);
3071 }
3072
3073 static inline gboolean
3074 accumulate (GSignalInvocationHint *ihint,
3075 GValue *return_accu,
3076 GValue *handler_return,
3077 SignalAccumulator *accumulator)
3078 {
3079 gboolean continue_emission;
3080
3081 if (!accumulator)
3082 return TRUE;
3083
3084 continue_emission = accumulator->func (ihint, return_accu, handler_return, accumulator->data);
3085 g_value_reset (handler_return);
3086
3087 return continue_emission;
3088 }
3089
3090 /**
3091 * g_signal_emit_valist: (skip)
3092 * @instance: the instance the signal is being emitted on.
3093 * @signal_id: the signal id
3094 * @detail: the detail
3095 * @var_args: a list of parameters to be passed to the signal, followed by a
3096 * location for the return value. If the return type of the signal
3097 * is #G_TYPE_NONE, the return value location can be omitted.
3098 *
3099 * Emits a signal.
3100 *
3101 * Note that g_signal_emit_valist() resets the return value to the default
3102 * if no handlers are connected, in contrast to g_signal_emitv().
3103 */
3104 void
3105 g_signal_emit_valist (gpointer instance,
3106 guint signal_id,
3107 GQuark detail,
3108 va_list var_args)
3109 {
3110 GValue *instance_and_params;
3111 GType signal_return_type;
3112 GValue *param_values;
3113 SignalNode *node;
3114 guint i, n_params;
3115
3116 g_return_if_fail (G_TYPE_CHECK_INSTANCE (instance));
3117 g_return_if_fail (signal_id > 0);
3118
3119 SIGNAL_LOCK ();
3120 node = LOOKUP_SIGNAL_NODE (signal_id);
3121 if (!node || !g_type_is_a (G_TYPE_FROM_INSTANCE (instance), node->itype))
3122 {
3123 g_warning ("%s: signal id '%u' is invalid for instance '%p'", G_STRLOC, signal_id, instance);
3124 SIGNAL_UNLOCK ();
3125 return;
3126 }
3127 #ifndef G_DISABLE_CHECKS
3128 if (detail && !(node->flags & G_SIGNAL_DETAILED))
3129 {
3130 g_warning ("%s: signal id '%u' does not support detail (%u)", G_STRLOC, signal_id, detail);
3131 SIGNAL_UNLOCK ();
3132 return;
3133 }
3134 #endif /* !G_DISABLE_CHECKS */
3135
3136 if (!node->single_va_closure_is_valid)
3137 node_update_single_va_closure (node);
3138
3139 if (node->single_va_closure != NULL)
3140 {
3141 HandlerList* hlist = handler_list_lookup (node->signal_id, instance);
3142 Handler *fastpath_handler = NULL;
3143 Handler *l;
3144 GClosure *closure = NULL;
3145 gboolean fastpath = TRUE;
3146 GSignalFlags run_type = G_SIGNAL_RUN_FIRST;
3147
3148 if (node->single_va_closure != SINGLE_VA_CLOSURE_EMPTY_MAGIC &&
3149 !_g_closure_is_void (node->single_va_closure, instance))
3150 {
3151 if (_g_closure_supports_invoke_va (node->single_va_closure))
3152 {
3153 closure = node->single_va_closure;
3154 if (node->single_va_closure_is_after)
3155 run_type = G_SIGNAL_RUN_LAST;
3156 else
3157 run_type = G_SIGNAL_RUN_FIRST;
3158 }
3159 else
3160 fastpath = FALSE;
3161 }
3162
3163 for (l = hlist ? hlist->handlers : NULL; fastpath && l != NULL; l = l->next)
3164 {
3165 if (!l->block_count &&
3166 (!l->detail || l->detail == detail))
3167 {
3168 if (closure != NULL || !_g_closure_supports_invoke_va (l->closure))
3169 {
3170 fastpath = FALSE;
3171 break;
3172 }
3173 else
3174 {
3175 fastpath_handler = l;
3176 closure = l->closure;
3177 if (l->after)
3178 run_type = G_SIGNAL_RUN_LAST;
3179 else
3180 run_type = G_SIGNAL_RUN_FIRST;
3181 }
3182 }
3183 }
3184
3185 if (fastpath && closure == NULL && node->return_type == G_TYPE_NONE)
3186 {
3187 SIGNAL_UNLOCK ();
3188 return;
3189 }
3190
3191 /* Don't allow no-recurse emission as we might have to restart, which means
3192 we will run multiple handlers and thus must ref all arguments */
3193 if (closure != NULL && (node->flags & (G_SIGNAL_NO_RECURSE)) != 0)
3194 fastpath = FALSE;
3195
3196 if (fastpath)
3197 {
3198 SignalAccumulator *accumulator;
3199 Emission emission;
3200 GValue *return_accu, accu = G_VALUE_INIT;
3201 guint signal_id;
3202 GType instance_type = G_TYPE_FROM_INSTANCE (instance);
3203 GValue emission_return = G_VALUE_INIT;
3204 GType rtype = node->return_type & ~G_SIGNAL_TYPE_STATIC_SCOPE;
3205 gboolean static_scope = node->return_type & G_SIGNAL_TYPE_STATIC_SCOPE;
3206
3207 signal_id = node->signal_id;
3208 accumulator = node->accumulator;
3209 if (rtype == G_TYPE_NONE)
3210 return_accu = NULL;
3211 else if (accumulator)
3212 return_accu = &accu;
3213 else
3214 return_accu = &emission_return;
3215
3216 emission.instance = instance;
3217 emission.ihint.signal_id = signal_id;
3218 emission.ihint.detail = detail;
3219 emission.ihint.run_type = run_type;
3220 emission.state = EMISSION_RUN;
3221 emission.chain_type = instance_type;
3222 emission_push (&g_recursive_emissions, &emission);
3223
3224 if (fastpath_handler)
3225 handler_ref (fastpath_handler);
3226
3227 SIGNAL_UNLOCK ();
3228
3229 TRACE(GOBJECT_SIGNAL_EMIT(signal_id, detail, instance, instance_type));
3230
3231 if (rtype != G_TYPE_NONE)
3232 g_value_init (&emission_return, rtype);
3233
3234 if (accumulator)
3235 g_value_init (&accu, rtype);
3236
3237 if (closure != NULL)
3238 {
3239 g_object_ref (instance);
3240 _g_closure_invoke_va (closure,
3241 return_accu,
3242 instance,
3243 var_args,
3244 node->n_params,
3245 node->param_types);
3246 accumulate (&emission.ihint, &emission_return, &accu, accumulator);
3247 }
3248
3249 SIGNAL_LOCK ();
3250
3251 emission.chain_type = G_TYPE_NONE;
3252 emission_pop (&g_recursive_emissions, &emission);
3253
3254 if (fastpath_handler)
3255 handler_unref_R (signal_id, instance, fastpath_handler);
3256
3257 SIGNAL_UNLOCK ();
3258
3259 if (accumulator)
3260 g_value_unset (&accu);
3261
3262 if (rtype != G_TYPE_NONE)
3263 {
3264 gchar *error = NULL;
3265 for (i = 0; i < node->n_params; i++)
3266 {
3267 GType ptype = node->param_types[i] & ~G_SIGNAL_TYPE_STATIC_SCOPE;
3268 G_VALUE_COLLECT_SKIP (ptype, var_args);
3269 }
3270
3271 G_VALUE_LCOPY (&emission_return,
3272 var_args,
3273 static_scope ? G_VALUE_NOCOPY_CONTENTS : 0,
3274 &error);
3275 if (!error)
3276 g_value_unset (&emission_return);
3277 else
3278 {
3279 g_warning ("%s: %s", G_STRLOC, error);
3280 g_free (error);
3281 /* we purposely leak the value here, it might not be
3282 * in a sane state if an error condition occurred
3283 */
3284 }
3285 }
3286
3287 TRACE(GOBJECT_SIGNAL_EMIT_END(signal_id, detail, instance, instance_type));
3288
3289 if (closure != NULL)
3290 g_object_unref (instance);
3291
3292 return;
3293 }
3294 }
3295 SIGNAL_UNLOCK ();
3296
3297 n_params = node->n_params;
3298 signal_return_type = node->return_type;
3299 instance_and_params = g_alloca (sizeof (GValue) * (n_params + 1));
3300 memset (instance_and_params, 0, sizeof (GValue) * (n_params + 1));
3301 param_values = instance_and_params + 1;
3302
3303 for (i = 0; i < node->n_params; i++)
3304 {
3305 gchar *error;
3306 GType ptype = node->param_types[i] & ~G_SIGNAL_TYPE_STATIC_SCOPE;
3307 gboolean static_scope = node->param_types[i] & G_SIGNAL_TYPE_STATIC_SCOPE;
3308
3309 G_VALUE_COLLECT_INIT (param_values + i, ptype,
3310 var_args,
3311 static_scope ? G_VALUE_NOCOPY_CONTENTS : 0,
3312 &error);
3313 if (error)
3314 {
3315 g_warning ("%s: %s", G_STRLOC, error);
3316 g_free (error);
3317
3318 /* we purposely leak the value here, it might not be
3319 * in a sane state if an error condition occoured
3320 */
3321 while (i--)
3322 g_value_unset (param_values + i);
3323
3324 return;
3325 }
3326 }
3327
3328 instance_and_params->g_type = 0;
3329 g_value_init_from_instance (instance_and_params, instance);
3330 if (signal_return_type == G_TYPE_NONE)
3331 signal_emit_unlocked_R (node, detail, instance, NULL, instance_and_params);
3332 else
3333 {
3334 GValue return_value = G_VALUE_INIT;
3335 gchar *error = NULL;
3336 GType rtype = signal_return_type & ~G_SIGNAL_TYPE_STATIC_SCOPE;
3337 gboolean static_scope = signal_return_type & G_SIGNAL_TYPE_STATIC_SCOPE;
3338
3339 g_value_init (&return_value, rtype);
3340
3341 signal_emit_unlocked_R (node, detail, instance, &return_value, instance_and_params);
3342
3343 G_VALUE_LCOPY (&return_value,
3344 var_args,
3345 static_scope ? G_VALUE_NOCOPY_CONTENTS : 0,
3346 &error);
3347 if (!error)
3348 g_value_unset (&return_value);
3349 else
3350 {
3351 g_warning ("%s: %s", G_STRLOC, error);
3352 g_free (error);
3353
3354 /* we purposely leak the value here, it might not be
3355 * in a sane state if an error condition occurred
3356 */
3357 }
3358 }
3359 for (i = 0; i < n_params; i++)
3360 g_value_unset (param_values + i);
3361 g_value_unset (instance_and_params);
3362 }
3363
3364 /**
3365 * g_signal_emit:
3366 * @instance: (type GObject.Object): the instance the signal is being emitted on.
3367 * @signal_id: the signal id
3368 * @detail: the detail
3369 * @...: parameters to be passed to the signal, followed by a
3370 * location for the return value. If the return type of the signal
3371 * is #G_TYPE_NONE, the return value location can be omitted.
3372 *
3373 * Emits a signal.
3374 *
3375 * Note that g_signal_emit() resets the return value to the default
3376 * if no handlers are connected, in contrast to g_signal_emitv().
3377 */
3378 void
3379 g_signal_emit (gpointer instance,
3380 guint signal_id,
3381 GQuark detail,
3382 ...)
3383 {
3384 va_list var_args;
3385
3386 va_start (var_args, detail);
3387 g_signal_emit_valist (instance, signal_id, detail, var_args);
3388 va_end (var_args);
3389 }
3390
3391 /**
3392 * g_signal_emit_by_name:
3393 * @instance: (type GObject.Object): the instance the signal is being emitted on.
3394 * @detailed_signal: a string of the form "signal-name::detail".
3395 * @...: parameters to be passed to the signal, followed by a
3396 * location for the return value. If the return type of the signal
3397 * is #G_TYPE_NONE, the return value location can be omitted.
3398 *
3399 * Emits a signal.
3400 *
3401 * Note that g_signal_emit_by_name() resets the return value to the default
3402 * if no handlers are connected, in contrast to g_signal_emitv().
3403 */
3404 void
3405 g_signal_emit_by_name (gpointer instance,
3406 const gchar *detailed_signal,
3407 ...)
3408 {
3409 GQuark detail = 0;
3410 guint signal_id;
3411 GType itype;
3412
3413 g_return_if_fail (G_TYPE_CHECK_INSTANCE (instance));
3414 g_return_if_fail (detailed_signal != NULL);
3415
3416 itype = G_TYPE_FROM_INSTANCE (instance);
3417
3418 SIGNAL_LOCK ();
3419 signal_id = signal_parse_name (detailed_signal, itype, &detail, TRUE);
3420 SIGNAL_UNLOCK ();
3421
3422 if (signal_id)
3423 {
3424 va_list var_args;
3425
3426 va_start (var_args, detailed_signal);
3427 g_signal_emit_valist (instance, signal_id, detail, var_args);
3428 va_end (var_args);
3429 }
3430 else
3431 g_warning ("%s: signal name '%s' is invalid for instance '%p' of type '%s'",
3432 G_STRLOC, detailed_signal, instance, g_type_name (itype));
3433 }
3434
3435 static gboolean
3436 signal_emit_unlocked_R (SignalNode *node,
3437 GQuark detail,
3438 gpointer instance,
3439 GValue *emission_return,
3440 const GValue *instance_and_params)
3441 {
3442 SignalAccumulator *accumulator;
3443 Emission emission;
3444 GClosure *class_closure;
3445 HandlerList *hlist;
3446 Handler *handler_list = NULL;
3447 GValue *return_accu, accu = G_VALUE_INIT;
3448 guint signal_id;
3449 gulong max_sequential_handler_number;
3450 gboolean return_value_altered = FALSE;
3451
3452 TRACE(GOBJECT_SIGNAL_EMIT(node->signal_id, detail, instance, G_TYPE_FROM_INSTANCE (instance)));
3453
3454 SIGNAL_LOCK ();
3455 signal_id = node->signal_id;
3456
3457 if (node->flags & G_SIGNAL_NO_RECURSE)
3458 {
3459 Emission *node = emission_find (g_restart_emissions, signal_id, detail, instance);
3460
3461 if (node)
3462 {
3463 node->state = EMISSION_RESTART;
3464 SIGNAL_UNLOCK ();
3465 return return_value_altered;
3466 }
3467 }
3468 accumulator = node->accumulator;
3469 if (accumulator)
3470 {
3471 SIGNAL_UNLOCK ();
3472 g_value_init (&accu, node->return_type & ~G_SIGNAL_TYPE_STATIC_SCOPE);
3473 return_accu = &accu;
3474 SIGNAL_LOCK ();
3475 }
3476 else
3477 return_accu = emission_return;
3478 emission.instance = instance;
3479 emission.ihint.signal_id = node->signal_id;
3480 emission.ihint.detail = detail;
3481 emission.ihint.run_type = 0;
3482 emission.state = 0;
3483 emission.chain_type = G_TYPE_NONE;
3484 emission_push ((node->flags & G_SIGNAL_NO_RECURSE) ? &g_restart_emissions : &g_recursive_emissions, &emission);
3485 class_closure = signal_lookup_closure (node, instance);
3486
3487 EMIT_RESTART:
3488
3489 if (handler_list)
3490 handler_unref_R (signal_id, instance, handler_list);
3491 max_sequential_handler_number = g_handler_sequential_number;
3492 hlist = handler_list_lookup (signal_id, instance);
3493 handler_list = hlist ? hlist->handlers : NULL;
3494 if (handler_list)
3495 handler_ref (handler_list);
3496
3497 emission.ihint.run_type = G_SIGNAL_RUN_FIRST;
3498
3499 if ((node->flags & G_SIGNAL_RUN_FIRST) && class_closure)
3500 {
3501 emission.state = EMISSION_RUN;
3502
3503 emission.chain_type = G_TYPE_FROM_INSTANCE (instance);
3504 SIGNAL_UNLOCK ();
3505 g_closure_invoke (class_closure,
3506 return_accu,
3507 node->n_params + 1,
3508 instance_and_params,
3509 &emission.ihint);
3510 if (!accumulate (&emission.ihint, emission_return, &accu, accumulator) &&
3511 emission.state == EMISSION_RUN)
3512 emission.state = EMISSION_STOP;
3513 SIGNAL_LOCK ();
3514 emission.chain_type = G_TYPE_NONE;
3515 return_value_altered = TRUE;
3516
3517 if (emission.state == EMISSION_STOP)
3518 goto EMIT_CLEANUP;
3519 else if (emission.state == EMISSION_RESTART)
3520 goto EMIT_RESTART;
3521 }
3522
3523 if (node->emission_hooks)
3524 {
3525 gboolean need_destroy, was_in_call, may_recurse = TRUE;
3526 GHook *hook;
3527
3528 emission.state = EMISSION_HOOK;
3529 hook = g_hook_first_valid (node->emission_hooks, may_recurse);
3530 while (hook)
3531 {
3532 SignalHook *signal_hook = SIGNAL_HOOK (hook);
3533
3534 if (!signal_hook->detail || signal_hook->detail == detail)
3535 {
3536 GSignalEmissionHook hook_func = (GSignalEmissionHook) hook->func;
3537
3538 was_in_call = G_HOOK_IN_CALL (hook);
3539 hook->flags |= G_HOOK_FLAG_IN_CALL;
3540 SIGNAL_UNLOCK ();
3541 need_destroy = !hook_func (&emission.ihint, node->n_params + 1, instance_and_params, hook->data);
3542 SIGNAL_LOCK ();
3543 if (!was_in_call)
3544 hook->flags &= ~G_HOOK_FLAG_IN_CALL;
3545 if (need_destroy)
3546 g_hook_destroy_link (node->emission_hooks, hook);
3547 }
3548 hook = g_hook_next_valid (node->emission_hooks, hook, may_recurse);
3549 }
3550
3551 if (emission.state == EMISSION_RESTART)
3552 goto EMIT_RESTART;
3553 }
3554
3555 if (handler_list)
3556 {
3557 Handler *handler = handler_list;
3558
3559 emission.state = EMISSION_RUN;
3560 handler_ref (handler);
3561 do
3562 {
3563 Handler *tmp;
3564
3565 if (handler->after)
3566 {
3567 handler_unref_R (signal_id, instance, handler_list);
3568 handler_list = handler;
3569 break;
3570 }
3571 else if (!handler->block_count && (!handler->detail || handler->detail == detail) &&
3572 handler->sequential_number < max_sequential_handler_number)
3573 {
3574 SIGNAL_UNLOCK ();
3575 g_closure_invoke (handler->closure,
3576 return_accu,
3577 node->n_params + 1,
3578 instance_and_params,
3579 &emission.ihint);
3580 if (!accumulate (&emission.ihint, emission_return, &accu, accumulator) &&
3581 emission.state == EMISSION_RUN)
3582 emission.state = EMISSION_STOP;
3583 SIGNAL_LOCK ();
3584 return_value_altered = TRUE;
3585
3586 tmp = emission.state == EMISSION_RUN ? handler->next : NULL;
3587 }
3588 else
3589 tmp = handler->next;
3590
3591 if (tmp)
3592 handler_ref (tmp);
3593 handler_unref_R (signal_id, instance, handler_list);
3594 handler_list = handler;
3595 handler = tmp;
3596 }
3597 while (handler);
3598
3599 if (emission.state == EMISSION_STOP)
3600 goto EMIT_CLEANUP;
3601 else if (emission.state == EMISSION_RESTART)
3602 goto EMIT_RESTART;
3603 }
3604
3605 emission.ihint.run_type = G_SIGNAL_RUN_LAST;
3606
3607 if ((node->flags & G_SIGNAL_RUN_LAST) && class_closure)
3608 {
3609 emission.state = EMISSION_RUN;
3610
3611 emission.chain_type = G_TYPE_FROM_INSTANCE (instance);
3612 SIGNAL_UNLOCK ();
3613 g_closure_invoke (class_closure,
3614 return_accu,
3615 node->n_params + 1,
3616 instance_and_params,
3617 &emission.ihint);
3618 if (!accumulate (&emission.ihint, emission_return, &accu, accumulator) &&
3619 emission.state == EMISSION_RUN)
3620 emission.state = EMISSION_STOP;
3621 SIGNAL_LOCK ();
3622 emission.chain_type = G_TYPE_NONE;
3623 return_value_altered = TRUE;
3624
3625 if (emission.state == EMISSION_STOP)
3626 goto EMIT_CLEANUP;
3627 else if (emission.state == EMISSION_RESTART)
3628 goto EMIT_RESTART;
3629 }
3630
3631 if (handler_list)
3632 {
3633 Handler *handler = handler_list;
3634
3635 emission.state = EMISSION_RUN;
3636 handler_ref (handler);
3637 do
3638 {
3639 Handler *tmp;
3640
3641 if (handler->after && !handler->block_count && (!handler->detail || handler->detail == detail) &&
3642 handler->sequential_number < max_sequential_handler_number)
3643 {
3644 SIGNAL_UNLOCK ();
3645 g_closure_invoke (handler->closure,
3646 return_accu,
3647 node->n_params + 1,
3648 instance_and_params,
3649 &emission.ihint);
3650 if (!accumulate (&emission.ihint, emission_return, &accu, accumulator) &&
3651 emission.state == EMISSION_RUN)
3652 emission.state = EMISSION_STOP;
3653 SIGNAL_LOCK ();
3654 return_value_altered = TRUE;
3655
3656 tmp = emission.state == EMISSION_RUN ? handler->next : NULL;
3657 }
3658 else
3659 tmp = handler->next;
3660
3661 if (tmp)
3662 handler_ref (tmp);
3663 handler_unref_R (signal_id, instance, handler);
3664 handler = tmp;
3665 }
3666 while (handler);
3667
3668 if (emission.state == EMISSION_STOP)
3669 goto EMIT_CLEANUP;
3670 else if (emission.state == EMISSION_RESTART)
3671 goto EMIT_RESTART;
3672 }
3673
3674 EMIT_CLEANUP:
3675
3676 emission.ihint.run_type = G_SIGNAL_RUN_CLEANUP;
3677
3678 if ((node->flags & G_SIGNAL_RUN_CLEANUP) && class_closure)
3679 {
3680 gboolean need_unset = FALSE;
3681
3682 emission.state = EMISSION_STOP;
3683
3684 emission.chain_type = G_TYPE_FROM_INSTANCE (instance);
3685 SIGNAL_UNLOCK ();
3686 if (node->return_type != G_TYPE_NONE && !accumulator)
3687 {
3688 g_value_init (&accu, node->return_type & ~G_SIGNAL_TYPE_STATIC_SCOPE);
3689 need_unset = TRUE;
3690 }
3691 g_closure_invoke (class_closure,
3692 node->return_type != G_TYPE_NONE ? &accu : NULL,
3693 node->n_params + 1,
3694 instance_and_params,
3695 &emission.ihint);
3696 if (need_unset)
3697 g_value_unset (&accu);
3698 SIGNAL_LOCK ();
3699 emission.chain_type = G_TYPE_NONE;
3700
3701 if (emission.state == EMISSION_RESTART)
3702 goto EMIT_RESTART;
3703 }
3704
3705 if (handler_list)
3706 handler_unref_R (signal_id, instance, handler_list);
3707
3708 emission_pop ((node->flags & G_SIGNAL_NO_RECURSE) ? &g_restart_emissions : &g_recursive_emissions, &emission);
3709 SIGNAL_UNLOCK ();
3710 if (accumulator)
3711 g_value_unset (&accu);
3712
3713 TRACE(GOBJECT_SIGNAL_EMIT_END(node->signal_id, detail, instance, G_TYPE_FROM_INSTANCE (instance)));
3714
3715 return return_value_altered;
3716 }
3717
3718 static void
3719 add_invalid_closure_notify (Handler *handler,
3720 gpointer instance)
3721 {
3722 g_closure_add_invalidate_notifier (handler->closure, instance, invalid_closure_notify);
3723 handler->has_invalid_closure_notify = 1;
3724 }
3725
3726 static void
3727 remove_invalid_closure_notify (Handler *handler,
3728 gpointer instance)
3729 {
3730 if (handler->has_invalid_closure_notify)
3731 {
3732 g_closure_remove_invalidate_notifier (handler->closure, instance, invalid_closure_notify);
3733 handler->has_invalid_closure_notify = 0;
3734 }
3735 }
3736
3737 static void
3738 invalid_closure_notify (gpointer instance,
3739 GClosure *closure)
3740 {
3741 Handler *handler;
3742 guint signal_id;
3743
3744 SIGNAL_LOCK ();
3745
3746 handler = handler_lookup (instance, 0, closure, &signal_id);
3747 g_assert (handler->closure == closure);
3748
3749 handler->sequential_number = 0;
3750 handler->block_count = 1;
3751 handler_unref_R (signal_id, instance, handler);
3752
3753 SIGNAL_UNLOCK ();
3754 }
3755
3756 static const gchar*
3757 type_debug_name (GType type)
3758 {
3759 if (type)
3760 {
3761 const char *name = g_type_name (type & ~G_SIGNAL_TYPE_STATIC_SCOPE);
3762 return name ? name : "<unknown>";
3763 }
3764 else
3765 return "<invalid>";
3766 }
3767
3768 /**
3769 * g_signal_accumulator_true_handled:
3770 * @ihint: standard #GSignalAccumulator parameter
3771 * @return_accu: standard #GSignalAccumulator parameter
3772 * @handler_return: standard #GSignalAccumulator parameter
3773 * @dummy: standard #GSignalAccumulator parameter
3774 *
3775 * A predefined #GSignalAccumulator for signals that return a
3776 * boolean values. The behavior that this accumulator gives is
3777 * that a return of %TRUE stops the signal emission: no further
3778 * callbacks will be invoked, while a return of %FALSE allows
3779 * the emission to continue. The idea here is that a %TRUE return
3780 * indicates that the callback handled the signal, and no further
3781 * handling is needed.
3782 *
3783 * Since: 2.4
3784 *
3785 * Returns: standard #GSignalAccumulator result
3786 */
3787 gboolean
3788 g_signal_accumulator_true_handled (GSignalInvocationHint *ihint,
3789 GValue *return_accu,
3790 const GValue *handler_return,
3791 gpointer dummy)
3792 {
3793 gboolean continue_emission;
3794 gboolean signal_handled;
3795
3796 signal_handled = g_value_get_boolean (handler_return);
3797 g_value_set_boolean (return_accu, signal_handled);
3798 continue_emission = !signal_handled;
3799
3800 return continue_emission;
3801 }
3802
3803 /**
3804 * g_signal_accumulator_first_wins:
3805 * @ihint: standard #GSignalAccumulator parameter
3806 * @return_accu: standard #GSignalAccumulator parameter
3807 * @handler_return: standard #GSignalAccumulator parameter
3808 * @dummy: standard #GSignalAccumulator parameter
3809 *
3810 * A predefined #GSignalAccumulator for signals intended to be used as a
3811 * hook for application code to provide a particular value. Usually
3812 * only one such value is desired and multiple handlers for the same
3813 * signal don't make much sense (except for the case of the default
3814 * handler defined in the class structure, in which case you will
3815 * usually want the signal connection to override the class handler).
3816 *
3817 * This accumulator will use the return value from the first signal
3818 * handler that is run as the return value for the signal and not run
3819 * any further handlers (ie: the first handler "wins").
3820 *
3821 * Returns: standard #GSignalAccumulator result
3822 *
3823 * Since: 2.28
3824 **/
3825 gboolean
3826 g_signal_accumulator_first_wins (GSignalInvocationHint *ihint,
3827 GValue *return_accu,
3828 const GValue *handler_return,
3829 gpointer dummy)
3830 {
3831 g_value_copy (handler_return, return_accu);
3832 return FALSE;
3833 }