NAME

Glib::Ex::FreezeNotify -- freeze notifies in scope guard style

SYNOPSIS

use Glib::Ex::FreezeNotify;

{ my $freezer = Glib::Ex::FreezeNotify->new ($obj);
  $obj->set (foo => 123);
  $obj->set (bar => 456);
  # notify_thaw happens when $freezer goes out of scope
}

# or multiple objects in one FreezeNotify
{
  my $freezer = Glib::Ex::FreezeNotify->new ($obj1, $obj2, ...);
  $obj1->set (foo => 999);
  ...
}

DESCRIPTION

Glib::Ex::FreezeNotify helps you freeze_notify on given Glib::Objects, with an automatic corresponding thaw_notify at the end of the block, no matter how it's exited, whether a goto, early return, die, etc.

The main advantage is protection against an error throw leaving the object permanently frozen. Errors can be thrown for a bad property name in a set, or all the usual ways if calculating a value. (Though as of Glib-Perl 1.181 bad value types as such generally only provoke warnings.)

FreezeNotify works by having thaw_notify in the destroy code of a FreezeNotify object. General purpose cleanups in this destructor style can be done with Scope::Guard or Sub::ScopeFinalizer. FreezeNotify is specific to Glib::Object freeze/thaw.

FreezeNotify only holds weak references to its objects, so the mere fact they're due for later thawing doesn't keep them alive when nothing else cares if they live or die. The only real effect of this is that frozen objects can be garbage collected within the freeze block, instead their life extended to the end of it.

It works to nest freeze/thaws, done either with FreezeNotify or with explicit freeze_notify calls. Glib::Object simply counts outstanding freezes so they don't have to nest; multiple freezes can overlap in any fashion. If you're freezing for an extended time then a FreezeNotify object is a good way not to lose track of your thaws, though anything except a short freeze over a handful of set() calls is probably unusual.

FUNCTIONS

Glib::Ex::FreezeNotify->new ($object,...)

Do a $object->freeze_notify on each given object and return a FreezeNotify object which, when it's destroyed, will $object->thaw_notify each. So if you were thinking of

$obj->freeze_notify;
$obj->set (foo => 1);
$obj->set (bar => 1);
$obj->thaw_notify;

you instead use

{ my $freezer = Glib::Ex::FreezeNotify->new ($obj);
  $obj->set (foo => 1);
  $obj->set (bar => 1);
} # automatic thaw when $freezer goes out of scope

SEE ALSO

Glib::Object, Scope::Guard, Sub::ScopeFinalizer

HOME PAGE

http://www.geocities.com/user42_kevin/glib-ex-objectbits/index.html

LICENSE

Copyright 2008 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/.