NAME

       Glib::MainLoop -  An event source manager

DESCRIPTION

       Event-driven programs need some sort of loop which watches for events and launches the
       appropriate actions.  Glib::MainLoop provides this functionality.

       Mainloops have context, provided by the MainContext object.  For the most part you can use
       the default context (see "default"), but if you want to create a subcontext for a nested
       loop which doesn't have the same event sources, etc, you can.

       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 ("Glib::IO->add_watch").

       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 "Gtk2->main" and friends), so
       you may rarely have cause to use Glib::MainLoop directly.

       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.

CONSTANTS

       "SOURCE_REMOVE" and "SOURCE_CONTINUE" 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.

           Glib::SOURCE_CONTINUE     # true
           Glib::SOURCE_REMOVE       # false

METHODS

   maincontext thingamabob = Glib::MainContext->new
   mainloop = Glib::MainLoop->new ($context=undef, $is_running=FALSE)
       •   $context (Glib::MainContext thingamabob)

       •   $is_running (boolean)

   integer = Glib::Timeout->add ($interval, $callback, $data=undef, $priority=G_PRIORITY_DEFAULT)
       •   $interval (integer) number of milliseconds

       •   $callback (subroutine)

       •   $data (scalar)

       •   $priority (integer)

       Run $callback every $interval milliseconds until $callback returns false.  Returns a
       source id which may be used with "Glib::Source->remove".  Note that a mainloop must be
       active for the timeout to execute.

   integer = Glib::Idle->add ($callback, $data=undef, $priority=G_PRIORITY_DEFAULT_IDLE)
       •   $callback (subroutine)

       •   $data (scalar)

       •   $priority (integer)

       Run $callback when the mainloop is idle.  If $callback 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 "Glib::Source->remove".

   integer = Glib::Timeout->add_seconds ($interval, $callback, $data=undef,
       $priority=G_PRIORITY_DEFAULT)
       •   $interval (integer)

       •   $callback (scalar)

       •   $data (scalar)

       •   $priority (integer)

       Since: glib 2.14

   integer = Glib::IO->add_watch ($fd, $condition, $callback, $data=undef,
       $priority=G_PRIORITY_DEFAULT)
       •   $fd (integer) file descriptor, e.g. fileno($filehandle)

       •   $condition (Glib::IOCondition)

       •   $callback (subroutine)

       •   $data (scalar)

       •   $priority (integer)

       Run $callback when there is an event on $fd that matches $condition.  The watch uninstalls
       itself if $callback returns false.  Returns a source id that may be used with
       "Glib::Source->remove".

       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 "fileno" in perlfunc.

   maincontext thingamabob = $loop->get_context
   maincontext thingamabob = Glib::MainContext->default
   boolean = $context->is_owner
       Since: glib 2.12

   boolean = $loop->is_running
   boolean = $context->iteration ($may_block)
       •   $may_block (boolean)

   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.

       Since: glib 2.4

   boolean = $context->pending
   $loop->quit
   boolean = Glib::Source->remove ($tag)
       •   $tag (integer)

       Remove an event source.  $tag is the number returned by things like "Glib::Timeout->add",
       "Glib::Idle->add", and "Glib::IO->add_watch".

   $loop->run
   integer = Glib::Child->watch_add ($pid, $callback, $data=undef, $priority=G_PRIORITY_DEFAULT)
       •   $pid (integer) child process ID

       •   $callback (subroutine)

       •   $data (scalar)

       •   $priority (integer)

       Add a source to the default main context which will call

           &$callback ($pid, $waitstatus, $data)

       when child process $pid terminates.  The return value is a source id which can be used
       with "Glib::Source->remove".  When the callback is made the source is removed
       automatically.

       In a non-threaded program Glib implements this source by installing a SIGCHLD handler.
       Don't change $SIG{CHLD} in Perl or the callback will never run.

       Since: glib 2.4

ENUMS AND FLAGS

   flags Glib::IOCondition
       •   'in' / 'G_IO_IN'

       •   'out' / 'G_IO_OUT'

       •   'pri' / 'G_IO_PRI'

       •   'err' / 'G_IO_ERR'

       •   'hup' / 'G_IO_HUP'

       •   'nval' / 'G_IO_NVAL'

SEE ALSO

       Glib

COPYRIGHT

       Copyright (C) 2003-2011 by the gtk2-perl team.

       This software is licensed under the LGPL.  See Glib for a full notice.