Handler/Essex/Threaded.pm untested

filter: Statementstmt 0.0% 0 / 189 Branchbran 0.0% 0 / 82 Conditioncond 0.0% 0 / 5 MC/DCmcdc 0.0% 0 / 3 Subroutinesub 0.0% 0 / 12 Podpod 0.0% 0 / 10 totaltotal 0.0% 0 / 301 CC 42 SCAR 42.9
CC
42
Cov
0%
threaded_execute
156.0
_send_event_to_child
110.0
DESTROY
42.0
CRAP 72.9
1 package XML::Handler::Essex::Threaded;
2  
3 $VERSION = 0.000_1;
4  
5 =head1 NAME
6  
7 XML::Handler::Essex::Threaded - Threading support for perls >= 5.8.0
8  
9 =head1 SYNOPSIS
10  
11 =head1 DESCRIPTION
12  
13 Loaded only if XML::Handler::Essex detects that threads.pm is loaded
14  
15 =cut
16  
17 @ISA = qw( XML::Handler::Essex );
18  
19 use strict;
20  
21 use threads::shared;
22  
23 warn "Essex: threads enabled\n";
24  
25 sub DESTROY {
26 my $self = shift;
27 return unless $self->{IsChild};
28 warn "Essex $self: DESTROYing parent\n" if debugging;
29 {
30 lock @{$self->{Events}};
31 my @event : shared = ( SEPPUKU );
32 @{$self->{Events}} = ( \@event );
33 threads::shared::cond_signal( @{$self->{Events}} );
34 }
35 warn "Essex $self: waiting for child to exit\n" if debugging;
36 lock @{$self->{Results}};
37 until ( @{$self->{Results}} ) {
38 warn "Essex $self: cond_wait on Results\n" if debugging;
39 threads::shared::cond_wait( @{$self->{Results}} );
40 }
41 warn "Essex $self: child exited\n" if debugging;
42 }
43  
44 # This is design to have the parent block until the child finishes
45 # handling the event. This is because the child (and especially filters
46 # downstream of the child) are likely to be non-threadsafe. So we only
47 # allow the child to run when there's an event to process, and we block
48 # until it is finish.
49 sub _start_child {
50 my $self = shift;
51  
52 warn "Essex $self: starting child thread\n" if debugging;
53  
54 # the = [] is to give threads::shared something to chew on that
55 # won't make it throw up.
56 # We pass the type of the event or
57 # result in other variables because they don't need to be shared
58 # and sharing them can break bless()ing.
59 my @events: shared;
60 my @results: shared;
61 $self->{Events} = \@events;
62 $self->{Results} = \@results;
63  
64 # The BOD sync loop in threaded_execute will send us a thread started
65 # "result". Ignore it, other than to sync on it.
66 lock @{$self->{Results}};
67 $self->{Thread} = threads->create(
68 $self->can( "threaded_execute" ),
69 $self
70 );
71 warn "Essex $self: waiting for child thread to start\n" if debugging;
72 until ( @{$self->{Results}} ) {
73 warn "Essex $self: cond_wait on Results\n" if debugging;
74 threads::shared::cond_wait( @{$self->{Results}} );
75 }
76 @{$self->{Results}} = ();
77  
78 warn "Essex $self: child thread started\n" if debugging;
79 }
80  
81  
82 ## This next sub works around a limitation in 5.8.0's share() that
83 ## seems to prevent me from using it; I get core dumps when I try.
84 ## TODO: try again with 5.8.0.
85 sub _r_share {
86 my $t = reftype $_[0];
87  
88 return if ( tied $_[0] or "" ) eq "threads::shared::tie";
89  
90 unless ( $t ) {
91 my $foo: shared = $_[0];
92 $_[0] = $foo;
93 }
94 elsif ( $t eq "HASH" ) {
95 _r_share( $_ )
96 for values %{$_[0]};
97 my %foo: shared = %{$_[0]};
98 $_[0] = \%foo;
99 }
100 elsif ( $t eq "ARRAY" ) {
101 my @foo: shared = map _r_share( $_ ), @{$_[0]};
102 $_[0] = \@foo;
103 }
104 elsif ( $t eq "SCALAR" ) {
105 my $foo: shared = ${$_[0]};
106 $_[0] = \$foo;
107 }
108 else {
109 Carp::confess "Essex: can't share $t";
110 }
111 }
112  
113  
114 sub _send_event_to_child {
115 my $self = shift;
116  
117 $self->_start_child unless $self->{Thread};
118  
119 {
120 lock @{$self->{Events}};
121 for ( @{$self->{PendingEvents}}, \@_ ) {
122 _r_share( $_->[1] );
123 my @event: shared = @$_;
124  
125 warn "Essex $self: sending $event[0] => CHILD \n" if debugging;
126  
127 push @{$self->{Events}}, \@event;
128 }
129 @{$self->{PendingEvents}} = ();
130 warn "Essex $self: signalling Events\n" if debugging;
131 threads::shared::cond_signal( @{$self->{Events}} );
132 } # unlock
133  
134 # Receive result from child.
135 warn "Essex $self: waiting for result from child\n" if debugging;
136 lock @{$self->{Results}};
137 until (@{$self->{Results}} ) {
138 warn "Essex $self: cond_wait on Results\n" if debugging;
139 threads::shared::cond_wait( @{$self->{Results}} );
140 }
141  
142 my ( $result_type, $result );
143 do {
144 ( $result_type, $result ) = (
145 shift( @{$self->{Results}} ),
146 shift( @{$self->{Results}} ),
147 );
148  
149 warn "Essex $self: ",
150 @{$self->{Results}} ? "ignoring" : "got",
151 " $result_type result ",
152 defined $result ? "'$result'" : "undef",
153 " from child\n" if debugging;
154  
155 } while @{$self->{Results}};
156  
157 $result_type eq "exception"
158 ? die $result
159 : return $result;
160 }
161  
162  
163 sub _send_result_to_parent {
164 my $self = shift;
165  
166 return unless defined $self->{PendingResultType};
167  
168 warn "Essex $self: sending PARENT <= $self->{PendingResultType} result ",
169 defined $self->{PendingResult} ? "'$self->{PendingResult}'" : "undef",
170 "\n" if debugging;
171  
172 lock @{$self->{Results}};
173  
174 _r_share( $self->{PendingResult} );
175 push @{$self->{Results}}, @{$self}{qw( PendingResultType PendingResult)};
176 @$self{"PendingResultType","PendingResult"} = ();
177  
178 warn "Essex $self: signalling Results\n" if debugging;
179 threads::shared::cond_signal( @{$self->{Results}} );
180 }
181  
182  
183 # NOTE: returns \@event, whereas _send_event_to_child takes @event.
184 # This is to speed the queue fudging that threaded_execute does on
185 # start_document.
186 sub _recv_event_from_parent {
187 my $self = shift;
188  
189 my $event;
190  
191 die EOD . "\n"
192 if $self->{PendingResultType} eq "end_document";
193  
194 warn "Essex $self: getting event from parent\n" if debugging;
195 lock @{$self->{Events}};
196  
197 # only send a result if there's one to send and there are no
198 # events waiting.
199 # TODO when and if we allow multiple events to stack up:
200 # If there are events waiting, then we need to
201 # wait until the last event to send the result.
202 $self->_send_result_to_parent;
203 # if defined $self->{PendingResultType};# && ! @{$self->{Events}};
204  
205 # We don't block if there're already events; this is used
206 # at start_document because the execute routine scans the input
207 # until it sees the start_document, then queues up a new
208 # set_document_locator and start_document.
209 until ( @{$self->{Events}} ) {
210 warn "Essex $self: cond_wait on Events\n" if debugging;
211 threads::shared::cond_wait( @{$self->{Events}} );
212 }
213  
214 ## TODO: Lock Events? The parent should not be running now,
215 ## it should be waiting for results.
216  
217 return $self->SUPER::_recv_event_from_parent;
218 }
219  
220 # Result handling:
221 #
222 # We track the event just received so threaded_execute() can tell what
223 # to do when the main routine exits or throws an exception. If it was
224 #
225 # We don't know if execute() actually does anything, or if it will do
226 # anything if entered a second time, so we need to return the
227 # result here.
228 #
229 # BOD notes. We wait for the BOD here and not in _recv_event_from_parent
230 # because we can't be sure that main() will ever call _recv_event_from_parent.
231 # It might throw an exception or return a result instead. This has the
232 # side effect of making it seem like (to the programmer) the child thread
233 # is respawned each start_document() event: main() will not be entered until
234 # after the BOD is sent, and that's sent in start_document(). Whether or
235 # not that's good or bad depends on what's happening in main(), but it's
236 # a necessary implementation detail. It also reserves the right to actually
237 # implement threading that way one day, either as an option for the caller
238 # or due to some shift in perl's threading implementation.
239 sub threaded_execute {
240 my $self = shift;
241  
242 $self->{IsChild};
243 threads->self->detach;
244  
245 # This thread only exits if it gets an undefined eventtype. This is
246 # to avoid the extreme cost of starting a thread on every document if
247 # the caller is handling a series of documents.
248 my $pending_end_document_result = "Essex: default end_document result";
249 $self->{PendingResultType} =
250 $self->{PendingResult} = "thread started";
251  
252 EXECUTE:
253 while (1) {
254 while (1) { # Wait for BOD.
255 if ( $self->{PendingResultType} eq "end_document" ) {
256 $self->{PendingResultType} = "end_document again";
257 $self->{PendingResult} = $pending_end_document_result;
258 $pending_end_document_result
259 = "Essex: default end_document result";
260 }
261  
262 my $event = eval { $self->_recv_event_from_parent };
263  
264 unless ( defined $event ) {
265 if ( $@ eq EOD . "\n" ) {
266 lock @{$self->{Events}};
267 shift @{$self->{Events}};
268 }
269 elsif ( $@ eq BOD . "\n") {
270 lock @{$self->{Events}};
271 shift @{$self->{Events}};
272 last;
273 }
274 elsif ( $@ eq SEPPUKU . "\n") {
275 last EXECUTE;
276 }
277 else {
278 die $@;
279 }
280 }
281  
282 }
283  
284 $pending_end_document_result = "Essex: default end_document result";
285  
286 eval {
287 my $event;
288  
289 undef $pending_end_document_result;
290 warn "Essex $self: running execute()\n" if debugging;
291 my $r = $self->SUPER::execute( @_ );
292 warn "Essex $self: execute() exited with ",
293 defined $r ? "'$r'" : "undef",
294 "\n"
295 if debugging;
296  
297 $pending_end_document_result = $r;
298 1;
299 } or do {
300 warn "Essex $self: execute() exited with exception $@\n"
301 if debugging;
302 if ( $@ eq EOD . "\n") {
303 lock @{$self->{Events}};
304 shift @{$self->{Events}};
305 }
306 elsif ( $@ eq SEPPUKU . "\n") {
307 last;
308 }
309 else {
310 $self->{PendingResultType} = "exception";
311 $self->{PendingResult} = $@;
312 }
313 };
314 }
315  
316 $self->{PendingResultType} =
317 $self->{PendingResult} = SEPPUKU;
318 $self->_send_result_to_parent;
319 }
320  
321 # Hopefully, this handles inline set_document_locator events relatively
322 # gracefully, by queueing them up until the next event arrives. This is
323 # necessary because set_document_locator events can arrive *before* the
324 # start_document, and we need to wait for the next event to see whether
325 # to insert the BOD before the set_document_locator. This is all so that
326 # the initial set_document_locator event(s) will arrive before the
327 # start_document event in the main() routine, given that we need to
328 # send the BOD psuedo event in case the main() routine is still running.
329 sub set_document_locator {
330 push @{shift->{PendingEvents}}, [ "set_document_locator", @_ ];
331 return "Essex: document locator queued";
332 }
333  
334  
335 sub start_document {
336 my $self = shift;
337  
338 unshift @{$self->{PendingEvents}}, [ BOD ];
339 $self->SUPER::start_document( @_ );
340 }
341  
342  
343 sub end_document {
344 my $self = shift;
345 ## Must send EOD after the end_document so that we get the end_document
346 ## result back first otherwise it would be lost because
347 ## _recv_event_from_parent does not send results back if there are any
348 ## other events in the queue. If this were not so, we could add a hack
349 ## here to queue up both end_document and EOD at once.
350 my $r = _send_event_to_child( $self, "end_document", @_ );
351  
352 my @event: shared = ( EOD );
353 lock @{$self->{Events}};
354 push @{$self->{Events}}, \@event;
355 threads::shared::cond_signal( @{$self->{Events}} );
356  
357 return $r;
358 }
359  
360  
361 =head1 LIMITATIONS
362  
363 =head1 COPYRIGHT
364  
365 Copyright 2002, R. Barrie Slaymaker, Jr., All Rights Reserved
366  
367 =head1 LICENSE
368  
369 You may use this module under the terms of the BSD, Artistic, oir GPL licenses,
370 any version.
371  
372 =head1 AUTHOR
373  
374 Barrie Slaymaker <barries@slaysys.com>
375  
376 =cut
377  
378 1;
379 =head1 LIMITATIONS
380  
381 =head1 COPYRIGHT
382  
383 Copyright 2003, R. Barrie Slaymaker, Jr., All Rights Reserved
384  
385 =head1 LICENSE
386  
387 You may use this module under the terms of the BSD, Artistic, oir GPL licenses,
388 any version.
389  
390 =head1 AUTHOR
391  
392 Barrie Slaymaker <barries@slaysys.com>
393  
394 =cut
395  
396 1;