NAME

Glib::Ex::SourceIds -- hold Glib main loop source IDs

SYNOPSIS

 use Glib::Ex::SourceIds;
 my $sourceids = Glib::Ex::SourceIds->new
                    (Glib::Timeout->add (1000, \&do_timer),
                     Glib::Idle->add (\&do_idle));

 # removed when ids object destroyed
 $sourceids = undef;

DESCRIPTION

Glib::Ex::SourceIds holds a set of Glib main loop source IDs. When the SourceIds object is destroyed it removes those IDs.

This is designed as a reliable way to keep sources installed for a limited period, such as an IO watch while communicating on a socket, or a timeout on an action. Often such things will be associated with a Glib::Object (or just a Perl object), though they don't have to be.

Callback Removal

Callback handler code which wants to remove itself as a source should destroy any SourceIds object holding that source. This will have the effect of removing the handler. It can return false (Glib::SOURCE_REMOVE()) to remove itself too if desired.

Recent Glib made incompatible changes to g_source_remove() so that it emits a g_log() error message on attempting to remove an already-removed source. This will happen if a handler removes itself and then later a SourceIds is destroyed and so removes again.

FUNCTIONS

$sourceids = Glib::Ex::SourceIds->new ($id,$id,...)

Create and return a SourceIds object holding the given $id main loop source IDs (integers).

SourceIds doesn't install sources. You do that with Glib::Timeout->add(), Glib::IO->add_watch() and Glib::Idle->add() in the usual ways and all the various options, then pass the resulting ID to SourceIds to look after. Eg.

    my $sourceids = Glib::Ex::SourceIds->new
                      (Glib::Timeout->add (1000, \&do_timer));

You can hold any number of IDs in a SourceIds object. If you want things installed and removed at different points in the program then use separate SourceIds objects for each (or each group).

$sourceids->add ($id,$id,...)

Add the given $id main loop source IDs (integers) to SourceIds object $sourceids. This can be used for IDs created separately from a new() call.

    $sourceids->add (Glib::Timeout->add (1000, \&do_timer));

Adding IDs one by one is good if the code might error out. IDs previously connected are safely tucked away in the SourceIds and will be disconnect as the error unwinds. An error in a simple connection is unlikely, but if for instance the "condition" flags for an add_watch() came from some external code then they could be invalid.

$sourceids->remove()

Remove the source IDs held in $sourceids from the main loop, using Glib::Source->remove(). This remove is done when $sourceids is garbage collected, but you can do it explicitly sooner if desired.

SEE ALSO

Glib::MainLoop, Glib::Ex::SignalIds

HOME PAGE

http://user42.tuxfamily.org/glib-ex-objectbits/index.html

LICENSE

Copyright 2008, 2009, 2010, 2011, 2012, 2014 Kevin Ryde

Glib-Ex-ObjectBits is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Glib-Ex-ObjectBits is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Glib-Ex-ObjectBits. If not, see http://www.gnu.org/licenses/.