Glib::MainLoop(3)

📦
version 1.3294 · 14 versions
, in opensuse-leap 16.0

💖 Glib::MainLoop(3) 💖

okay so bestie, this is Glib::MainLoop(3), and it comes straight from the User Contributed Perl Documentation girlies. It's literally an event source manager, and we're gonna get into it. 🦋

🌸 NAME 🌸

Glib::MainLoop — an event source manager. periodt.

✨ DESCRIPTION ✨

Event-driven programs need some kind of loop that watches for events and launches the appropriate actions. Glib::MainLoop provides exactly that functionality, no cap.

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. iykyk.

Event sources, attached to main contexts, watch for events to happen, and launch appropriate actions. Glib provides a few ready-made event sources: Glib::Timeout, Glib::Idle, and io watch (Glib::IO->add_watch). slay.

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. lowkey convenient.

⭐ 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. fr fr.

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

💅 METHODS 💅

🌟 maincontext thingamabob = Glib::MainContext->new

No arguments here — it's giving solo main character energy. ✨

💫 mainloop = Glib::MainLoop->new ($context=undef, $is_running=FALSE)

  • $context (Glib::MainContext thingamabob) — yes, the docs literally say thingamabob, iconic.
  • $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. important bestie.

🦋 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. cute little self-cleaning source.

🌸 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 — vintage but still cute. 🎀

🔥 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. raw fd realness.

🫶 maincontext thingamabob = $loop->get_context

No arguments, just vibes. ✨

🎀 maincontext thingamabob = Glib::MainContext->default

No arguments either — it's the default context, bestie.

👑 boolean = $context->is_owner

Since: glib 2.12.

💜 boolean = $loop->is_running

No arguments. It's just checking the vibe. 🌈

🌟 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

No arguments. Short and sweet. 🍓

💀 $loop->quit

No arguments. Say bye to the loop. 💅

🦋 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

No arguments. Run the loop, bestie. 🏃‍♀️💨

👶 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. self-removing, we love to see it.

⚠️ 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. This is a real one, bestie. 😭

Since: glib 2.4.

🦋 ENUMS AND FLAGS 🦋

🏷️ flags Glib::IOCondition

The whole flag lineup, no substitutions:

  • '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 — go read that one too, bestie. 💜

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

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

💖 sourced from perl v5.42.0, dated 2023-09-05 — mwah, bye bestie 💅

📦 where this page comes from