[ViewVC] Diff of: cvs/Guard/Guard.pm

Comparing Guard/Guard.pm (file contents):
Revision 1.12 by root, Sat Dec 13 18:53:30 2008 UTC vs.
Revision 1.22 by root, Sun Jul 26 08:07:11 2009 UTC

…		…
10	# to go back to "/" no matter how myfun exits:	10	# to go back to "/" no matter how myfun exits:
11	sub myfun {	11	sub myfun {
12	scope_guard { chdir "/" };	12	scope_guard { chdir "/" };
13	chdir "/etc";	13	chdir "/etc";
14		14
15	call_function_that_might_die_or_other_fun_stuff;	15	code_that_might_die_or_does_other_fun_stuff;
16	}	16	}
		17
		18	# create an object that, when the last reference to it is gone,
		19	# invokes the given codeblock:
		20	my $guard = guard { print "destroyed!\n" };
		21	undef $guard; # probably destroyed here
17		22
18	=head1 DESCRIPTION	23	=head1 DESCRIPTION
19		24
20	This module implements so-called "guards". A guard is something (usually	25	This module implements so-called "guards". A guard is something (usually
21	an object) that "guards" a resource, ensuring that it is cleaned up when	26	an object) that "guards" a resource, ensuring that it is cleaned up when
…		…
34		39
35	=cut	40	=cut
36		41
37	package Guard;	42	package Guard;
38		43
		44	no warnings;
		45
