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

Comparing Guard/Guard.pm (file contents):
Revision 1.2 by root, Sat Dec 13 17:49:12 2008 UTC vs.
Revision 1.22 by root, Sun Jul 26 08:07:11 2009 UTC

…		…
2		2
3	Guard - safe cleanup blocks	3	Guard - safe cleanup blocks
4		4
5	=head1 SYNOPSIS	5	=head1 SYNOPSIS
6		6
7	use Guard;	7	use Guard;
		8
		9	# temporarily chdir to "/etc" directory, but make sure
		10	# to go back to "/" no matter how myfun exits:
		11	sub myfun {
		12	scope_guard { chdir "/" };
		13	chdir "/etc";
		14
		15	code_that_might_die_or_does_other_fun_stuff;
		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
8		22
9	=head1 DESCRIPTION	23	=head1 DESCRIPTION
10		24
11	This module implements so-called "guards". A guard is something (usually	25	This module implements so-called "guards". A guard is something (usually
12	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
…		…
25		39
26	=cut	40	=cut
27		41
28	package Guard;	42	package Guard;
29		43
		44	no warnings;
		45
30	BEGIN {	46	BEGIN {
31	$VERSION = '0.01';	47	$VERSION = '1.021';
32	@ISA = qw(Exporter);	48	@ISA = qw(Exporter);
33	@EXPORT = qw(guard scope_guard cancel);	49	@EXPORT = qw(guard scope_guard);
34		50
35	require Exporter;	51	require Exporter;
36		52
37	require XSLoader;	53	require XSLoader;
38	XSLoader::load Guard, $VERSION;	54	XSLoader::load Guard, $VERSION;
…		…
43	=item scope_guard BLOCK	59	=item scope_guard BLOCK
44		60
45	Registers a block that is executed when the current scope (block,	61	Registers a block that is executed when the current scope (block,
46	function, method, eval etc.) is exited.	62	function, method, eval etc.) is exited.
47		63
		64	See the EXCEPTIONS section for an explanation of how exceptions
		65	(i.e. C<die>) are handled inside guard blocks.
		66
48	The description below sounds a bit complicated, but that's just because	67	The description below sounds a bit complicated, but that's just because
49	C<scope_guard> tries to get even corner cases "right": the goal is to	68	C<scope_guard> tries to get even corner cases "right": the goal is to
50	provide you with a rock solid clean up tool.	69	provide you with a rock solid clean up tool.
51		70
52	This is similar to this code fragment:	71	The behaviour is similar to this code fragment:
53		72
54	eval ... code following scope_guard ...	73	eval ... code following scope_guard ...
55	{	74	{
56	local $@;	75	local $@;
57	eval BLOCK;	76	eval BLOCK;
…		…
60	die if $@;	79	die if $@;
61		80
62	Except it is much faster, and the whole thing gets executed even when the	81	Except it is much faster, and the whole thing gets executed even when the
63	BLOCK calls C<exit>, C<goto>, C<last> or escapes via other means.	82	BLOCK calls C<exit>, C<goto>, C<last> or escapes via other means.
64		83
65	See B<EXCEPTIONS>, below, for an explanation of exception handling	84	If multiple BLOCKs are registered to the same scope, they will be executed
66	(C<die>) within guard blocks.	85	in reverse order. Other scope-related things such as C<local> are managed
		86	via the same mechanism, so variables C<local>ised I<after> calling
		87	C<scope_guard> will be restored when the guard runs.
67		88
68	Example: Temporarily change the directory to F</etc> and make sure it's	89	Example: temporarily change the timezone for the current process,
69	set back to F</> when the function returns:	90	ensuring it will be reset when the C<if> scope is exited:
70		91
71	sub dosomething {	92	use Guard;
72	scope_guard { chdir "/" };	93	use POSIX ();
73	chdir "/etc";
74		94
75	...	95	if ($need_to_switch_tz) {
		96	# make sure we call tzset after $ENV{TZ} has been restored
		97	scope_guard { POSIX::tzset };
		98
		99	# localise after the scope_guard, so it gets undone in time
		100	local $ENV{TZ} = "Europe/London";
		101	POSIX::tzset;
		102
		103	# do something with the new timezone
76	}	104	}
77		105
78	=item my $guard = guard BLOCK	106	=item my $guard = guard BLOCK
79		107
80	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
81	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
82	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
83	destroyed, the BLOCK gets executed as with C<scope_guard>.	111	destroyed, the BLOCK gets executed as with C<scope_guard>.
84		112
85	The returned object can be copied as many times as you want.	113	See the EXCEPTIONS section for an explanation of how exceptions
86		114	(i.e. C<die>) are handled inside guard blocks.
87	See B<EXCEPTIONS>, below, for an explanation of exception handling
88	(C<die>) within guard blocks.
89		115
90	Example: acquire a Coro::Semaphore for a second by registering a	116	Example: acquire a Coro::Semaphore for a second by registering a
91	timer. The timer callback references the guard used to unlock it again.	117	timer. The timer callback references the guard used to unlock it
		118	again. (Please ignore the fact that C<Coro::Semaphore> has a C<guard>
		119	method that does this already):
92		120
		121	use Guard;
93	use AnyEvent;	122	use Coro::AnyEvent;
94	use Coro::Semaphore;	123	use Coro::Semaphore;
95		124
96	my $sem = new Coro::Semaphore;	125	my $sem = new Coro::Semaphore;
97		126
98	sub lock_1s {	127	sub lock_for_a_second {
99	$sem->down;	128	$sem->down;
100	my $guard = guard { $sem->up };	129	my $guard = guard { $sem->up };
101		130
102	my $timer;	131	Coro::AnyEvent::sleep 1;
103	$timer = AnyEvent->timer (after => 1, sub {	132
104	# do something	133	# $sem->up gets executed when returning
105	undef $sem;
106	undef $timer;
107	});
108	}	134	}
109		135
110	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<<
111	$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,
112	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
113	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
114	one gets executed will the lock be unlocked.	140	event watchers and only when the last one gets executed will the lock be
		141	unlocked. Using the C<guard>, you do not have to worry about catching all
		142	the places where you have to unlock the semaphore.
115		143
116	=item Guard::cancel $guard	144	=item $guard->cancel
117		145
118	Calling this function will "disable" the guard object returned by the	146	Calling this function will "disable" the guard object returned by the
119	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
120	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.
121		149
122	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
123	and later decide it is no longer needed.	151	called under fatal conditions and later decide it is no longer needed.
124		152
125	=cut	153	=cut
126		154
127	1;	155	1;
128		156
129	=back	157	=back
130		158
131	=head1 EXCEPTIONS	159	=head1 EXCEPTIONS
132		160
133	Guard blocks should not normally throw exceptions (e.g. C<die>), after	161	Guard blocks should not normally throw exceptions (that is, C<die>). After
134	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,
135	something truly exceptional is happening, a guard block should be allowed	163	if something truly exceptional is happening, a guard block should of
136	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
137	programmer certainly wants to know about those.	165	exceptions, and the programmer certainly wants to know about those.
138		166
139	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
140	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
141	let containing code handle the exception.	169	let containing code handle the exception.
142		170
143	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
144	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>
145	(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
146	event loops handle this case.	174	event loops handle this case.
147		175
		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.
		178
		179	The C<$@> variable will be restored to its value before the guard call in
		180	all cases, so guards will not disturb C<$@> in any way.
		181
148	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
149	not guaranteed, but right now, the exception will simply be ignored).	183	not guaranteed, but right now, the exception will simply be ignored).
150		184
151	The default for C<$Guard::DIED> is to call C<warn "$@">.
152
153	=head1 AUTHOR	185	=head1 AUTHOR
154		186
155	Marc Lehmann <schmorp@schmorp.de>	187	Marc Lehmann <schmorp@schmorp.de>
156	http://home.schmorp.de/	188	http://home.schmorp.de/
157		189
158	=head1 THANKS	190	=head1 THANKS
159		191
160	To Marco Maisenhelder, who reminded me of the C<$Guard::DIED> solution to	192	Thanks to Marco Maisenhelder, who reminded me of the C<$Guard::DIED>
161	the problem of exceptions.	193	solution to the problem of exceptions.
		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.
162		203
163	=cut	204	=cut
164		205

Diff Legend

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

Comparing Guard/Guard.pm (file contents): Revision 1.2 by root, Sat Dec 13 17:49:12 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.2 by root, Sat Dec 13 17:49:12 2008 UTC vs.
Revision 1.22 by root, Sun Jul 26 08:07:11 2009 UTC