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

Comparing Guard/Guard.pm (file contents):
Revision 1.17 by root, Fri Dec 26 13:04:04 2008 UTC vs.
Revision 1.23 by root, Fri Mar 12 17:25:58 2010 UTC

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

Diff Legend

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

Comparing Guard/Guard.pm (file contents): Revision 1.17 by root, Fri Dec 26 13:04:04 2008 UTC vs. Revision 1.23 by root, Fri Mar 12 17:25:58 2010 UTC

Diff Legend

Comparing Guard/Guard.pm (file contents):
Revision 1.17 by root, Fri Dec 26 13:04:04 2008 UTC vs.
Revision 1.23 by root, Fri Mar 12 17:25:58 2010 UTC