ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Guard/README
(Generate patch)

Comparing Guard/README (file contents):
Revision 1.1 by root, Sat Dec 13 17:37:22 2008 UTC vs.
Revision 1.2 by root, Sat Dec 13 17:50:29 2008 UTC

1NAME 1NAME
2 Guard - convert between different representations of perl 2 Guard - safe cleanup blocks
3 scalars
4 3
5SYNOPSIS 4SYNOPSIS
6 use Guard; 5 use Guard;
7 6
8DESCRIPTION 7DESCRIPTION
9 This module exports various internal perl methods that change the 8 This module implements so-called "guards". A guard is something (usually
10 internal representation or state of a perl scalar. All of these work 9 an object) that "guards" a resource, ensuring that it is cleaned up when
11 in-place, that is, they modify their scalar argument. No functions are 10 expected.
12 exported by default.
13 11
14 The following export tags exist: 12 Specifically, this module supports two different types of guards: guard
13 objects, which execute a given code block when destroyed, and scoped
14 guards, which are tied to the scope exit.
15 15
16 :utf8 all functions with utf8 in their name 16FUNCTIONS
17 :taint all functions with taint in their name 17 This module currently exports the "scope_guard" and "guard" functions by
18 :refcnt all functions with refcnt in their name 18 default.
19 :ok all *ok-functions.
20 19
21 utf8 scalar[, mode] 20 scope_guard BLOCK
22 Returns true when the given scalar is marked as utf8, false 21 Registers a block that is executed when the current scope (block,
23 otherwise. If the optional mode argument is given, also forces the 22 function, method, eval etc.) is exited.
24 interpretation of the string to utf8 (mode true) or plain bytes
25 (mode false). The actual (byte-) content is not changed. The return
26 value always reflects the state before any modification is done.
27 23
28 This function is useful when you "import" utf8-data into perl, or 24 The description below sounds a bit complicated, but that's just
29 when some external function (e.g. storing/retrieving from a 25 because "scope_guard" tries to get even corner cases "right": the
30 database) removes the utf8-flag. 26 goal is to provide you with a rock solid clean up tool.
31 27
32 utf8_on scalar 28 This is similar to this code fragment:
33 Similar to "utf8 scalar, 1", but additionally returns the scalar
34 (the argument is still modified in-place).
35 29
36 utf8_off scalar 30 eval ... code following scope_guard ...
37 Similar to "utf8 scalar, 0", but additionally returns the scalar 31 {
38 (the argument is still modified in-place). 32 local $@;
33 eval BLOCK;
34 eval { $Guard::DIED->() } if $@;
35 }
36 die if $@;
39 37
40 utf8_valid scalar [Perl 5.7] 38 Except it is much faster, and the whole thing gets executed even
41 Returns true if the bytes inside the scalar form a valid utf8 39 when the BLOCK calls "exit", "goto", "last" or escapes via other
42 string, false otherwise (the check is independent of the actual 40 means.
43 encoding perl thinks the string is in).
44 41
45 utf8_upgrade scalar 42 See EXCEPTIONS, below, for an explanation of exception handling
46 Convert the string content of the scalar in-place to its 43 ("die") within guard blocks.
47 UTF8-encoded form (and also returns it).
48 44
49 utf8_downgrade scalar[, fail_ok=0] 45 Example: Temporarily change the directory to /etc and make sure it's
50 Attempt to convert the string content of the scalar from 46 set back to / when the function returns:
51 UTF8-encoded to ISO-8859-1. This may not be possible if the string
52 contains characters that cannot be represented in a single byte; if
53 this is the case, it leaves the scalar unchanged and either returns
54 false or, if "fail_ok" is not true (the default), croaks.
55 47
56 utf8_encode scalar 48 sub dosomething {
57 Convert the string value of the scalar to UTF8-encoded, but then 49 scope_guard { chdir "/" };
58 turn off the "SvUTF8" flag so that it looks like bytes to perl 50 chdir "/etc";
59 again. (Might be removed in future versions).
60 51
61 utf8_length scalar 52 ...
62 Returns the number of characters in the string, counting wide UTF8 53 }
63 characters as a single character, independent of wether the scalar
64 is marked as containing bytes or mulitbyte characters.
65 54
66 unmagic scalar, type 55 my $guard = guard BLOCK
67 Remove the specified magic from the scalar (DANGEROUS!). 56 Behaves the same as "scope_guard", except that instead of executing
57 the block on scope exit, it returns an object whose lifetime
58 determines when the BLOCK gets executed: when the last reference to
59 the object gets destroyed, the BLOCK gets executed as with
60 "scope_guard".
68 61
69 weaken scalar 62 The returned object can be copied as many times as you want.
70 Weaken a reference. (See also WeakRef).
71 63
72 taint scalar 64 See EXCEPTIONS, below, for an explanation of exception handling
73 Taint the scalar. 65 ("die") within guard blocks.
74 66
75 tainted scalar 67 Example: acquire a Coro::Semaphore for a second by registering a
76 returns true when the scalar is tainted, false otherwise. 68 timer. The timer callback references the guard used to unlock it
69 again.
77 70
78 untaint scalar 71 use AnyEvent;
79 Remove the tainted flag from the specified scalar. 72 use Coro::Semaphore;
80 73
81 grow scalar, newlen 74 my $sem = new Coro::Semaphore;
82 Sets the memory area used for the scalar to the given length, if the
83 current length is less than the new value. This does not affect the
84 contents of the scalar, but is only useful to "pre-allocate" memory
85 space if you know the scalar will grow. The return value is the
86 modified scalar (the scalar is modified in-place).
87 75
88 refcnt scalar[, newrefcnt] 76 sub lock_1s {
89 Returns the current reference count of the given scalar and 77 $sem->down;
90 optionally sets it to the given reference count. 78 my $guard = guard { $sem->up };
91 79
92 refcnt_inc scalar 80 my $timer;
93 Increments the reference count of the given scalar inplace. 81 $timer = AnyEvent->timer (after => 1, sub {
82 # do something
83 undef $sem;
84 undef $timer;
85 });
86 }
94 87
95 refcnt_dec scalar 88 The advantage of doing this with a guard instead of simply calling
96 Decrements the reference count of the given scalar inplace. Use 89 "$sem->down" in the callback is that you can opt not to create the
97 "weaken" instead if you understand what this function is fore. 90 timer, or your code can throw an exception before it can create the
98 Better yet: don't use this module in this case. 91 timer, or you can create multiple timers or other event watchers and
92 only when the last one gets executed will the lock be unlocked.
99 93
100 refcnt_rv scalar[, newrefcnt] 94 Guard::cancel $guard
101 Works like "refcnt", but dereferences the given reference first. 95 Calling this function will "disable" the guard object returned by
102 This is useful to find the reference count of arrays or hashes, 96 the "guard" function, i.e. it will free the BLOCK originally passed
103 which cnanot be passed directly. Remember that taking a reference of 97 to "guard "and will arrange for the BLOCK not to be executed.
104 some object increases it's reference count, so the reference count
105 used by the *_rv-functions tend to be one higher.
106 98
107 refcnt_inc_rv scalar 99 This can be useful when you use "guard" to create a fatal cleanup
108 Works like "refcnt_inc", but dereferences the given reference first. 100 handler and later decide it is no longer needed.
109 101
110 refcnt_dec_rv scalar 102EXCEPTIONS
111 Works like "refcnt_dec", but dereferences the given reference first. 103 Guard blocks should not normally throw exceptions (e.g. "die"), after
104 all, they are usually used to clean up after such exceptions. However,
105 if something truly exceptional is happening, a guard block should be
106 allowed to die. Also, programming errors are a large source of
107 exceptions, and the programmer certainly wants to know about those.
112 108
113 ok scalar 109 Since in most cases, the block executing when the guard gets executes
114 uok scalar 110 does not know or does not care about the guard blocks, it makes little
115 rok scalar 111 sense to let containing code handle the exception.
116 pok scalar
117 nok scalar
118 niok scalar
119 Calls SvOK, SvUOK, SvROK, SvPOK, SvNOK or SvNIOK on the given
120 scalar, respectively.
121 112
122 CANDIDATES FOR FUTURE RELEASES 113 Therefore, whenever a guard block throws an exception, it will be
123 The following API functions (perlapi) are considered for future 114 caught, and this module will call the code reference stored in
124 inclusion in this module If you want them, write me. 115 $Guard::DIED (with $@ set to the actual exception), which is similar to
116 how most event loops handle this case.
125 117
126 sv_upgrade 118 The code reference stored in $Guard::DIED should not die (behaviour is
127 sv_pvn_force 119 not guaranteed, but right now, the exception will simply be ignored).
128 sv_pvutf8n_force 120
129 the sv2xx family 121 The default for $Guard::DIED is to call "warn "$@"".
130 122
131AUTHOR 123AUTHOR
132 Marc Lehmann <schmorp@schmorp.de> 124 Marc Lehmann <schmorp@schmorp.de>
133 http://home.schmorp.de/ 125 http://home.schmorp.de/
134 126
127THANKS
128 To Marco Maisenhelder, who reminded me of the $Guard::DIED solution to
129 the problem of exceptions.
130

Diff Legend

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