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

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

Diff Legend

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

Comparing Guard/Guard.pm (file contents): Revision 1.1 by root, Sat Dec 13 17:37:22 2008 UTC vs. Revision 1.25 by root, Thu Nov 20 18:13:58 2014 UTC

Diff Legend

Comparing Guard/Guard.pm (file contents):
Revision 1.1 by root, Sat Dec 13 17:37:22 2008 UTC vs.
Revision 1.25 by root, Thu Nov 20 18:13:58 2014 UTC