.\" -*- 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::MainLoop 3pm"
.TH Glib::MainLoop 3pm 2024-03-07 "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::MainLoop \-  An event source manager
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Event-driven programs need some sort of loop which watches for events and
launches the appropriate actions.  Glib::MainLoop provides this functionality.
.PP
Mainloops have context, provided by the MainContext object.  For the most part
you can use the default context (see \f(CW\*(C`default\*(C'\fR), but if you want to create a
subcontext for a nested loop which doesn't have the same event sources, etc,
you can.
.PP
Event sources, attached to main contexts, watch for events to happen, and
launch appropriate actions.  Glib provides a few ready-made event sources,
the Glib::Timeout, Glib::Idle, and io watch (\f(CW\*(C`Glib::IO\->add_watch\*(C'\fR).
.PP
Under the hood, Gtk+ adds event sources for GdkEvents to dispatch events to
your widgets.  In fact, Gtk2 provides an abstraction of Glib::MainLoop (See
\&\f(CW\*(C`Gtk2\->main\*(C'\fR and friends), so you may rarely have cause to use
Glib::MainLoop directly.
.PP
Note: As of version 1.080, the Glib module uses a custom event source to
ensure that perl's safe signal handling and the glib polling event loop
play nicely together.  It is no longer necessary to install a timeout to
ensure that async signals get handled in a timely manner.
.SH CONSTANTS
.IX Header "CONSTANTS"
\&\f(CW\*(C`SOURCE_REMOVE\*(C'\fR and \f(CW\*(C`SOURCE_CONTINUE\*(C'\fR are designed for use as the
return values from timeout, idle and I/O watch source functions.  They
return true to keep running or false to remove themselves.  These
constants can help you get that the right way around.
.PP
.Vb 2
\&    Glib::SOURCE_CONTINUE     # true
\&    Glib::SOURCE_REMOVE       # false
.Ve
.SH METHODS
.IX Header "METHODS"
.SS "maincontext thingamabob = Glib::MainContext\->\fBnew\fP"
.IX Subsection "maincontext thingamabob = Glib::MainContext->new"
.ie n .SS "mainloop = Glib::MainLoop\->\fBnew\fP ($context=undef, $is_running=FALSE)"
.el .SS "mainloop = Glib::MainLoop\->\fBnew\fP ($context=undef, \f(CW$is_running\fP=FALSE)"
.IX Subsection "mainloop = Glib::MainLoop->new ($context=undef, $is_running=FALSE)"
.IP \(bu 4
\&\f(CW$context\fR (Glib::MainContext thingamabob)
.IP \(bu 4
\&\f(CW$is_running\fR (boolean)
.ie n .SS "integer = Glib::Timeout\->\fBadd\fP ($interval, $callback, $data=undef, $priority=G_PRIORITY_DEFAULT)"
.el .SS "integer = Glib::Timeout\->\fBadd\fP ($interval, \f(CW$callback\fP, \f(CW$data\fP=undef, \f(CW$priority\fP=G_PRIORITY_DEFAULT)"
.IX Subsection "integer = Glib::Timeout->add ($interval, $callback, $data=undef, $priority=G_PRIORITY_DEFAULT)"
.IP \(bu 4
\&\f(CW$interval\fR (integer) number of milliseconds
.IP \(bu 4
\&\f(CW$callback\fR (subroutine)
.IP \(bu 4
\&\f(CW$data\fR (scalar)
.IP \(bu 4
\&\f(CW$priority\fR (integer)
.PP
Run \fR\f(CI$callback\fR\fI\fR every \fI\fR\f(CI$interval\fR\fI\fR milliseconds until \fI\fR\f(CI$callback\fR\fI\fR returns
false.  Returns a source id which may be used with \f(CW\*(C`Glib::Source\->remove\*(C'\fR.
Note that a mainloop must be active for the timeout to execute.
.ie n .SS "integer = Glib::Idle\->\fBadd\fP ($callback, $data=undef, $priority=G_PRIORITY_DEFAULT_IDLE)"
.el .SS "integer = Glib::Idle\->\fBadd\fP ($callback, \f(CW$data\fP=undef, \f(CW$priority\fP=G_PRIORITY_DEFAULT_IDLE)"
.IX Subsection "integer = Glib::Idle->add ($callback, $data=undef, $priority=G_PRIORITY_DEFAULT_IDLE)"
.IP \(bu 4
\&\f(CW$callback\fR (subroutine)
.IP \(bu 4
\&\f(CW$data\fR (scalar)
.IP \(bu 4
\&\f(CW$priority\fR (integer)
.PP
Run \fR\f(CI$callback\fR\fI\fR when the mainloop is idle.  If \fI\fR\f(CI$callback\fR\fI\fR returns false,
it will uninstall itself, otherwise, it will run again at the next idle
iteration.  Returns a source id which may be used with
\&\f(CW\*(C`Glib::Source\->remove\*(C'\fR.
.ie n .SS "integer = Glib::Timeout\->\fBadd_seconds\fP ($interval, $callback, $data=undef, $priority=G_PRIORITY_DEFAULT)"
.el .SS "integer = Glib::Timeout\->\fBadd_seconds\fP ($interval, \f(CW$callback\fP, \f(CW$data\fP=undef, \f(CW$priority\fP=G_PRIORITY_DEFAULT)"
.IX Subsection "integer = Glib::Timeout->add_seconds ($interval, $callback, $data=undef, $priority=G_PRIORITY_DEFAULT)"
.IP \(bu 4
\&\f(CW$interval\fR (integer)
.IP \(bu 4
\&\f(CW$callback\fR (scalar)
.IP \(bu 4
\&\f(CW$data\fR (scalar)
.IP \(bu 4
\&\f(CW$priority\fR (integer)
.PP
Since: glib 2.14
.ie n .SS "integer = Glib::IO\->\fBadd_watch\fP ($fd, $condition, $callback, $data=undef, $priority=G_PRIORITY_DEFAULT)"
.el .SS "integer = Glib::IO\->\fBadd_watch\fP ($fd, \f(CW$condition\fP, \f(CW$callback\fP, \f(CW$data\fP=undef, \f(CW$priority\fP=G_PRIORITY_DEFAULT)"
.IX Subsection "integer = Glib::IO->add_watch ($fd, $condition, $callback, $data=undef, $priority=G_PRIORITY_DEFAULT)"
.IP \(bu 4
\&\f(CW$fd\fR (integer) file descriptor, e.g. fileno($filehandle)
.IP \(bu 4
\&\f(CW$condition\fR (Glib::IOCondition)
.IP \(bu 4
\&\f(CW$callback\fR (subroutine)
.IP \(bu 4
\&\f(CW$data\fR (scalar)
.IP \(bu 4
\&\f(CW$priority\fR (integer)
.PP
Run \fR\f(CI$callback\fR\fI\fR when there is an event on \fI\fR\f(CI$fd\fR\fI\fR that matches \fI\fR\f(CI$condition\fR\fI\fR.
The watch uninstalls itself if \fI\fR\f(CI$callback\fR\fI\fR returns false.
Returns a source id that may be used with \f(CW\*(C`Glib::Source\->remove\*(C'\fR.
.PP
Glib's IO channels serve the same basic purpose as Perl's file handles, so
for the most part you don't see GIOChannels in Perl.  The IO watch integrates
IO operations with the main loop, which Perl file handles don't do.  For
various reasons, this function requires raw file descriptors, not full
file handles.  See \f(CW\*(C`fileno\*(C'\fR in perlfunc.
.ie n .SS "maincontext thingamabob = $loop\->\fBget_context\fP"
.el .SS "maincontext thingamabob = \f(CW$loop\fP\->\fBget_context\fP"
.IX Subsection "maincontext thingamabob = $loop->get_context"
.SS "maincontext thingamabob = Glib::MainContext\->\fBdefault\fP"
.IX Subsection "maincontext thingamabob = Glib::MainContext->default"
.ie n .SS "boolean = $context\->\fBis_owner\fP"
.el .SS "boolean = \f(CW$context\fP\->\fBis_owner\fP"
.IX Subsection "boolean = $context->is_owner"
Since: glib 2.12
.ie n .SS "boolean = $loop\->\fBis_running\fP"
.el .SS "boolean = \f(CW$loop\fP\->\fBis_running\fP"
.IX Subsection "boolean = $loop->is_running"
.ie n .SS "boolean = $context\->\fBiteration\fP ($may_block)"
.el .SS "boolean = \f(CW$context\fP\->\fBiteration\fP ($may_block)"
.IX Subsection "boolean = $context->iteration ($may_block)"
.IP \(bu 4
\&\f(CW$may_block\fR (boolean)
.SS "integer = Glib::main_depth"
.IX Subsection "integer = Glib::main_depth"
Find the current main loop recursion level.  This is handy in fringe
situations, but those are very rare; see the C API reference for a more
in-depth discussion.
.PP
Since: glib 2.4
.ie n .SS "boolean = $context\->\fBpending\fP"
.el .SS "boolean = \f(CW$context\fP\->\fBpending\fP"
.IX Subsection "boolean = $context->pending"
.ie n .SS $loop\->\fBquit\fP
.el .SS \f(CW$loop\fP\->\fBquit\fP
.IX Subsection "$loop->quit"
.SS "boolean = Glib::Source\->\fBremove\fP ($tag)"
.IX Subsection "boolean = Glib::Source->remove ($tag)"
.IP \(bu 4
\&\f(CW$tag\fR (integer)
.PP
Remove an event source.  \fR\f(CI$tag\fR\fI\fR is the number returned by things like
\&\f(CW\*(C`Glib::Timeout\->add\*(C'\fR, \f(CW\*(C`Glib::Idle\->add\*(C'\fR, and
\&\f(CW\*(C`Glib::IO\->add_watch\*(C'\fR.
.ie n .SS $loop\->\fBrun\fP
.el .SS \f(CW$loop\fP\->\fBrun\fP
.IX Subsection "$loop->run"
.ie n .SS "integer = Glib::Child\->\fBwatch_add\fP ($pid, $callback, $data=undef, $priority=G_PRIORITY_DEFAULT)"
.el .SS "integer = Glib::Child\->\fBwatch_add\fP ($pid, \f(CW$callback\fP, \f(CW$data\fP=undef, \f(CW$priority\fP=G_PRIORITY_DEFAULT)"
.IX Subsection "integer = Glib::Child->watch_add ($pid, $callback, $data=undef, $priority=G_PRIORITY_DEFAULT)"
.IP \(bu 4
\&\f(CW$pid\fR (integer) child process ID
.IP \(bu 4
\&\f(CW$callback\fR (subroutine)
.IP \(bu 4
\&\f(CW$data\fR (scalar)
.IP \(bu 4
\&\f(CW$priority\fR (integer)
.PP
Add a source to the default main context which will call
.PP
.Vb 1
\&    &$callback ($pid, $waitstatus, $data)
.Ve
.PP
when child process \f(CW$pid\fR terminates.  The return value is a source id
which can be used with \f(CW\*(C`Glib::Source\->remove\*(C'\fR.  When the callback
is made the source is removed automatically.
.PP
In a non-threaded program Glib implements this source by installing a
SIGCHLD handler.  Don't change \f(CW$SIG\fR{CHLD} in Perl or the callback will
never run.
.PP
Since: glib 2.4
.SH "ENUMS AND FLAGS"
.IX Header "ENUMS AND FLAGS"
.SS "flags Glib::IOCondition"
.IX Subsection "flags Glib::IOCondition"
.IP \(bu 4
\&'in' / 'G_IO_IN'
.IP \(bu 4
\&'out' / 'G_IO_OUT'
.IP \(bu 4
\&'pri' / 'G_IO_PRI'
.IP \(bu 4
\&'err' / 'G_IO_ERR'
.IP \(bu 4
\&'hup' / 'G_IO_HUP'
.IP \(bu 4
\&'nval' / 'G_IO_NVAL'
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Glib
.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.