| 1 | package subs::parallel; | ||
| 2 | |||
| 3 | 2 | ▶ | use warnings; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 4 | 2 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 5 | |||
| 6 | 0 | ▶ | use threads; |
|
Subroutine
BEGIN: called CC=1 SCAR=2.6
| |||
| 7 | use vars qw/@ISA @EXPORT $AUTOLOAD/; | ||
| 8 | use Attribute::Handlers; | ||
| 9 | use Scalar::Util qw/set_prototype/; | ||
| 10 | |||
| 11 | =head1 NAME | ||
| 12 | |||
| 13 | subs::parallel - enables subroutines to seamlessly run in parallel | ||
| 14 | |||
| 15 | =head1 VERSION | ||
| 16 | |||
| 17 | Version 0.09 | ||
| 18 | |||
| 19 | =cut | ||
| 20 | |||
| 21 | require Exporter; | ||
| 22 | @ISA = qw(Exporter); | ||
| 23 | @EXPORT = qw(parallelize parallelize_sub parallelize_coderef); | ||
| 24 | |||
| 25 | our $VERSION = '0.09'; | ||
| 26 | |||
| 27 | use overload | ||
| 28 | '""' => \&_deref, | ||
| 29 | '0+' => \&_deref, | ||
| 30 | 'bool'=> \&_deref, | ||
| 31 | '${}' => \&_deref, | ||
| 32 | '@{}' => \&_deref, | ||
| 33 | '%{}' => \&_deref, | ||
| 34 | '&{}' => \&_deref, | ||
| 35 | '*{}' => \&_deref, | ||
| 36 | fallback => 1; | ||
| 37 | |||
| 38 | =head1 SYNOPSIS | ||
| 39 | |||
| 40 | use subs::parallel; | ||
| 41 | |||
| 42 | sub foo : Parallel { | ||
| 43 | # foo runs in parallel | ||
| 44 | } | ||
| 45 | |||
| 46 | parallelize_sub('bar'); | ||
| 47 | # subroutine named bar now runs in parallel | ||
| 48 | |||
| 49 | my $foo = foo(); # returns immediately | ||
| 50 | my $bar = bar(); # also returns immediately | ||
| 51 | |||
| 52 | # now it might block waiting for both to finish | ||
| 53 | if ($foo == $bar) { | ||
| 54 | ... | ||
| 55 | } | ||
| 56 | |||
| 57 | |||
| 58 | my $baz = parallelize { ... code ... }; # returns immediately | ||
| 59 | |||
| 60 | ... | ||
| 61 | |||
| 62 | print "baz: $baz\n"; # if it's still running, blocks until it finishes | ||
| 63 | |||
| 64 | |||
| 65 | # it can be done to anonymous subs or any other coderefs too | ||
| 66 | my $anon = sub { ... more code ... }; | ||
| 67 | my $parallel_coderef = parallelize_coderef($anon); | ||
| 68 | |||
| 69 | my $foobar = $parallel_coderef->('arg'); # returns immediately | ||
| 70 | |||
| 71 | ... | ||
| 72 | |||
| 73 | # sub should return an object, no problem | ||
| 74 | $foobar->do_something_else(); # blocks until it finishes running | ||
| 75 | |||
| 76 | =head1 DESCRIPTION | ||
| 77 | |||
| 78 | This module gives Perl programmers the ability to easily and conveniently | ||
| 79 | create multi-threaded applications through B<parallel subroutines>. | ||
| 80 | |||
| 81 | Parallel subroutines are just plain old subroutines which happen to run in | ||
| 82 | another thread. When called, they return immediately to the calling thread but | ||
| 83 | keep running in another. When its return value is needed somewhere, the | ||
| 84 | returned value is transparently fetched. If the thread is still running, the | ||
| 85 | code blocks waiting for it to finish (since the program can't go on without a | ||
| 86 | value and keep being transparent). | ||
| 87 | |||
| 88 | So, as it's possible to notice, the module interface aims to be as simple | ||
| 89 | as possible. In fact, it works in such a way that, aside from the | ||
| 90 | I<parallelizing> directives, you wouldn't be able to tell it's a multi-threaded | ||
| 91 | application. All the thread handling (which isn't I<that> complicated, really) | ||
| 92 | is done automagically. | ||
| 93 | |||
| 94 | It should work for anything that's thread safe - even for subroutines whose | ||
| 95 | return values are not usually available across thread boundaries (for example, | ||
| 96 | usually, you can't C<share> an object, but this module makes it possible to | ||
| 97 | return them without any problems, provided they're thread safe). | ||
| 98 | |||
| 99 | =head1 MOTIVATION | ||
| 100 | |||
| 101 | The main reason behind this module was the fact that Perl threads are not | ||
| 102 | widely used. Some could argue that this might happen because Perl threads are | ||
| 103 | not very practical to use. Others could say that the restrictions imposed by | ||
| 104 | the use of threads (you can't pass arbitrary data structures between threads). | ||
| 105 | |||
| 106 | The latter issue is out of my reach. But, through the use of already existing | ||
| 107 | features, it was possible to mask it a little bit. So you can return anything | ||
| 108 | from your parallelized subroutines, but this is just some maybe unknown feature | ||
| 109 | of C<threads->join>. | ||
| 110 | |||
| 111 | The first issue is the main aim of this module: provide an extremely simple way | ||
| 112 | to make multi-threaded applications. Along this near-future reality of a | ||
| 113 | majority of dual-core computers, multi-threading might become the factor that | ||
| 114 | distiguishes good from bad software. | ||
| 115 | |||
| 116 | But I would be dishonest if I didn't note that some part of the effort was | ||
| 117 | driven by the will to prove it could be done in Perl. | ||
| 118 | |||
| 119 | =head1 ATTRIBUTE HANDLING | ||
| 120 | |||
| 121 | The most practical way of using this module's features is through attrubutes. | ||
| 122 | This snippet ilustrates how to do it: | ||
| 123 | |||
| 124 | use subs::parallel; | ||
| 125 | |||
| 126 | sub foobar : Parallel { | ||
| 127 | # do stuff | ||
| 128 | } | ||
| 129 | |||
| 130 | That way, C<foobar> is declared as a B<parallel subroutine>. This should have | ||
| 131 | exactly the same effect as using the C<parallelize_sub> below, but is cleaner | ||
| 132 | and more convenient. | ||
| 133 | |||
| 134 | =head1 EXPORTS | ||
| 135 | |||
| 136 | The C<parallelize>, C<parallelize_sub> and C<parallelize_coderef> subroutines | ||
| 137 | are exported. If you have problems with that, you're free to: | ||
| 138 | |||
| 139 | use subs::parallel (); | ||
| 140 | |||
| 141 | =head1 FUNCTIONS | ||
| 142 | |||
| 143 | All the three functions available work similarly, implementing the idea of | ||
| 144 | B<parallelized subroutines> as explained above. Nevertheless, here's a brief | ||
| 145 | explanation of each of them. | ||
| 146 | |||
| 147 | =head2 parallelize { BLOCK } | ||
| 148 | |||
| 149 | Starts running the specified block of code in parallel B<immediately>. | ||
| 150 | The snippet below ilustrates this concept: | ||
| 151 | |||
| 152 | use subs::parallel; | ||
| 153 | |||
| 154 | my $foo = parallelize { | ||
| 155 | # do stuff here | ||
| 156 | }; | ||
| 157 | |||
| 158 | my $bar = parallelize { | ||
| 159 | # do even more stuff | ||
| 160 | }; | ||
| 161 | |||
| 162 | # now we wait for them to finish | ||
| 163 | print "$foo, $bar\n"; | ||
| 164 | |||
| 165 | =cut | ||
| 166 | |||
| 167 | # parallelizes and runs a block of code / coderef | ||
| 168 | sub parallelize (&) { parallelize_coderef(shift)->() } | ||
| 169 | |||
| 170 | =head2 parallelize_sub(STRING) | ||
| 171 | |||
| 172 | Transforms the named subroutine into a B<parallel subroutine>. After this | ||
| 173 | modification, every it's called, it will run inside another thread and return | ||
| 174 | immediately to the caller. | ||
| 175 | |||
| 176 | The snippet below ilustrates this concept: | ||
| 177 | |||
| 178 | use subs::parallel; | ||
| 179 | |||
| 180 | sub blocking_stuff { | ||
| 181 | # do blocking stuff | ||
| 182 | } | ||
| 183 | |||
| 184 | blocking_stuff(); # this blocks | ||
| 185 | |||
| 186 | parallelize_sub('blocking_stuff'); | ||
| 187 | |||
| 188 | blocking_stuff(); | ||
| 189 | # now it returns immediately and the return values are discarded | ||
| 190 | |||
| 191 | Note that, you can I<parallelize> named subroutines inside other packages: | ||
| 192 | |||
| 193 | parallelize_sub('Other::Package::function'); | ||
| 194 | |||
| 195 | =cut | ||
| 196 | |||
| 197 | # parallelizing subroutines by name | ||
| 198 | sub parallelize_sub { | ||
| 199 | my ($sub) = @_; | ||
| 200 | |||
| 201 | # only prepend caller package if it's fully qualified | ||
| 202 | # allows easy parallelizing of subroutines inside other packages | ||
| 203 | if ($sub !~ /::/) { | ||
| 204 | my ($caller) = caller(); | ||
| 205 | $sub = join('::', $caller, $sub); | ||
| 206 | } | ||
| 207 | |||
| 208 | # we don't want nasty warnings - but don't try this at home | ||
| 209 | no strict 'refs'; | ||
| 210 | no warnings 'redefine'; | ||
| 211 | |||
| 212 | croak("can't parallelize non-existant subroutine") unless defined *{$sub}{CODE}; | ||
| 213 | |||
| 214 | # keeps the prototype | ||
| 215 | *$sub = &set_prototype(parallelize_coderef(\&$sub), prototype($sub)); | ||
| 216 | } | ||
| 217 | |||
| 218 | =head2 parallelize_coderef(CODEREF) | ||
| 219 | |||
| 220 | Returns a parallelized version of the given CODEREF. This function is used | ||
| 221 | internally to implement the other two functions explained above. | ||
| 222 | |||
| 223 | my $code = sub { ... } | ||
| 224 | my $parallel = parallelize_coderef($code); | ||
| 225 | |||
| 226 | my $return = $parallel->(@args); # runs in another thread | ||
| 227 | |||
| 228 | =cut | ||
| 229 | |||
| 230 | # returns a new coderef: a parallelized version of the original coderef | ||
| 231 | # the original is *not* modified | ||
| 232 | sub parallelize_coderef { | ||
| 233 | my ($coderef) = @_; | ||
| 234 | |||
| 235 | return sub { | ||
| 236 | # this is the simple trick which makes this module work | ||
| 237 | my $scalar = threads->create($coderef, @_); | ||
| 238 | bless {thread => $scalar, caller => threads->tid}, __PACKAGE__; | ||
| 239 | }; | ||
| 240 | } | ||
| 241 | |||
| 242 | # support for parallelizing through subroutine attributes | ||
| 243 | sub UNIVERSAL::Parallel : ATTR(CODE) { | ||
| 244 | # for completeness sake, let's have the whole prototype | ||
| 245 | my ($caller, $symtable, $coderef, $attr, $data, $phase) = @_; | ||
| 246 | |||
| 247 | no warnings 'redefine'; | ||
| 248 | # keeps the prototype | ||
| 249 | *$symtable = &set_prototype(parallelize_coderef($coderef), prototype($coderef)); | ||
| 250 | } | ||
| 251 | |||
| 252 | # the overload handler | ||
| 253 | sub _deref { | ||
| 254 | my $class = CORE::ref $_[0]; | ||
| 255 | # work-around in order to support scalar refs - yes, it's kinda ugly | ||
| 256 | # the alternative would be Acme::Damn but I feel kinda bad using Acme modules | ||
| 257 | bless $_[0], "${class}::NoOverload"; | ||
| 258 | if (CORE::ref($_[0]->{thread}) eq 'threads') { | ||
| 259 | $_[0] = $_[0]->{thread}->join; | ||
| 260 | } | ||
| 261 | else { | ||
| 262 | # just in case - should never get here | ||
| 263 | croak(__PACKAGE__ . " object doesn't reference a threads object - something really bad happened"); | ||
| 264 | } | ||
| 265 | return $_[0]; | ||
| 266 | } | ||
| 267 | |||
| 268 | # provide method calling support | ||
| 269 | sub AUTOLOAD { | ||
| 270 | # make errors appear to come from the caller | ||
| 271 | local $SIG{__DIE__} = sub { goto &croak }; | ||
| 272 | (my $sub = $AUTOLOAD) =~ s/.*:://; | ||
| 273 | $_[0] = _deref($_[0]); | ||
| 274 | # unfortunately, if we used goto CODEREF, the call wouldn't be made as a | ||
| 275 | # method and warnings wouldn't be transparent. so, we prefer messing up the | ||
| 276 | # caller stack - which is not that used anyway, aside from instrospection | ||
| 277 | # modules. | ||
| 278 | shift->$sub(@_); | ||
| 279 | } | ||
| 280 | |||
| 281 | sub croak { | ||
| 282 | # somehow, local $SIG handlers are not actually locally scoped | ||
| 283 | # this makes sure we get other possibly fatal errors | ||
| 284 | local $SIG{__DIE__} = ''; | ||
| 285 | (my $err = shift) =~ s/ at [^ ]+ line (?:\d+).?\n//; | ||
| 286 | require Carp; | ||
| 287 | Carp::croak($err); | ||
| 288 | } | ||
| 289 | |||
| 290 | # magic destructor! | ||
| 291 | # ok, ok... it just detaches the thread if we go out of scope. | ||
| 292 | # BUT ONLY IF we're the original caller of the thread | ||
| 293 | # this is a work-around for a strange behaviour of the perl threads implementation | ||
| 294 | sub DESTROY { | ||
| 295 | my $class = CORE::ref($_[0]); | ||
| 296 | bless $_[0], "${class}::NoOverload"; | ||
| 297 | if (CORE::ref($_[0]->{thread}) eq 'threads' && $_[0]->{caller} == threads->tid) { | ||
| 298 | $_[0]->{thread}->detach; | ||
| 299 | } | ||
| 300 | } | ||
| 301 | |||
| 302 | # provide overriden ref() function | ||
| 303 | sub ref ($) { | ||
| 304 | return CORE::ref($_[0]) if CORE::ref($_[0]) ne __PACKAGE__; | ||
| 305 | return CORE::ref($_[0]->_deref); | ||
| 306 | } | ||
| 307 | *CORE::GLOBAL::ref = \&ref; | ||
| 308 | |||
| 309 | 1; | ||
| 310 | |||
| 311 | # ok, i didn't tie anything. oh well, can't use them all... | ||
| 312 | |||
| 313 | =head1 INTERACTION WITH OTHER MODULES | ||
| 314 | |||
| 315 | The only B<known> issue is between this module and L<Catalyst>. When using | ||
| 316 | L<Catalyst> the C<Parallel> attribute seems to be broken. This is probably due | ||
| 317 | to L<Catalyst> trying to process every possible attribute, but I'm not really | ||
| 318 | sure. Patches are welcome. | ||
| 319 | |||
| 320 | There's a simple workaround. Instead of writing: | ||
| 321 | |||
| 322 | sub foo : Parallel { | ||
| 323 | # code here | ||
| 324 | } | ||
| 325 | |||
| 326 | Use the slightly more verbose: | ||
| 327 | |||
| 328 | sub foo { | ||
| 329 | # code here | ||
| 330 | } | ||
| 331 | |||
| 332 | parallelize_sub('foo'); | ||
| 333 | |||
| 334 | That should work in all cases. | ||
| 335 | |||
| 336 | =head1 CAVEATS | ||
| 337 | |||
| 338 | Currently, the parallel subroutines will always be called in scalar context. | ||
| 339 | There are plans for changing this in the future but, for now, if multiple | ||
| 340 | return values are needed, consider wrapping them around an array ref (this | ||
| 341 | feature would require adding the Want module as a dependency). | ||
| 342 | |||
| 343 | In order for objects to survice across threads, both the calling and the | ||
| 344 | executing thread must have its class properly included. This means that you | ||
| 345 | can't require a module only inside a subroutine and then return an object | ||
| 346 | blessed into that class to the calling thread. | ||
| 347 | |||
| 348 | You shouldn't pass to another thread/parallelized subroutines previous return | ||
| 349 | values from other parallelized subroutines without reading their values. And, | ||
| 350 | while you can get away with it, it's probably too much rope to hang yourself on | ||
| 351 | when things start to get ugly. This might be changed in the future, but would | ||
| 352 | require some sort of explicit synchronization through shared variables. | ||
| 353 | |||
| 354 | Also, there's no way to tell if a parallelized subroutine is still running or | ||
| 355 | not. This probably will be changed in the future but, unfortunately, will | ||
| 356 | require either a minimalistic approach using some simple shared variables or | ||
| 357 | the use of Thread::Running, which would be another dependency and ends up using | ||
| 358 | shared variables anyway. | ||
| 359 | |||
| 360 | The caller stack may behave in a non expected manner. When calling returned | ||
| 361 | object's methods, there will be an extra level in the stack, representing | ||
| 362 | C<AUTOLOAD> magic - the third form of C<goto> couldn't be used since that way | ||
| 363 | if the user called a non-existant method, he wouldn't get the default warning. | ||
| 364 | In the future, maybe this will be configurable so that if you need to rely on | ||
| 365 | the caller stack, you can make this trade-off. | ||
| 366 | |||
| 367 | If the I<parallelized> subroutine dies, you won't get any warnings on notices | ||
| 368 | of any kind. It would be like it returned C<undef>. This might change in the | ||
| 369 | future. | ||
| 370 | |||
| 371 | C<GLOBAL::CORE::ref> is overriden. This may be an issue if there are other | ||
| 372 | modules in use which override it too. In the future, there may be a switch to | ||
| 373 | disable this. | ||
| 374 | |||
| 375 | =head1 BUGS | ||
| 376 | |||
| 377 | Besides the CAVEATS (which some people might consider to be bugs) there are no | ||
| 378 | known bugs. | ||
| 379 | |||
| 380 | Please report any bugs or feature requests to | ||
| 381 | C<bug-subs-parallel@rt.cpan.org>, or through the web interface at | ||
| 382 | L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=subs-parallel-0.09>. | ||
| 383 | I will be notified, and then you'll automatically be notified of progress on | ||
| 384 | your bug as I make changes. | ||
| 385 | |||
| 386 | =head1 AUTHOR | ||
| 387 | |||
| 388 | Nilson Santos F. Jr., C<< <nilsonsfj@cpan.org> >> | ||
| 389 | |||
| 390 | =head1 COPYRIGHT & LICENSE | ||
| 391 | |||
| 392 | Copyright (C) 2005-2015 Nilson Santos Figueiredo Junior. | ||
| 393 | |||
| 394 | This program is free software; you can redistribute it and/or modify it | ||
| 395 | under the same terms as Perl itself. | ||
| 396 | |||
| 397 | =head1 SEE ALSO | ||
| 398 | |||
| 399 | L<threads> | ||
| 400 | |||
| 401 | =cut | ||
| 402 | |||
| 403 | 1; # End of subs::parallel | ||