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

Comparing Guard/Guard.pm (file contents):
Revision 1.11 by root, Sat Dec 13 18:51:19 2008 UTC vs.
Revision 1.26 by root, Tue Mar 21 11:39:27 2017 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.023;
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
…		…
48	}	55	}
49		56
50	our $DIED = sub { warn "$@" };	57	our $DIED = sub { warn "$@" };
51		58
52	=item scope_guard BLOCK	59	=item scope_guard BLOCK
		60
		61	=item scope_guard ($coderef)
53		62
54	Registers a block that is executed when the current scope (block,	63	Registers a block that is executed when the current scope (block,
55	function, method, eval etc.) is exited.	64	function, method, eval etc.) is exited.
56		65
57	See the EXCEPTIONS section for an explanation of how exceptions	66	See the EXCEPTIONS section for an explanation of how exceptions
…		…
75	BLOCK calls C<exit>, C<goto>, C<last> or escapes via other means.	84	BLOCK calls C<exit>, C<goto>, C<last> or escapes via other means.
76		85
77	If multiple BLOCKs are registered to the same scope, they will be executed	86	If multiple BLOCKs are registered to the same scope, they will be executed
78	in reverse order. Other scope-related things such as C<local> are managed	87	in reverse order. Other scope-related things such as C<local> are managed
79	via the same mechanism, so variables C<local>ised I<after> calling	88	via the same mechanism, so variables C<local>ised I<after> calling
80	C<scope_guard> will be restored when the guard runs.	89	C<scope_guard> will be restored I<before> the guard runs.
81		90
82	Example: temporarily change the timezone for the current process,	91	Example: temporarily change the timezone for the current process,
83	ensuring it will be reset when the C<if> scope is exited:	92	ensuring it will be reset when the C<if> scope is exited:
84		93
85	use Guard;	94	use Guard;
…		…
95		104
96	# do something with the new timezone	105	# do something with the new timezone
97	}	106	}
98		107
99	=item my $guard = guard BLOCK	108	=item my $guard = guard BLOCK
		109
		110	=item my $guard = guard ($coderef)
100		111
101	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
102	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
103	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
104	destroyed, the BLOCK gets executed as with C<scope_guard>.	115	destroyed, the BLOCK gets executed as with C<scope_guard>.
105		116
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	117	See the EXCEPTIONS section for an explanation of how exceptions
109	(i.e. C<die>) are handled inside guard blocks.	118	(i.e. C<die>) are handled inside guard blocks.
110		119
111	Example: acquire a Coro::Semaphore for a second by registering a	120	Example: acquire a Coro::Semaphore for a second by registering a
112	timer. The timer callback references the guard used to unlock it	121	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>	122	again. (Please ignore the fact that C<Coro::Semaphore> has a C<guard>
114	method that does this already):	123	method that does this already):
115		124
116	use Guard;	125	use Guard;
117	use AnyEvent;	126	use Coro::AnyEvent;
118	use Coro::Semaphore;	127	use Coro::Semaphore;
119		128
120	my $sem = new Coro::Semaphore;	129	my $sem = new Coro::Semaphore;
121		130
122	sub lock_for_a_second {	131	sub lock_for_a_second {
123	$sem->down;	132	$sem->down;
124	my $guard = guard { $sem->up };	133	my $guard = guard { $sem->up };
125		134
126	my $timer;	135	Coro::AnyEvent::sleep 1;
127	$timer = AnyEvent->timer (after => 1, sub {	136
128	# do something	137	# $sem->up gets executed when returning
129	undef $sem;
130	undef $timer;
131	});
132	}	138	}
133		139
134	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<<
135	$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,
136	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
137	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
138	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
139	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
140	the semaphore.	146	the places where you have to unlock the semaphore.
141		147
142	=item Guard::cancel $guard	148	=item $guard->cancel
143		149
144	Calling this function will "disable" the guard object returned by the	150	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	151	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.	152	C<guard >and will arrange for the BLOCK not to be executed.
147		153
148	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
149	and later decide it is no longer needed.	155	called under fatal conditions and later decide it is no longer needed.
150		156
151	=cut	157	=cut
152		158
153	1;	159	1;
154		160
155	=back	161	=back
156		162
157	=head1 EXCEPTIONS	163	=head1 EXCEPTIONS
158		164
159	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
160	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,
161	something truly exceptional is happening, a guard block should be allowed	167	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	168	course be allowed to die. Also, programming errors are a large source of
163	programmer certainly wants to know about those.	169	exceptions, and the programmer certainly wants to know about those.
164		170
165	Since in most cases, the block executing when the guard gets executes does	171	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	172	not know or does not care about the guard blocks, it makes little sense to
167	let containing code handle the exception.	173	let containing code handle the exception.
168		174
169	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
170	and this module will call the code reference stored in C<$Guard::DIED>	176	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	177	(with C<$@> set to the actual exception), which is similar to how most
172	event loops handle this case.	178	event loops handle this case.
173		179
		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.
		182
		183	The C<$@> variable will be restored to its value before the guard call in
		184	all cases, so guards will not disturb C<$@> in any way.
		185
174	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
175	not guaranteed, but right now, the exception will simply be ignored).	187	not guaranteed, but right now, the exception will simply be ignored).
176		188
177	The default for C<$Guard::DIED> is to call C<warn "$@">.
178
179	=head1 AUTHOR	189	=head1 AUTHOR
180		190
181	Marc Lehmann <schmorp@schmorp.de>	191	Marc Lehmann <schmorp@schmorp.de>
182	http://home.schmorp.de/	192	http://home.schmorp.de/
183		193
184	=head1 THANKS	194	=head1 THANKS
185		195
186	Thanks to Marco Maisenhelder, who reminded me of the C<$Guard::DIED>	196	Thanks to Marco Maisenhelder, who reminded me of the C<$Guard::DIED>
187	solution to the problem of exceptions.	197	solution to the problem of exceptions.
188		198
		199	=head1 SEE ALSO
		200
		201	L<Scope::Guard> and L<Sub::ScopeFinalizer>, which actually implement
		202	dynamically scoped guards only, not the lexically scoped guards that their
		203	documentation promises, and have a lot higher CPU, memory and typing
		204	overhead.
		205
		206	L<Hook::Scope>, which has apparently never been finished and can corrupt
		207	memory when used.
		208
		209	L<Scope::Guard> seems to have a big SEE ALSO section for even more
		210	modules like it.
		211
189	=cut	212	=cut
190		213

Diff Legend

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

Comparing Guard/Guard.pm (file contents): Revision 1.11 by root, Sat Dec 13 18:51:19 2008 UTC vs. Revision 1.26 by root, Tue Mar 21 11:39:27 2017 UTC

Diff Legend

Comparing Guard/Guard.pm (file contents):
Revision 1.11 by root, Sat Dec 13 18:51:19 2008 UTC vs.
Revision 1.26 by root, Tue Mar 21 11:39:27 2017 UTC