39	BEGIN {	46	BEGIN {
40	$VERSION = '0.1';	47	$VERSION = '1.021';
41	@ISA = qw(Exporter);	48	@ISA = qw(Exporter);
42	@EXPORT = qw(guard scope_guard);	49	@EXPORT = qw(guard scope_guard);
43		50
44	require Exporter;	51	require Exporter;
45		52
…		…
101	Behaves the same as C<scope_guard>, except that instead of executing	108	Behaves the same as C<scope_guard>, except that instead of executing
102	the block on scope exit, it returns an object whose lifetime determines	109	the block on scope exit, it returns an object whose lifetime determines
103	when the BLOCK gets executed: when the last reference to the object gets	110	when the BLOCK gets executed: when the last reference to the object gets
104	destroyed, the BLOCK gets executed as with C<scope_guard>.	111	destroyed, the BLOCK gets executed as with C<scope_guard>.
105		112
106	The returned object can be copied as many times as you want.
107
108	See the EXCEPTIONS section for an explanation of how exceptions	113	See the EXCEPTIONS section for an explanation of how exceptions
109	(i.e. C<die>) are handled inside guard blocks.	114	(i.e. C<die>) are handled inside guard blocks.
110		115
111	Example: acquire a Coro::Semaphore for a second by registering a	116	Example: acquire a Coro::Semaphore for a second by registering a
112	timer. The timer callback references the guard used to unlock it	117	timer. The timer callback references the guard used to unlock it
113	again. (Please ignore the fact that C<Coro::Semaphore> has a C<guard>	118	again. (Please ignore the fact that C<Coro::Semaphore> has a C<guard>
114	method that does this already):	119	method that does this already):
115		120
116	use Guard;	121	use Guard;
117	use AnyEvent;	122	use Coro::AnyEvent;
118	use Coro::Semaphore;	123	use Coro::Semaphore;
119		124
120	my $sem = new Coro::Semaphore;	125	my $sem = new Coro::Semaphore;
121		126
122	sub lock_for_a_second {	127	sub lock_for_a_second {
123	$sem->down;	128	$sem->down;
124	my $guard = guard { $sem->up };	129	my $guard = guard { $sem->up };
125		130
126	my $timer;	131	Coro::AnyEvent::sleep 1;
127	$timer = AnyEvent->timer (after => 1, sub {	132
128	# do something	133	# $sem->up gets executed when returning
129	undef $sem;
130	undef $timer;
131	});
132	}	134	}
133		135
134	The advantage of doing this with a guard instead of simply calling C<<	136	The advantage of doing this with a guard instead of simply calling C<<
135	$sem->down >> in the callback is that you can opt not to create the timer,	137	$sem->down >> in the callback is that you can opt not to create the timer,
136	or your code can throw an exception before it can create the timer, or you	138	or your code can throw an exception before it can create the timer (or
137	can create multiple timers or other event watchers and only when the last	139	the thread gets canceled), or you can create multiple timers or other
138	one gets executed will the lock be unlocked. Using the C<guard>, you do	140	event watchers and only when the last one gets executed will the lock be
139	not have to worry about catching all the places where you have to unlock	141	unlocked. Using the C<guard>, you do not have to worry about catching all
140	the semaphore.	142	the places where you have to unlock the semaphore.
141		143
142	=item Guard::cancel $guard	144	=item $guard->cancel
143		145
144	Calling this function will "disable" the guard object returned by the	146	Calling this function will "disable" the guard object returned by the
145	C<guard> function, i.e. it will free the BLOCK originally passed to	147	C<guard> function, i.e. it will free the BLOCK originally passed to
146	C<guard >and will arrange for the BLOCK not to be executed.	148	C<guard >and will arrange for the BLOCK not to be executed.
147		149
148	This can be useful when you use C<guard> to create a fatal cleanup handler	150	This can be useful when you use C<guard> to create a cleanup handler to be
149	and later decide it is no longer needed.	151	called under fatal conditions and later decide it is no longer needed.
150		152
151	=cut	153	=cut
152		154
153	1;	155	1;
154		156
155	=back	157	=back
156		158
157	=head1 EXCEPTIONS	159	=head1 EXCEPTIONS
158		160
159	Guard blocks should not normally throw exceptions (that is, C<die>). After	161	Guard blocks should not normally throw exceptions (that is, C<die>). After
160	all, they are usually used to clean up after such exceptions. However, if	162	all, they are usually used to clean up after such exceptions. However,
161	something truly exceptional is happening, a guard block should be allowed	163	if something truly exceptional is happening, a guard block should of
162	to die. Also, programming errors are a large source of exceptions, and the	164	course be allowed to die. Also, programming errors are a large source of
163	programmer certainly wants to know about those.	165	exceptions, and the programmer certainly wants to know about those.
164		166
165	Since in most cases, the block executing when the guard gets executes does	167	Since in most cases, the block executing when the guard gets executed does
166	not know or does not care about the guard blocks, it makes little sense to	168	not know or does not care about the guard blocks, it makes little sense to
167	let containing code handle the exception.	169	let containing code handle the exception.
168		170
169	Therefore, whenever a guard block throws an exception, it will be caught,	171	Therefore, whenever a guard block throws an exception, it will be caught
170	and this module will call the code reference stored in C<$Guard::DIED>	172	by Guard, followed by calling the code reference stored in C<$Guard::DIED>
171	(with C<$@> set to the actual exception), which is similar to how most	173	(with C<$@> set to the actual exception), which is similar to how most
172	event loops handle this case.	174	event loops handle this case.
173		175
174	The default for C<$Guard::DIED> is to call C<warn "$@">.	176	The default for C<$Guard::DIED> is to call C<warn "$@">, i.e. the error is
		177	printed as a warning and the program continues.
175		178
176	The C<$@> variable will be restored to its value before the guard call in	179	The C<$@> variable will be restored to its value before the guard call in
177	all cases, so guards will not disturb C<$@> in any way.	180	all cases, so guards will not disturb C<$@> in any way.
178		181
179	The code reference stored in C<$Guard::DIED> should not die (behaviour is	182	The code reference stored in C<$Guard::DIED> should not die (behaviour is
…		…
187	=head1 THANKS	190	=head1 THANKS
188		191
189	Thanks to Marco Maisenhelder, who reminded me of the C<$Guard::DIED>	192	Thanks to Marco Maisenhelder, who reminded me of the C<$Guard::DIED>
190	solution to the problem of exceptions.	193	solution to the problem of exceptions.
191		194
		195	=head1 SEE ALSO
		196
		197	L<Scope::Guard> and L<Sub::ScopeFinalizer>, which actually implement
		198	dynamic guards only, not scoped guards, and have a lot higher CPU, memory
		199	and typing overhead.
		200
		201	L<Hook::Scope>, which has apparently never been finished and can corrupt
		202	memory when used.
		203
192	=cut	204	=cut
193		205

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing Guard/Guard.pm (file contents): Revision 1.12 by root, Sat Dec 13 18:53:30 2008 UTC vs. Revision 1.22 by root, Sun Jul 26 08:07:11 2009 UTC

Diff Legend

Comparing Guard/Guard.pm (file contents):
Revision 1.12 by root, Sat Dec 13 18:53:30 2008 UTC vs.
Revision 1.22 by root, Sun Jul 26 08:07:11 2009 UTC