.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Glib::Signal 3pm"
.TH Glib::Signal 3pm 2024-01-10 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Glib::Signal \-  Object customization and general purpose notification
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This page describes some functions related to signals in Glib.  Since most
things you can do with signals are tied to Glib::Object instances, the
majority of the signal functions are documented there.
.SS "Thread safety"
.IX Subsection "Thread safety"
Some libraries, most notably GStreamer, sometimes invoke signal handlers from a
foreign thread that has no Perl interpreter associated with it.  When this
happens, we have no choice but to hand the marshalling over to the main loop
which in turn later wakes up the main thread and lets it handle the request.
We cannot invoke the signal handler from the foreign thread since the Perl
interpreter may not be used concurrently.
.PP
The downside to this approach is that the foreign thread is blocked until the
main thread has finished executing the signal handler.  This might lead to
deadlocks.  It might help in this case to wrap the crucial parts of the signal
handler inside a Glib::Idle callback so that the signal handler can return
directly.
.SH METHODS
.IX Header "METHODS"
.ie n .SS "integer = Glib\->\fBinstall_exception_handler\fP ($func, $data=undef)"
.el .SS "integer = Glib\->\fBinstall_exception_handler\fP ($func, \f(CW$data\fP=undef)"
.IX Subsection "integer = Glib->install_exception_handler ($func, $data=undef)"
.IP \(bu 4
\&\f(CW$func\fR (subroutine)
.IP \(bu 4
\&\f(CW$data\fR (scalar)
.PP
Install a subroutine to be executed when a signal emission traps an exception
(a croak or die).  \fR\f(CI$func\fR\fI\fR should return boolean (true if the handler should
remain installed) and expect to receive a single scalar.  This scalar will be a
private copy of $@ which the handler can mangle to its heart's content.
.PP
Returns an identifier that may be used with \f(CW\*(C`remove_exception_handler\*(C'\fR.
.PP
See \f(CWgperl_install_exception_handler()\fR in Glib::xsapi.
.SS "Glib\->\fBremove_exception_handler\fP ($tag)"
.IX Subsection "Glib->remove_exception_handler ($tag)"
.IP \(bu 4
\&\f(CW$tag\fR (integer)
.PP
Remove the exception handler identified by \fR\f(CI$tag\fR\fI\fR, as returned by
\&\f(CW\*(C`install_exception_handler\*(C'\fR.  If \fI\fR\f(CI$tag\fR\fI\fR cannot be found, this
does nothing.
.PP
WARNING:  Do not call this function from within an exception handler.
If you want to remove your handler during its execution just have it
return false.
.PP
See \f(CWgperl_remove_exception_handler()\fR in Glib::xsapi.
.SH "ENUMS AND FLAGS"
.IX Header "ENUMS AND FLAGS"
.SS "flags Glib::SignalFlags"
.IX Subsection "flags Glib::SignalFlags"
.IP \(bu 4
\&'run\-first' / 'G_SIGNAL_RUN_FIRST'
.IP \(bu 4
\&'run\-last' / 'G_SIGNAL_RUN_LAST'
.IP \(bu 4
\&'run\-cleanup' / 'G_SIGNAL_RUN_CLEANUP'
.IP \(bu 4
\&'no\-recurse' / 'G_SIGNAL_NO_RECURSE'
.IP \(bu 4
\&'detailed' / 'G_SIGNAL_DETAILED'
.IP \(bu 4
\&'action' / 'G_SIGNAL_ACTION'
.IP \(bu 4
\&'no\-hooks' / 'G_SIGNAL_NO_HOOKS'
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Glib, Glib::Object
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (C) 2003\-2011 by the gtk2\-perl team.
.PP
This software is licensed under the LGPL.  See Glib for a full notice.