| 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; |