* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General
- * Public License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
- * Boston, MA 02111-1307, USA.
+ * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
*
* this code is based on the original GtkSignal implementation
* for the Gtk+ library by Peter Mattis <petm@xcf.berkeley.edu>
* and a general purpose notification mechanism
* @title: Signals
*
- * The basic concept of the signal system is that of the
- * <emphasis>emission</emphasis> of a signal. Signals are introduced
- * per-type and are identified through strings. Signals introduced
- * for a parent type are available in derived types as well, so
- * basically they are a per-type facility that is inherited. A signal
- * emission mainly involves invocation of a certain set of callbacks
- * in precisely defined manner. There are two main categories of such
- * callbacks, per-object
- * <footnote><para>Although signals can deal with any kind of instantiatable
- * type, i'm referring to those types as "object types" in the following,
- * simply because that is the context most users will encounter signals in.
- * </para></footnote>
- * ones and user provided ones.
+ * The basic concept of the signal system is that of the emission
+ * of a signal. Signals are introduced per-type and are identified
+ * through strings. Signals introduced for a parent type are available
+ * in derived types as well, so basically they are a per-type facility
+ * that is inherited.
+ *
+ * A signal emission mainly involves invocation of a certain set of
+ * callbacks in precisely defined manner. There are two main categories
+ * of such callbacks, per-object ones and user provided ones.
+ * (Although signals can deal with any kind of instantiatable type, I'm
+ * referring to those types as "object types" in the following, simply
+ * because that is the context most users will encounter signals in.)
* The per-object callbacks are most often referred to as "object method
* handler" or "default (signal) handler", while user provided callbacks are
* usually just called "signal handler".
+ *
* The object method handler is provided at signal creation time (this most
* frequently happens at the end of an object class' creation), while user
- * provided handlers are frequently connected and disconnected to/from a certain
- * signal on certain object instances.
+ * provided handlers are frequently connected and disconnected to/from a
+ * certain signal on certain object instances.
*
* A signal emission consists of five stages, unless prematurely stopped:
- * <variablelist>
- * <varlistentry><term></term><listitem><para>
- * 1 - Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * 2 - Invocation of normal user-provided signal handlers (<emphasis>after</emphasis> flag %FALSE)
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * 3 - Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * 4 - Invocation of user provided signal handlers, connected with an <emphasis>after</emphasis> flag of %TRUE
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * 5 - Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals
- * </para></listitem></varlistentry>
- * </variablelist>
+ *
+ * 1. Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals
+ *
+ * 2. Invocation of normal user-provided signal handlers (where the @after
+ * flag is not set)
+ *
+ * 3. Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals
+ *
+ * 4. Invocation of user provided signal handlers (where the @after flag is set)
+ *
+ * 5. Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals
+
* The user-provided signal handlers are called in the order they were
* connected in.
+ *
* All handlers may prematurely stop a signal emission, and any number of
* handlers may be connected, disconnected, blocked or unblocked during
* a signal emission.
+ *
* There are certain criteria for skipping user handlers in stages 2 and 4
* of a signal emission.
- * First, user handlers may be <emphasis>blocked</emphasis>, blocked handlers are omitted
- * during callback invocation, to return from the "blocked" state, a
- * handler has to get unblocked exactly the same amount of times
- * it has been blocked before.
+ *
+ * First, user handlers may be blocked. Blocked handlers are omitted during
+ * callback invocation, to return from the blocked state, a handler has to
+ * get unblocked exactly the same amount of times it has been blocked before.
+ *
* Second, upon emission of a %G_SIGNAL_DETAILED signal, an additional
- * "detail" argument passed in to g_signal_emit() has to match the detail
+ * @detail argument passed in to g_signal_emit() has to match the detail
* argument of the signal handler currently subject to invocation.
* Specification of no detail argument for signal handlers (omission of the
* detail part of the signal specification upon connection) serves as a
#define REPORT_BUG "please report occurrence circumstances to gtk-devel-list@gnome.org"
-#ifdef G_ENABLE_DEBUG
-#define COND_DEBUG(debug_type, cond) ((_g_type_debug_flags & G_TYPE_DEBUG_ ## debug_type) || (cond))
-#define IF_DEBUG(debug_type, cond) if (COND_DEBUG(debug_type, cond))
-
-static volatile gpointer g_trace_instance_signals = NULL;
-static volatile gpointer g_trap_instance_signals = NULL;
-#endif /* G_ENABLE_DEBUG */
-
/* --- typedefs --- */
typedef struct _SignalNode SignalNode;
* be used, but they cannot be mixed.
*
* If 0 is used for @class_offset subclasses cannot override the class handler
- * in their <code>class_init</code> method by doing
- * <code>super_class->signal_handler = my_signal_handler</code>. Instead they
- * will have to use g_signal_override_class_handler().
+ * in their class_init method by doing super_class->signal_handler = my_signal_handler.
+ * Instead they will have to use g_signal_override_class_handler().
*
* If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as
* the marshaller for this signal.
*
* See g_signal_new() for information about signal names.
*
- * If c_marshaller is %NULL @g_cclosure_marshal_generic will be used as
+ * If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as
* the marshaller for this signal.
*
* Returns: the signal id
*
* See g_signal_new() for details on allowed signal names.
*
- * If c_marshaller is %NULL @g_cclosure_marshal_generic will be used as
+ * If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as
* the marshaller for this signal.
*
* Returns: the signal id
*
* Connects a closure to a signal for a particular object.
*
- * Returns: the handler id
+ * Returns: the handler id (always greater than 0 for successful connections)
*/
gulong
g_signal_connect_closure_by_id (gpointer instance,
*
* Connects a closure to a signal for a particular object.
*
- * Returns: the handler id
+ * Returns: the handler id (always greater than 0 for successful connections)
*/
gulong
g_signal_connect_closure (gpointer instance,
* Connects a #GCallback function to a signal for a particular object. Similar
* to g_signal_connect(), but allows to provide a #GClosureNotify for the data
* which will be called when the signal handler is disconnected and no longer
- * used. Specify @connect_flags if you need <literal>..._after()</literal> or
- * <literal>..._swapped()</literal> variants of this function.
+ * used. Specify @connect_flags if you need `..._after()` or
+ * `..._swapped()` variants of this function.
*
- * Returns: the handler id
+ * Returns: the handler id (always greater than 0 for successful connections)
*/
gulong
g_signal_connect_data (gpointer instance,
return connected;
}
+/**
+ * g_signal_handlers_destroy:
+ * @instance: (type GObject.Object): The instance whose signal handlers are destroyed
+ *
+ * Destroy all signal handlers of a type instance. This function is
+ * an implementation detail of the #GObject dispose implementation,
+ * and should not be used outside of the type system.
+ */
void
g_signal_handlers_destroy (gpointer instance)
{
if (node->single_va_closure != NULL &&
(node->single_va_closure == SINGLE_VA_CLOSURE_EMPTY_MAGIC ||
- _g_closure_is_void (node->single_va_closure, instance))
-#ifdef G_ENABLE_DEBUG
- && !COND_DEBUG (SIGNALS, g_trace_instance_signals != instance &&
- g_trap_instance_signals == instance)
-#endif /* G_ENABLE_DEBUG */
- )
+ _g_closure_is_void (node->single_va_closure, instance)))
{
HandlerList* hlist = handler_list_lookup (node->signal_id, instance);
if (hlist == NULL || hlist->handlers == NULL)
if (!node->single_va_closure_is_valid)
node_update_single_va_closure (node);
- if (node->single_va_closure != NULL
-#ifdef G_ENABLE_DEBUG
- && !COND_DEBUG (SIGNALS, g_trace_instance_signals != instance &&
- g_trap_instance_signals == instance)
-#endif /* G_ENABLE_DEBUG */
- )
+ if (node->single_va_closure != NULL)
{
HandlerList* hlist = handler_list_lookup (node->signal_id, instance);
Handler *fastpath_handler = NULL;
gulong max_sequential_handler_number;
gboolean return_value_altered = FALSE;
-#ifdef G_ENABLE_DEBUG
- IF_DEBUG (SIGNALS, g_trace_instance_signals == instance || g_trap_instance_signals == instance)
- {
- g_message ("%s::%s(%u) emitted (instance=%p, signal-node=%p)",
- g_type_name (G_TYPE_FROM_INSTANCE (instance)),
- node->name, detail,
- instance, node);
- if (g_trap_instance_signals == instance)
- G_BREAKPOINT ();
- }
-#endif /* G_ENABLE_DEBUG */
-
TRACE(GOBJECT_SIGNAL_EMIT(node->signal_id, detail, instance, G_TYPE_FROM_INSTANCE (instance)));
SIGNAL_LOCK ();
* that a return of %TRUE stops the signal emission: no further
* callbacks will be invoked, while a return of %FALSE allows
* the emission to continue. The idea here is that a %TRUE return
- * indicates that the callback <emphasis>handled</emphasis> the signal,
- * and no further handling is needed.
+ * indicates that the callback handled the signal, and no further
+ * handling is needed.
*
* Since: 2.4
*
projects / platform / upstream / glib.git / blobdiff