blib/lib/Eval/Reversible.pm

filter: Statementstmt 95.7% 67 / 70 Branchbran 79.1% 19 / 24 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 88.8% 16 / 18 Podpod 100% 6 / 6 totaltotal 91.5% 108 / 118 CC 13 SCAR 11.2
CC
13
Cov
91%
run_reversibly
7.2
to_undo
3.0
run_undo
3.0
CRAP 3.1
↑ Summary
1 package Eval::Reversible;
2  
3 3 our $AUTHORITY = 'cpan:GSG';
4 # ABSTRACT: Evals with undo stacks
5 3 ▶use version;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 3 our $VERSION = 'v0.900.1'; # VERSION
7  
8 3 ▶use v5.10;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 3 ▶use Moo;
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 3 ▶use Types::Standard qw( Bool Str ArrayRef CodeRef );
Subroutine BEGIN: called CC=1 SCAR=0.0
12 3 ▶use MooX::HandlesVia;
Subroutine BEGIN: called CC=1 SCAR=0.0
13  
14 3 ▶use Scalar::Util qw( blessed );
Subroutine BEGIN: called CC=1 SCAR=0.0
15  
16 3 ▶use namespace::clean; # don't export the above
Subroutine BEGIN: called CC=1 SCAR=0.0
17  
18 # Goes after namespace::clean, since we actually want to include this into our
19 # namespace
20 3 ▶use Exporter 'import';
Subroutine BEGIN: called CC=1 SCAR=0.0
21  
22 3 ▶BEGIN {
Subroutine BEGIN: called CC=1 SCAR=0.0
23 3 our @EXPORT_OK = qw( to_undo reversibly );
24 };
25  
26 3 our $Current_Reversible;
27  
28 #pod =head1 SYNOPSIS
29 #pod
30 #pod use Eval::Reversible;
31 #pod
32 #pod my $reversible = Eval::Reversible->new(
33 #pod failure_warning => "Undoing actions..",
34 #pod );
35 #pod
36 #pod $reversible->run_reversibly(sub {
37 #pod # Do something with a side effect
38 #pod open my $fh, '>', '/tmp/file' or die;
39 #pod
40 #pod # Specify how that side effect can be undone
41 #pod # (assuming '/tmp/file' did not exist before)
42 #pod $reversible->add_undo(sub { close $fh; unlink '/tmp/file' });
43 #pod
44 #pod operation_that_might_die($fh);
45 #pod operation_that_might_get_SIGINTed($fh);
46 #pod
47 #pod close $fh;
48 #pod unlink '/tmp/file';
49 #pod
50 #pod $reversible->clear_undo;
51 #pod $reversible->failure_warning("Wasn't quite finished yet...");
52 #pod
53 #pod another_operation_that_might_die;
54 #pod $reversible->add_undo(sub { foobar; });
55 #pod
56 #pod $reversible->disarm;
57 #pod
58 #pod # This could die without an undo stack
59 #pod another_operation_that_might_die;
60 #pod
61 #pod $reversible->arm;
62 #pod
63 #pod # Previous undo stack back in play
64 #pod });
65 #pod
66 #pod # Alternative caller
67 #pod Eval::Reversible->run_reversibly(sub {
68 #pod my $reversible = $_[0];
69 #pod
70 #pod $reversible->add_undo(...);
71 #pod ...
72 #pod });
73 #pod
74 #pod # Alternative function interface
75 #pod reversibly {
76 #pod to_undo { ... };
77 #pod die;
78 #pod } 'Failed to run code; undoing...';
79 #pod
80 #pod =head1 DESCRIPTION
81 #pod
82 #pod Run code and automatically reverse their side effects if the code fails. This is done by
83 #pod way of an undo stack. By calling L</add_undo> right after a side effect, the effect is
84 #pod undone on the event that the L</run_reversibly> sub dies. For example:
85 #pod
86 #pod $reversible->run_reversibly(sub {
87 #pod print "hello\n";
88 #pod $reversible->add_undo(sub { print "goodbye\n" });
89 #pod die "uh oh\n" if $something_bad;
90 #pod });
91 #pod
92 #pod This prints "hello" if C<$something_bad> is false. If it's true, then both "hello" and
93 #pod "goodbye" are printed and the exception "uh oh" is rethrown.
94 #pod
95 #pod Upon failure, any code refs provided by calling L</add_undo> are executed in reverse
96 #pod order. Conceptually, we're unwinding the stack of side effects that C<$code> performed
97 #pod up to the point of failure.
98 #pod
99 #pod =head1 ATTRIBUTES
100 #pod
101 #pod =head2 failure_warning
102 #pod
103 #pod This is the message that will warn as soon as the operation failed. After this, the undo
104 #pod stack is unwound, and the exception is rethrown. Default is no message.
105 #pod
106 #pod =cut
107  
108 3 has failure_warning => (
109 is => 'rw',
110 isa => Str,
111 required => 0,
112 );
113  
114 #pod =head2 undo_stack
115 #pod
116 #pod The undo stack, managed in LIFO order, as an arrayref of coderefs.
117 #pod
118 #pod This attribute has the following handles, which is what you should really interact with:
119 #pod
120 #pod =head3 add_undo
121 #pod
122 #pod Adds another coderef to the undo stack via push.
123 #pod
124 #pod =head3 pop_undo
125 #pod
126 #pod Removes the last coderef and returns it via pop.
127 #pod
128 #pod =head3 clear_undo
129 #pod
130 #pod Clears all undo coderefs from the stack. Handy if the undo stack needs to be cleared out
131 #pod early if a "point of no return" has been reached prior the end of the L</run_reversibly>
132 #pod code block. Alternatively, L</disarm> could be used, but it doesn't clear the existing
133 #pod stack.
134 #pod
135 #pod =head3 is_undo_empty
136 #pod
137 #pod Returns a boolean that indicates whether the undo stack is empty or not.
138 #pod
139 #pod =cut
140  
141 has undo_stack => (
142 is => 'ro',
143 isa => ArrayRef[CodeRef],
144 required => 1,
145 9 ▶ default => sub { [] },
Subroutine __ANON__: called CC=1 SCAR=0.0
146 3 handles_via => 'Array',
147 handles => {
148 add_undo => 'push',
149 pop_undo => 'pop',
150 clear_undo => 'clear',
151 is_undo_empty => 'is_empty',
152 },
153 );
154  
155 #pod =head2 armed
156 #pod
157 #pod Boolean that controls if L</run_reversibly> code blocks will actually run the undo stack
158 #pod upon failure. Turned on by default, but this can be enabled and disabled at will before
159 #pod or inside the code block.
160 #pod
161 #pod Has the following handles:
162 #pod
163 #pod =head3 arm
164 #pod
165 #pod Arms the undo stack.
166 #pod
167 #pod =head3 disarm
168 #pod
169 #pod Disarms the undo stack.
170 #pod
171 #pod =cut
172  
173 # XXX: MooX::HandlesVia can't really handle write operations on non-refs. So, we're
174 # faking the handles here.
175  
176 3 has armed => (
177 is => 'rw',
178 isa => Bool,
179 required => 0,
180 default => 1,
181 );
182  
183 1 ▶sub arm { shift->armed(1) }
Subroutine arm: called CC=1 SCAR=0.0
Pod documented
184 2 ▶sub disarm { shift->armed(0) }
Subroutine disarm: called CC=1 SCAR=0.0
Pod documented
185  
186 #pod =head1 METHODS
187 #pod
188 #pod =head2 run_reversibly
189 #pod
190 #pod $reversible->run_reversibly($code);
191 #pod Eval::Reversible->run_reversibly($code);
192 #pod
193 #pod Executes a code reference (C<$code>) allowing operations with side effects to be
194 #pod automatically reversed if C<$code> fails or is interrupted. Automatically clears the
195 #pod undo stack before the start of the code block.
196 #pod
197 #pod Can be called as a class method, which will auto-create a new object, and pass it along
198 #pod as the first parameter to C<$code>.
199 #pod
200 #pod If C<$code> is interrupted with SIGINT, the side effects are undone and an
201 #pod exception "SIGINT\n" is thrown.
202 #pod
203 #pod =cut
204  
205 13 ▶sub run_reversibly {
Subroutine run_reversibly: called CC=7 SCAR=19.7
Pod documented
206 13 my ($self, $code) = @_;
207 13 ▶ die "Cannot call run_reversibly without a code block!" unless $code;
Branch: 1 branch
BranchTrueFalseTotal
unless $code 0 13 13
208  
209 13 ▶ unless (blessed $self) {
Branch: 1 branch
BranchTrueFalseTotal
unless (builtin::blessed($self)) 1 12 13
210 1 my $class = $self;
211 1 $self = $class->new;
212 }
213  
214 13 $self->clear_undo;
215  
216 # If disarmed, just run the code without eval
217 13 ▶ unless ($self->armed) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->armed) 1 12 13
218 1 $self->$code();
219 0 return;
220 }
221  
222 0 ▶ local $SIG{INT} = sub { die "SIGINT\n" };
Subroutine __ANON__: not called CC=1 SCAR=1.2
223 0 ▶ local $SIG{TERM} = sub { die "SIGTERM\n" };
Subroutine __ANON__: not called CC=1 SCAR=1.2
224  
225 12 eval { $self->$code() };
226 12 ▶ if ( my $exception = $@ ) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $exception = $@) 8 4 12
227 # Re-check this because it may change inside the code block
228 8 ▶ if ($self->armed) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->armed) { } 7 1 8
229 7 ▶ warn $self->failure_warning if $self->failure_warning;
Branch: 1 branch
BranchTrueFalseTotal
if $self->failure_warning 0 7 7
230 7 $self->run_undo;
231  
232 # Re-throw the exception, with commentary
233 7 die "\nThe exception that caused rollback was: $exception";
234 }
235 else {
236 # Just die like it wasn't even in an eval
237 1 die $exception;
238 }
239 }
240 }
241  
242 #pod =head2 run_undo
243 #pod
244 #pod $reversible->run_undo;
245 #pod
246 #pod Runs the undo stack thus far. Always runs the bottom of the stack first (LIFO order). A
247 #pod finished run will clear out the stack via pop.
248 #pod
249 #pod Can be called outside of L</run_reversibly> if the eval was successful, but the undo
250 #pod stack still needs to be ran.
251 #pod
252 #pod =cut
253  
254 8 ▶sub run_undo {
Subroutine run_undo: called CC=3 SCAR=11.0
Pod documented
255 8 my ($self) = @_;
256  
257 8 ▶ while (my $undo = $self->pop_undo) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $undo = $self->pop_undo) 11 8 19
258 11 eval { $self->$undo() };
259 11 ▶ warn "Exception during undo: $@" if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 11 11
260 }
261 }
262  
263 3 1;
264  
265 #pod =head1 EXPORTABLE FUNCTIONS
266 #pod
267 #pod Eval::Reversible also supports an exportable function interface. Though its usage is
268 #pod somewhat legacy, the functions are prototyped for reduced sigilla.
269 #pod
270 #pod None of the functions are exported by default.
271 #pod
272 #pod =head2 reversibly
273 #pod
274 #pod reversibly {
275 #pod ...
276 #pod } 'Failure message';
277 #pod
278 #pod Creates a new localized Eval::Reversible object and calls L</run_reversibly> on it. An
279 #pod optional failure message can be added to the end of coderef.
280 #pod
281 #pod =cut
282  
283 3 ▶sub reversibly (&;$) {
Subroutine reversibly: called CC=3 SCAR=11.0
Pod documented
284 3 my ($code, $fail_msg) = @_;
285 3 ▶ die "Cannot call reversibly without a code block!" unless $code;
Branch: 1 branch
BranchTrueFalseTotal
unless $code 0 3 3
286  
287 3 local $Current_Reversible = __PACKAGE__->new;
288 3 ▶ $Current_Reversible->failure_warning($fail_msg) if defined $fail_msg;
Branch: 1 branch
BranchTrueFalseTotal
if defined $fail_msg 2 1 3
289 3 $Current_Reversible->run_reversibly($code);
290 }
291  
292 #pod =head2 to_undo
293 #pod
294 #pod # Only inside of a reversibly block
295 #pod to_undo { rollback_everything };
296 #pod
297 #pod Adds to the existing undo stack. Dies if called outside of a L</reversibly> block.
298 #pod
299 #pod =cut
300  
301 11 ▶sub to_undo (&) {
Subroutine to_undo: called CC=3 SCAR=11.0
Pod documented
302 11 my ($code) = @_;
303 11 ▶ die "Cannot call to_undo without a code block!" unless $code;
Branch: 1 branch
BranchTrueFalseTotal
unless $code 0 11 11
304 11 ▶ die "Cannot call to_undo outside of an reversibly block!" unless $Current_Reversible;
Branch: 1 branch
BranchTrueFalseTotal
unless $Eval::Reversible::Current_Reversible 2 9 11
305  
306 9 $Current_Reversible->add_undo($code);
307 }
308  
309 #pod =head1 SEE ALSO
310 #pod
311 #pod L<Scope::Guard>, L<Data::Transactional>, L<Object::Transaction>.
312 #pod
313 #pod =cut
314  
315 3 1;
316  
317 __END__
↑ Summary