-
-
08 Jun 2014 10:25:52 UTC
- Distribution: Glib-Ex-ObjectBits
- Module version: 16
- Source (raw)
- Browse (raw)
- Changes
- Homepage
- How to Contribute
- Issues
- Testers (3434 / 29 / 0)
- Kwalitee
Bus factor: 1- 68.02% Coverage
- License: gpl_3
- Perl: v5.8.0
- Activity
24 month- Tools
- Download (51.52KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
and 1 contributors-
Kevin Ryde
- Dependencies
- Devel::GlobalDestruction
- Glib
- Glib::Object::Subclass
- and possibly others
- Reverse dependencies
- CPAN Testers List
- Dependency graph
NAME
Glib::Ex::FreezeNotify -- freeze Glib object property notifies by scope guard style
SYNOPSIS
use Glib::Ex::FreezeNotify; { my $freezer = Glib::Ex::FreezeNotify->new ($obj); $obj->set (foo => 123); $obj->set (bar => 456); # notify signals emitted when $freezer goes out of scope } # or multiple objects in one FreezeNotify { my $freezer = Glib::Ex::FreezeNotify->new ($obj1, $obj2); $obj1->set (foo => 999); $obj2->set (bar => 666); }
DESCRIPTION
Glib::Ex::FreezeNotify
applies afreeze_notify()
to given objects, with automatic correspondingthaw_notify()
at the end of a block, no matter how it's exited, whether agoto
, earlyreturn
,die
, etc.This protects against an error throw leaving the object permanently frozen. Even in simple code an error can be thrown for a bad property name in a
set()
, or while calculating a value. (Though as of Glib-Perl 1.222 an invalid argument type toset()
generally only provokes warnings.)Operation
FreezeNotify works by having
thaw_notify()
in the destroy code of the FreezeNotify object.FreezeNotify only holds weak references to its objects, so the mere fact they're due for later thawing doesn't keep them alive if nothing else cares whether they live or die. The effect is that frozen objects can be garbage collected within a freeze block at the same point they would be without any freezing, instead of extending their life to the end of the block.
It works to have multiple freeze/thaws, done either with FreezeNotify or with other
freeze_notify()
calls.Glib::Object
simply counts outstanding freezes, which means they don't have to nest, so 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 the thaws, although anything except a short freeze for a handful ofset_property()
calls would be unusual.During "global destruction" phase nothing is done when a FreezeNotify is destroyed. The target objects may be already destroyed and not in a fit state to unthaw. Perl is exiting so unthawing shouldn't matter.
FUNCTIONS
$freezer = 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 something like$obj->freeze_notify; $obj->set (foo => 1); $obj->set (bar => 1); $obj->thaw_notify;
becomes instead
{ my $freezer = Glib::Ex::FreezeNotify->new ($obj); $obj->set (foo => 1); $obj->set (bar => 1); } # automatic thaw when $freezer goes out of scope
$freezer->add ($object,...)
-
Add additional objects to the freezer, calling
$object->freeze_notify
on each, and setting up forthaw_notify
the same as innew
above.If the objects to be frozen are not known in advance then it's good to create an empty freezer with
new
then add objects to it as required.
OTHER NOTES
When there's multiple objects in a freezer it's unspecified what order the
thaw_notify()
calls are made. What would be good? First-in first-out, or a stack? You can create multiple FreezeNotify objects and arrange blocks or explicit discards to destroy them in a particular order if it matters.There's quite a few general purpose block-scope cleanup systems to do more than just thaws. Scope::Guard, AtExit, End, ReleaseAction, Sub::ScopeFinalizer and Guard use the destructor style. Hook::Scope and B::Hooks::EndOfScope manipulate the code in a block. Unwind::Protect uses an
eval
and re-throw.SEE ALSO
Glib::Object, Glib::Ex::SignalBits, 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/.
Module Install Instructions
To install Glib::Ex::ObjectBits, copy and paste the appropriate command in to your terminal.
cpanm Glib::Ex::ObjectBits
perl -MCPAN -e shell install Glib::Ex::ObjectBits
For more information on module installation, please visit the detailed CPAN module installation guide.