| 1 | ##============================================================================== | ||
| 2 | ## Tk::Task - allow multiple tasks to proceed at once | ||
| 3 | ##============================================================================== | ||
| 4 | ## Copyright 2002 Kevin Michael Vail. All rights reserved. | ||
| 5 | ## This program is free software. You may redistribute and/or modify it | ||
| 6 | ## under the same terms as Perl itself. | ||
| 7 | ##============================================================================== | ||
| 8 | ## $Id: Task.pm,v 1.1 2002/10/24 01:12:14 kevin Exp $ | ||
| 9 | ##============================================================================== | ||
| 10 | require 5.005_62; | ||
| 11 | |||
| 12 | package Tk::Task; | ||
| 13 | use strict; | ||
| 14 | use Tk; | ||
| 15 | use Tie::StrictHash; | ||
| 16 | use Carp; | ||
| 17 | use Exporter (); | ||
| 18 | use vars qw($VERSION @ISA @EXPORT); | ||
| 19 | ($VERSION) = q$Revision: 1.1 $ =~ /^Revision:\s+(\S+)/ or $VERSION = "0.0"; | ||
| 20 | @ISA = qw(Exporter); | ||
| 21 | @EXPORT = qw(TASK TASKPARM TASKQUEUE); | ||
| 22 | |||
| 23 | package Tk::Task::Instance; | ||
| 24 | use strict; | ||
| 25 | use Tk; | ||
| 26 | use Tie::StrictHash; | ||
| 27 | |||
| 28 | package Tk::Task::Queue; | ||
| 29 | use strict; | ||
| 30 | use Tk; | ||
| 31 | use Tie::StrictHash; | ||
| 32 | use Carp; | ||
| 33 | |||
| 34 | package Tk::Task::Step; | ||
| 35 | use strict; | ||
| 36 | use Tie::StrictHash; | ||
| 37 | |||
| 38 | package Tk::Task::Step::Method; | ||
| 39 | use strict; | ||
| 40 | use vars qw(@ISA); | ||
| 41 | @ISA = qw(Tk::Task::Step); | ||
| 42 | |||
| 43 | package Tk::Task::Step::Subroutine; | ||
| 44 | use strict; | ||
| 45 | use vars qw(@ISA); | ||
| 46 | @ISA = qw(Tk::Task::Step); | ||
| 47 | |||
| 48 | package Tk::Task::Step::Loop; | ||
| 49 | use strict; | ||
| 50 | use vars qw(@ISA); | ||
| 51 | @ISA = qw(Tk::Task::Step); | ||
| 52 | |||
| 53 | =head1 NAME | ||
| 54 | |||
| 55 | Tk::Task - allow multiple "tasks" to proceed at once | ||
| 56 | |||
| 57 | =head1 SYNOPSIS | ||
| 58 | |||
| 59 | use Tk::Task; | ||
| 60 | |||
| 61 | $mw = MainWindow->new; | ||
| 62 | ... | ||
| 63 | $task = $mw->Task( | ||
| 64 | [ | ||
| 65 | sub { | ||
| 66 | OpenCursor(); | ||
| 67 | } | ||
| 68 | ], | ||
| 69 | [ | ||
| 70 | [ | ||
| 71 | sub { | ||
| 72 | my $task = shift; | ||
| 73 | if (FetchFromCursor()) { | ||
| 74 | AddToTree; | ||
| 75 | } else { | ||
| 76 | $task->break; | ||
| 77 | } | ||
| 78 | } | ||
| 79 | ], | ||
| 80 | ], | ||
| 81 | [ | ||
| 82 | sub { | ||
| 83 | CloseCursor(); | ||
| 84 | } | ||
| 85 | ] | ||
| 86 | ); | ||
| 87 | |||
| 88 | $task->start; | ||
| 89 | |||
| 90 | =head1 DESCRIPTION | ||
| 91 | |||
| 92 | C<Tk::Task> is a module to allow a lengthy operation to be subdivided into | ||
| 93 | smaller pieces, with time to process events between pieces. For example, a | ||
| 94 | program that loaded a large number of records from a database could make the | ||
| 95 | load process a task, allowing the program to remain responsive to events--for | ||
| 96 | example, to handle a Stop button! | ||
| 97 | |||
| 98 | The steps of each task are executed at idle time, one step each time, while | ||
| 99 | "normal" processing (handling the event loop) continues. You might use a task | ||
| 100 | to do simple animations such as turning cards over in a game, or for other | ||
| 101 | purposes. For example, the L<Tk::TriangleTree|Tk::TriangleTree> widget uses a | ||
| 102 | Tk::Task to animate the disclosure triangle. | ||
| 103 | |||
| 104 | A Task is I<not> the same as a thread. It is more like a "poor man's" version | ||
| 105 | of threading. However, this is often quite good enough. | ||
| 106 | |||
| 107 | Each step of the task is a reference to an array which can contain one of the | ||
| 108 | following: | ||
| 109 | |||
| 110 | =over 4 | ||
| 111 | |||
| 112 | =item C<< [ \&subroutine, I<@args> ] >> | ||
| 113 | |||
| 114 | A reference to a subroutine causes that subroutine to be called with the rest | ||
| 115 | of the elements of the array as parameters. | ||
| 116 | |||
| 117 | =item C<< [ 'method' => $object, I<@args> ] >> | ||
| 118 | |||
| 119 | A string is treated as a method; the class or object associated with the | ||
| 120 | method must be the second element of the array, and any other elements are | ||
| 121 | passed as parameters. | ||
| 122 | |||
| 123 | =item C<< [ [ ... ], [ ... ], ... ] >> | ||
| 124 | |||
| 125 | A reference to an array indicates a loop. The steps within the outer array | ||
| 126 | are repeated until one of them calls the B<break> method, at which time the | ||
| 127 | first step after the outer array is executed. | ||
| 128 | |||
| 129 | =back | ||
| 130 | |||
| 131 | For example, the task structure shown in the L</SYNOPSIS> shows a task that | ||
| 132 | opens a database cursor, fetches each row and adds it to a tree, and then | ||
| 133 | closes the cursor and ends the task when there are no more rows to be | ||
| 134 | fetched. | ||
| 135 | |||
| 136 | There are three pseudo-arguments that can be specified when defining task steps. | ||
| 137 | These are exported by default. | ||
| 138 | |||
| 139 | =over 4 | ||
| 140 | |||
| 141 | =item C<< TASK >> | ||
| 142 | |||
| 143 | This is replaced with a reference to the task object itself when the task | ||
| 144 | step runs. This is necessary to allow the step to call the B<break> or | ||
| 145 | B<repeat> methods. | ||
| 146 | |||
| 147 | =item C<< TASKPARM(I<$name>) >> | ||
| 148 | |||
| 149 | This is replaced by the named parameter when the task step runs. Parameters | ||
| 150 | are set when the task is started, or can be added later using the B<parameter> | ||
| 151 | method. | ||
| 152 | |||
| 153 | =item C<< TASKQUEUE >> | ||
| 154 | |||
| 155 | This is replaced by a reference to the queue containing the currently executing | ||
| 156 | task. | ||
| 157 | |||
| 158 | =back | ||
| 159 | |||
| 160 | =head2 Queues | ||
| 161 | |||
| 162 | Tasks are useful enough by themselves, but it is also possible to make a queue | ||
| 163 | of tasks. Tasks can be added dynamically to the end of the queue, and will | ||
| 164 | execute when all tasks in front of them have executed. | ||
| 165 | |||
| 166 | =head1 METHODS | ||
| 167 | |||
| 168 | =head2 Task Methods | ||
| 169 | |||
| 170 | =over 4 | ||
| 171 | |||
| 172 | =item I<$task> = I<$mw>->Task(I<@specifications>); | ||
| 173 | |||
| 174 | Creates a new task with the given steps. This method is actually added to the | ||
| 175 | MainWindow class. | ||
| 176 | |||
| 177 | =cut | ||
| 178 | |||
| 179 | package Tk::Task; | ||
| 180 | |||
| 181 | ##============================================================================== | ||
| 182 | ## new | ||
| 183 | ##============================================================================== | ||
| 184 | sub Tk::Widget::Task { | ||
| 185 | my $mw = shift; | ||
| 186 | |||
| 187 | my $task = new Tie::StrictHash items => [], main => $mw; | ||
| 188 | |||
| 189 | bless $task, 'Tk::Task'; | ||
| 190 | $task->_process($task->{items}, [ @_ ]); | ||
| 191 | return $task; | ||
| 192 | } | ||
| 193 | |||
| 194 | =pod | ||
| 195 | |||
| 196 | =item I<$instance> = I<$task>->start(I<parm1> => I<$value1>, ...); | ||
| 197 | |||
| 198 | Starts I<$task> executing from the beginning. The given parameters are made | ||
| 199 | available to the steps of the task by use of the TASKPARM pseudo-argument. Any | ||
| 200 | existing instance of I<$task> is unaffected. | ||
| 201 | |||
| 202 | =cut | ||
| 203 | |||
| 204 | ##============================================================================== | ||
| 205 | ## start | ||
| 206 | ##============================================================================== | ||
| 207 | sub start { | ||
| 208 | my $task = shift; | ||
| 209 | my $instance = new Tk::Task::Instance $task, undef, @_; | ||
| 210 | $instance->_run; | ||
| 211 | return $instance; | ||
| 212 | } | ||
| 213 | |||
| 214 | =pod | ||
| 215 | |||
| 216 | =item I<$instance> = I<$task>->queue(I<$queue>, I<parm1> => I<$value1>, ...); | ||
| 217 | |||
| 218 | Same as B<start>, but also sets the queue that the instance is on. This is | ||
| 219 | meant to be called only by the Tk::Task::Queue methods. | ||
| 220 | |||
| 221 | =cut | ||
| 222 | |||
| 223 | ##============================================================================== | ||
| 224 | ## queue | ||
| 225 | ##============================================================================== | ||
| 226 | sub queue { | ||
| 227 | my $task = shift; | ||
| 228 | my $queue = shift; | ||
| 229 | my $instance = new Tk::Task::Instance $task, $queue, @_; | ||
| 230 | $instance->_run; | ||
| 231 | return $instance; | ||
| 232 | } | ||
| 233 | |||
| 234 | ##============================================================================== | ||
| 235 | ## Internal Tk::Task methods | ||
| 236 | ##------------------------------------------------------------------------------ | ||
| 237 | ## _process | ||
| 238 | ## Convert the input step specifications to instances of Tk::Task::Step. | ||
| 239 | ##============================================================================== | ||
| 240 | sub _process { | ||
| 241 | my ($task, $items, $steps) = @_; | ||
| 242 | |||
| 243 | foreach my $step (@$steps) { | ||
| 244 | next unless ref $step eq 'ARRAY'; | ||
| 245 | my @parms = @$step; | ||
| 246 | my $proc = shift(@parms); | ||
| 247 | my $refstep = ref $proc; | ||
| 248 | unless ($refstep) { | ||
| 249 | push @$items, Tk::Task::Step::Method->new($proc, @parms); | ||
| 250 | } elsif ($refstep eq 'CODE') { | ||
| 251 | push @$items, Tk::Task::Step::Subroutine->new($proc, @parms); | ||
| 252 | } elsif ($refstep eq 'ARRAY') { | ||
| 253 | my $array = []; | ||
| 254 | $task->_process($array, $step); | ||
| 255 | push @$items, Tk::Task::Step::Loop->new($array); | ||
| 256 | } else { | ||
| 257 | croak "invalid reference type in task step definition - must be CODE or ARRAY"; | ||
| 258 | } | ||
| 259 | } | ||
| 260 | } | ||
| 261 | |||
| 262 | ##------------------------------------------------------------------------------ | ||
| 263 | ## _mainwindow | ||
| 264 | ## Returns the main window associated with this task. Called by Instance::new. | ||
| 265 | ##------------------------------------------------------------------------------ | ||
| 266 | sub _mainwindow { | ||
| 267 | my $task = shift; | ||
| 268 | return $task->{main}; | ||
| 269 | } | ||
| 270 | |||
| 271 | ##------------------------------------------------------------------------------ | ||
| 272 | ## _items | ||
| 273 | ## Returns the list of items associated with this task. Called by | ||
| 274 | ## Instance::new. | ||
| 275 | ##------------------------------------------------------------------------------ | ||
| 276 | sub _items { | ||
| 277 | my $task = shift; | ||
| 278 | return $task->{items}; | ||
| 279 | } | ||
| 280 | |||
| 281 | ##============================================================================== | ||
| 282 | ## Definitions of the pseudo-arguments TASK, TASKPARM, and TASKQUEUE. | ||
| 283 | ##============================================================================== | ||
| 284 | sub _DummyProcTask {}; | ||
| 285 | sub _DummyProcTaskParm {}; | ||
| 286 | sub _DummyProcTaskQueue {}; | ||
| 287 | |||
| 288 | sub TASK { \&_DummyProcTask }; | ||
| 289 | sub TASKPARM { ( \&DummyProcTaskParm, $_[0]) }; | ||
| 290 | sub TASKQUEUE { \&DummyProcTaskQueue }; | ||
| 291 | |||
| 292 | =pod | ||
| 293 | |||
| 294 | =back | ||
| 295 | |||
| 296 | =head2 Instance Methods | ||
| 297 | |||
| 298 | A task instance is created automatically when you start a task. This allows | ||
| 299 | each task to be executing multiple copies at the same time, without interfering | ||
| 300 | with one another. | ||
| 301 | |||
| 302 | =over 4 | ||
| 303 | |||
| 304 | =item I<$instance>->repeat; | ||
| 305 | |||
| 306 | Prevents the instance from advancing to the next step; when the task is due to | ||
| 307 | run again, it will repeat the current step. | ||
| 308 | |||
| 309 | =cut | ||
| 310 | |||
| 311 | package Tk::Task::Instance; | ||
| 312 | |||
| 313 | ##============================================================================== | ||
| 314 | ## repeat | ||
| 315 | ##============================================================================== | ||
| 316 | sub repeat { | ||
| 317 | my $instance = shift; | ||
| 318 | $instance->{repeat} = 1; | ||
| 319 | return $instance; | ||
| 320 | } | ||
| 321 | |||
| 322 | =pod | ||
| 323 | |||
| 324 | =item I<$instance>->break; | ||
| 325 | |||
| 326 | Causes the instance to exit from the innermost loop; the next step executed will | ||
| 327 | be the one after the end of the loop. If the current step is not part of a | ||
| 328 | loop, nothing happens. | ||
| 329 | |||
| 330 | =cut | ||
| 331 | |||
| 332 | ##============================================================================== | ||
| 333 | ## break | ||
| 334 | ##============================================================================== | ||
| 335 | sub break { | ||
| 336 | my $instance = shift; | ||
| 337 | |||
| 338 | if (@{$instance->{stack}}) { | ||
| 339 | @{$instance}{qw/current list/} = @{pop(@{$instance->{stack}})}; | ||
| 340 | } | ||
| 341 | return $instance; | ||
| 342 | } | ||
| 343 | |||
| 344 | =pod | ||
| 345 | |||
| 346 | =item I<$instance>->cancel; | ||
| 347 | |||
| 348 | Causes the instance to stop after the end of the current step. No further steps | ||
| 349 | will be executed. If called from "outside" the task, between steps, then the | ||
| 350 | next step will never fire. | ||
| 351 | |||
| 352 | =cut | ||
| 353 | |||
| 354 | ##============================================================================== | ||
| 355 | ## cancel | ||
| 356 | ##============================================================================== | ||
| 357 | sub cancel { | ||
| 358 | my $instance = shift; | ||
| 359 | $instance->{cancel} = 1; | ||
| 360 | return $instance; | ||
| 361 | } | ||
| 362 | |||
| 363 | =pod | ||
| 364 | |||
| 365 | =item I<$instance>->delay(I<$milliseconds>); | ||
| 366 | |||
| 367 | Causes a delay of I<$milliseconds> between the time the current step finishes | ||
| 368 | and the next step begins. Behavior if called from other than within a task step | ||
| 369 | is undefined. | ||
| 370 | |||
| 371 | =cut | ||
| 372 | |||
| 373 | ##============================================================================== | ||
| 374 | ## delay | ||
| 375 | ##============================================================================== | ||
| 376 | sub delay { | ||
| 377 | my ($instance, $milliseconds) = @_; | ||
| 378 | $instance->{delay} = $milliseconds; | ||
| 379 | return $instance; | ||
| 380 | } | ||
| 381 | |||
| 382 | =pod | ||
| 383 | |||
| 384 | =item I<$value> = I<$instance>->parameter(I<parm_name>); | ||
| 385 | |||
| 386 | Returns the value of the particular parameter set when the instance was started, | ||
| 387 | or changed later. | ||
| 388 | |||
| 389 | =item I<$instance>->parameter(I<parm_name> => I<$value>); | ||
| 390 | |||
| 391 | Sets the value of the named parameter. This can be either a change to an | ||
| 392 | existing parameter or the creation of a new parameter. | ||
| 393 | |||
| 394 | =cut | ||
| 395 | |||
| 396 | ##============================================================================== | ||
| 397 | ## parameter | ||
| 398 | ##============================================================================== | ||
| 399 | sub parameter { | ||
| 400 | my ($instance, $parmname) = splice(@_, 0, 2); | ||
| 401 | $instance->{parms}->{$parmname} = shift if @_; | ||
| 402 | return $instance->{parms}->{$parmname}; | ||
| 403 | } | ||
| 404 | |||
| 405 | ##============================================================================== | ||
| 406 | ## Internal Tk::Task::Instance methods | ||
| 407 | ##------------------------------------------------------------------------------ | ||
| 408 | ## _fire | ||
| 409 | ## The procedure that actually calls a task step. | ||
| 410 | ##============================================================================== | ||
| 411 | sub _fire { | ||
| 412 | my $instance = shift; | ||
| 413 | |||
| 414 | ##-------------------------------------------------------------------------- | ||
| 415 | ## Execute the step at $task->{list}->[$task->{current}]. | ||
| 416 | ##-------------------------------------------------------------------------- | ||
| 417 | $instance->{id} = undef; | ||
| 418 | if ($instance->{current} < 0 | ||
| 419 | || $instance->{current} >= @{$instance->{list}} | ||
| 420 | || $instance->{cancel}) { | ||
| 421 | $instance->_finish; | ||
| 422 | return; | ||
| 423 | } | ||
| 424 | $instance->{list}->[$instance->{current}]->call($instance); | ||
| 425 | |||
| 426 | ##-------------------------------------------------------------------------- | ||
| 427 | ## Figure out which step to execute next, if any. If they called repeat, | ||
| 428 | ## it will be the same step (actually it just indicates that the current | ||
| 429 | ## index won't be incremented); otherwise, increment the index and run that | ||
| 430 | ## step, if possible. If we fall off the end of the task, just reset the | ||
| 431 | ## {running} flag and don't start another step. | ||
| 432 | ##-------------------------------------------------------------------------- | ||
| 433 | if ($instance->{repeat}) { | ||
| 434 | $instance->{repeat} = 0; | ||
| 435 | } elsif (++$instance->{current} >= @{$instance->{list}}) { | ||
| 436 | if (@{$instance->{stack}}) { | ||
| 437 | $instance->{current} = 0; | ||
| 438 | } else { | ||
| 439 | $instance->_finish; | ||
| 440 | } | ||
| 441 | } | ||
| 442 | $instance->_run if $instance->{running}; | ||
| 443 | } | ||
| 444 | |||
| 445 | ##------------------------------------------------------------------------------ | ||
| 446 | ## _run | ||
| 447 | ## Set up to run the current step. | ||
| 448 | ##------------------------------------------------------------------------------ | ||
| 449 | sub _run { | ||
| 450 | my $instance = shift; | ||
| 451 | if ($instance->{delay}) { | ||
| 452 | $instance->{id} = $instance->{main}->after( | ||
| 453 | $instance->{delay}, [ _fire => $instance ] | ||
| 454 | ); | ||
| 455 | $instance->{delay} = 0; | ||
| 456 | } else { | ||
| 457 | $instance->{id} = $instance->{main}->afterIdle([ _fire => $instance ]); | ||
| 458 | } | ||
| 459 | } | ||
| 460 | |||
| 461 | ##------------------------------------------------------------------------------ | ||
| 462 | ## _finish | ||
| 463 | ## Clean up when a task finishes, and let its queue know if it has one. | ||
| 464 | ##------------------------------------------------------------------------------ | ||
| 465 | sub _finish { | ||
| 466 | my $instance = shift; | ||
| 467 | |||
| 468 | $instance->{running} = 0; | ||
| 469 | $instance->{queue}->notify($instance) if $instance->{queue}; | ||
| 470 | } | ||
| 471 | |||
| 472 | ##------------------------------------------------------------------------------ | ||
| 473 | ## new | ||
| 474 | ## Create a new instance. Should only be called from Task::start or Task::queue. | ||
| 475 | ##------------------------------------------------------------------------------ | ||
| 476 | sub new { | ||
| 477 | my ($class, $task, $queue) = splice(@_, 0, 3); | ||
| 478 | my $instance = new Tie::StrictHash | ||
| 479 | task => $task, current => 0, stack => [], list => $task->_items, | ||
| 480 | repeat => 0, id => undef, running => 1, delay => 0, | ||
| 481 | main => $task->_mainwindow, queue => $queue, cancel => 0, | ||
| 482 | parms => { @_ }; | ||
| 483 | return bless $instance, $class; | ||
| 484 | } | ||
| 485 | |||
| 486 | ##------------------------------------------------------------------------------ | ||
| 487 | ## _setargs | ||
| 488 | ## Convert the argument array for a task step. | ||
| 489 | ## $instance->_setargs(\@args); | ||
| 490 | ## Can also be called as Tk::Task::Instance->_setargs if no task is involved. | ||
| 491 | ##------------------------------------------------------------------------------ | ||
| 492 | sub _setargs { | ||
| 493 | my ($instance, $args) = @_; | ||
| 494 | my $queue = $instance->{queue}; | ||
| 495 | my @args; | ||
| 496 | my $tctl0 = Tk::Task::TASK; | ||
| 497 | my ($tctl1, undef) = Tk::Task::TASKPARM('x'); | ||
| 498 | my $tctl2 = Tk::Task::TASKQUEUE; | ||
| 499 | my $state = 'regular'; | ||
| 500 | |||
| 501 | foreach (@$args) { | ||
| 502 | if ($state eq 'parmname') { | ||
| 503 | push @args, $instance->parameter($_); | ||
| 504 | $state = 'regular'; | ||
| 505 | } elsif ($_ eq $tctl0) { | ||
| 506 | push @args, $instance; | ||
| 507 | } elsif ($_ eq $tctl1) { | ||
| 508 | $state = 'parmname'; | ||
| 509 | } elsif ($_ eq $tctl2) { | ||
| 510 | push @args, $queue; | ||
| 511 | } else { | ||
| 512 | push @args, $_; | ||
| 513 | } | ||
| 514 | } | ||
| 515 | return @args; | ||
| 516 | } | ||
| 517 | |||
| 518 | ##------------------------------------------------------------------------------ | ||
| 519 | ## _push | ||
| 520 | ## $instance->_push($list); | ||
| 521 | ## Save the current list and index within that list, then set the list to the | ||
| 522 | ## given list and start at its beginning. | ||
| 523 | ##------------------------------------------------------------------------------ | ||
| 524 | sub _push { | ||
| 525 | my ($instance, $list) = @_; | ||
| 526 | push @{$instance->{stack}}, [ @{$instance}{qw/current list/} ]; | ||
| 527 | $instance->{list} = $list; | ||
| 528 | $instance->{current} = 0; | ||
| 529 | } | ||
| 530 | |||
| 531 | =pod | ||
| 532 | |||
| 533 | =back | ||
| 534 | |||
| 535 | =head2 Queue Methods | ||
| 536 | |||
| 537 | =over 4 | ||
| 538 | |||
| 539 | =item I<$queue> = new Tk::Task::Queue I<%options>; | ||
| 540 | |||
| 541 | Creates a new queue. The following I<options> are supported: | ||
| 542 | |||
| 543 | =over 4 | ||
| 544 | |||
| 545 | =item C<< -finish >> | ||
| 546 | |||
| 547 | A callback that is called when all tasks in the queue have been completed. | ||
| 548 | |||
| 549 | =item C<< -init >> | ||
| 550 | |||
| 551 | A callback that is called whenever a task starts when no task was running | ||
| 552 | before. | ||
| 553 | |||
| 554 | =back | ||
| 555 | |||
| 556 | The most common use for these two callbacks is to do something like calling Busy | ||
| 557 | on the main window when a lengthy task begins, and Unbusy when it ends. | ||
| 558 | |||
| 559 | Each callback can be either a reference to a subroutine, which is simply called | ||
| 560 | with a reference to the queue as its only parameter, or in the form of a task | ||
| 561 | step. In the latter case, the TASKQUEUE pseudo-argument must be used to get a | ||
| 562 | reference to the queue. | ||
| 563 | |||
| 564 | =cut | ||
| 565 | |||
| 566 | package Tk::Task::Queue; | ||
| 567 | |||
| 568 | ##============================================================================== | ||
| 569 | ## new | ||
| 570 | ##============================================================================== | ||
| 571 | sub new { | ||
| 572 | my $class = shift; | ||
| 573 | my $queue = new Tie::StrictHash | ||
| 574 | list => [], current => undef, paused => 0, cancel => 0, | ||
| 575 | -finish => undef, -init => undef; | ||
| 576 | |||
| 577 | while (@_) { | ||
| 578 | croak "odd number of options passed to $class\::new" if @_ % 2; | ||
| 579 | my $name = shift; | ||
| 580 | my $value = shift; | ||
| 581 | if ($name =~ /^-/ && exists $queue->{$name}) { | ||
| 582 | $queue->{$name} = $value; | ||
| 583 | } else { | ||
| 584 | croak "invalid option to $class\::new: '$name'"; | ||
| 585 | } | ||
| 586 | } | ||
| 587 | return bless $queue, $class; | ||
| 588 | } | ||
| 589 | |||
| 590 | =pod | ||
| 591 | |||
| 592 | =item I<$queue>->queue(I<$task>, I<parm1> => I<$value1>, ...); | ||
| 593 | |||
| 594 | Adds I<$task> to the end of I<$queue>, with the given parameters. I<$task> | ||
| 595 | will execute when all tasks in front of it have completed; if there are no | ||
| 596 | tasks in the queue when this method is called, the task will start executing | ||
| 597 | immediately. | ||
| 598 | |||
| 599 | =cut | ||
| 600 | |||
| 601 | ##============================================================================== | ||
| 602 | ## queue | ||
| 603 | ##============================================================================== | ||
| 604 | sub queue { | ||
| 605 | my $queue = shift; | ||
| 606 | push @{$queue->{list}}, [ @_ ]; | ||
| 607 | $queue->_dispatch unless $queue->{current} || $queue->{paused}; | ||
| 608 | } | ||
| 609 | |||
| 610 | =pod | ||
| 611 | |||
| 612 | =item I<$queue>->pause; | ||
| 613 | |||
| 614 | Pauses execution of the queue after the current task is complete. The next | ||
| 615 | task will not begin until the B<resume> method is called. | ||
| 616 | |||
| 617 | =cut | ||
| 618 | |||
| 619 | ##============================================================================== | ||
| 620 | ## pause | ||
| 621 | ##============================================================================== | ||
| 622 | sub pause { | ||
| 623 | my $queue = shift; | ||
| 624 | $queue->{paused} = 1; | ||
| 625 | return $queue; | ||
| 626 | } | ||
| 627 | |||
| 628 | =pod | ||
| 629 | |||
| 630 | =item I<$queue>->resume; | ||
| 631 | |||
| 632 | Resumes execution of the queue. Nothing happens if the queue isn't paused. | ||
| 633 | |||
| 634 | =cut | ||
| 635 | |||
| 636 | ##============================================================================== | ||
| 637 | ## resume | ||
| 638 | ##============================================================================== | ||
| 639 | sub resume { | ||
| 640 | my $queue = shift; | ||
| 641 | if ($queue->{paused}) { | ||
| 642 | $queue->{paused} = 0; | ||
| 643 | $queue->_dispatch; | ||
| 644 | } | ||
| 645 | return $queue; | ||
| 646 | } | ||
| 647 | |||
| 648 | =pod | ||
| 649 | |||
| 650 | =item I<$queue>->cancel; | ||
| 651 | |||
| 652 | Cancels execution of all tasks in the queue after the current one completes. | ||
| 653 | |||
| 654 | =cut | ||
| 655 | |||
| 656 | ##============================================================================== | ||
| 657 | ## cancel | ||
| 658 | ##============================================================================== | ||
| 659 | sub cancel { | ||
| 660 | my $queue = shift; | ||
| 661 | $queue->{cancel} = 1; | ||
| 662 | return $queue; | ||
| 663 | } | ||
| 664 | |||
| 665 | =pod | ||
| 666 | |||
| 667 | =item I<$queue>->abort; | ||
| 668 | |||
| 669 | Cancels execution of all tasks in the queue after the current step of the | ||
| 670 | current task completes. | ||
| 671 | |||
| 672 | =cut | ||
| 673 | |||
| 674 | ##============================================================================== | ||
| 675 | ## abort | ||
| 676 | ##============================================================================== | ||
| 677 | sub abort { | ||
| 678 | my $queue = shift; | ||
| 679 | $queue->cancel; | ||
| 680 | $queue->{current}->cancel if $queue->{current}; | ||
| 681 | return $queue; | ||
| 682 | } | ||
| 683 | |||
| 684 | =pod | ||
| 685 | |||
| 686 | =item I<$boolean> = I<$queue>->is_empty; | ||
| 687 | |||
| 688 | Returns true if there is nothing currently in the queue. Note that this method | ||
| 689 | will also return true if called from the last task that was in the queue. | ||
| 690 | |||
| 691 | =cut | ||
| 692 | |||
| 693 | ##============================================================================== | ||
| 694 | ## is_empty | ||
| 695 | ##============================================================================== | ||
| 696 | sub is_empty { | ||
| 697 | my $queue = shift; | ||
| 698 | return @{$queue->{list}} == 0; | ||
| 699 | } | ||
| 700 | |||
| 701 | =pod | ||
| 702 | |||
| 703 | =item I<$queue>->notify(I<$instance>); | ||
| 704 | |||
| 705 | Notifies the queue that the task instance specified by I<$instance> has | ||
| 706 | completed. This is called automatically by I<$instance> when it finishes; you | ||
| 707 | shouldn't ever have to call it directly. If I<$instance> isn't the instance | ||
| 708 | that's currently executing, nothing happens. | ||
| 709 | |||
| 710 | =cut | ||
| 711 | |||
| 712 | ##============================================================================== | ||
| 713 | ## notify | ||
| 714 | ##============================================================================== | ||
| 715 | sub notify { | ||
| 716 | my ($queue, $instance) = @_; | ||
| 717 | $queue->_dispatch if $queue->{current} eq $instance; | ||
| 718 | return $queue; | ||
| 719 | } | ||
| 720 | |||
| 721 | ##============================================================================== | ||
| 722 | ## Internal Tk::Task::Queue methods | ||
| 723 | ##------------------------------------------------------------------------------ | ||
| 724 | ## _dispatch | ||
| 725 | ## Execute the task at the front of the queue. | ||
| 726 | ##============================================================================== | ||
| 727 | sub _dispatch { | ||
| 728 | my $queue = shift; | ||
| 729 | if ($queue->{cancel} || @{$queue->{list}} == 0) { | ||
| 730 | $queue->_finish; | ||
| 731 | } elsif (!$queue->{paused}) { | ||
| 732 | $queue->_call('-init') unless defined $queue->{current}; | ||
| 733 | my $array = shift @{$queue->{list}}; | ||
| 734 | my $task = shift @$array; | ||
| 735 | $queue->{current} = $task->queue($queue, @$array); | ||
| 736 | } | ||
| 737 | } | ||
| 738 | |||
| 739 | ##------------------------------------------------------------------------------ | ||
| 740 | ## _finish | ||
| 741 | ## Execute the finish callback. | ||
| 742 | ##------------------------------------------------------------------------------ | ||
| 743 | sub _finish { | ||
| 744 | my $queue = shift; | ||
| 745 | $queue->_call('-finish'); | ||
| 746 | $queue->{paused} = 0; | ||
| 747 | $queue->{cancel} = 0; | ||
| 748 | $queue->{list} = []; | ||
| 749 | $queue->{current} = undef; | ||
| 750 | } | ||
| 751 | |||
| 752 | ##------------------------------------------------------------------------------ | ||
| 753 | ## _call | ||
| 754 | ## Call the -init or -finish callback. | ||
| 755 | ##------------------------------------------------------------------------------ | ||
| 756 | sub _call { | ||
| 757 | my ($queue, $cbtype) = @_; | ||
| 758 | |||
| 759 | if (my $callback = $queue->{$cbtype}) { | ||
| 760 | if (ref $callback eq 'CODE') { | ||
| 761 | $callback->($queue); | ||
| 762 | } elsif (ref $callback eq 'ARRAY') { | ||
| 763 | my @args = @$callback; | ||
| 764 | my $proc = shift @args; | ||
| 765 | @args = Tk::Task->setargs($queue, @args); | ||
| 766 | $proc->(@args); | ||
| 767 | } else { | ||
| 768 | die "invalid $cbtype callback for " . ref $queue; | ||
| 769 | } | ||
| 770 | } | ||
| 771 | |||
| 772 | return $queue; | ||
| 773 | } | ||
| 774 | |||
| 775 | ################################################################################ | ||
| 776 | ## INTERNAL CLASSES | ||
| 777 | ################################################################################ | ||
| 778 | package Tk::Task::Step; | ||
| 779 | |||
| 780 | ##------------------------------------------------------------------------------ | ||
| 781 | ## new | ||
| 782 | ## Create a new task step. | ||
| 783 | ##------------------------------------------------------------------------------ | ||
| 784 | sub new { | ||
| 785 | my ($class, $proc) = splice(@_, 0, 2); | ||
| 786 | my $step = new Tie::StrictHash proc => $proc, args => [ @_ ]; | ||
| 787 | bless $step, $class; | ||
| 788 | } | ||
| 789 | |||
| 790 | package Tk::Task::Step::Method; | ||
| 791 | |||
| 792 | ##------------------------------------------------------------------------------ | ||
| 793 | ## call | ||
| 794 | ## Call a method from a step. | ||
| 795 | ##------------------------------------------------------------------------------ | ||
| 796 | sub call { | ||
| 797 | my ($step, $instance) = @_; | ||
| 798 | my @args = $instance->_setargs($step->{args}); | ||
| 799 | my $method = $step->{proc}; | ||
| 800 | my $object = shift(@args); | ||
| 801 | $object->$method(@args); | ||
| 802 | } | ||
| 803 | |||
| 804 | package Tk::Task::Step::Subroutine; | ||
| 805 | |||
| 806 | ##------------------------------------------------------------------------------ | ||
| 807 | ## call | ||
| 808 | ##------------------------------------------------------------------------------ | ||
| 809 | sub call { | ||
| 810 | my ($step, $instance) = @_; | ||
| 811 | my @args = $instance->_setargs($step->{args}); | ||
| 812 | $step->{proc}->(@args); | ||
| 813 | } | ||
| 814 | |||
| 815 | package Tk::Task::Step::Loop; | ||
| 816 | |||
| 817 | ##------------------------------------------------------------------------------ | ||
| 818 | ## call | ||
| 819 | ##------------------------------------------------------------------------------ | ||
| 820 | sub call { | ||
| 821 | my ($step, $instance) = @_; | ||
| 822 | $instance->_push($step->{proc}); | ||
| 823 | $instance->repeat; ## so {current} doesn't get incremented | ||
| 824 | } | ||
| 825 | |||
| 826 | =pod | ||
| 827 | |||
| 828 | =back | ||
| 829 | |||
| 830 | =head1 DIAGNOSTICS | ||
| 831 | |||
| 832 | =over 4 | ||
| 833 | |||
| 834 | =item invalid -finish callback for Tk::Task::Queue | ||
| 835 | |||
| 836 | The C<-finish> callback must be either a code reference or an array reference. | ||
| 837 | |||
| 838 | =item invalid reference type in task step definition - must be CODE or ARRAY | ||
| 839 | |||
| 840 | A task step that was neither a reference to a subroutine nor a reference to an | ||
| 841 | array was encountered. | ||
| 842 | |||
| 843 | =item odd number of options passed to I<class>::new | ||
| 844 | |||
| 845 | Self-explanatory. | ||
| 846 | |||
| 847 | =item invalid option to I<class>::new: 'I<name>' | ||
| 848 | |||
| 849 | Self-explanatory. | ||
| 850 | |||
| 851 | =back | ||
| 852 | |||
| 853 | =head1 SEE ALSO | ||
| 854 | |||
| 855 | L<Tk::after> | ||
| 856 | |||
| 857 | =head1 MODULES USED | ||
| 858 | |||
| 859 | L<Tie::StrictHash|Tie::StrictHash> | ||
| 860 | |||
| 861 | =head1 CHANGES | ||
| 862 | |||
| 863 | =over 4 | ||
| 864 | |||
| 865 | =item 1.0 | ||
| 866 | |||
| 867 | First release. | ||
| 868 | |||
| 869 | =item 1.1 | ||
| 870 | |||
| 871 | Allow a Task to be created off of any widget, not just a MainWindow. | ||
| 872 | |||
| 873 | =back | ||
| 874 | |||
| 875 | =head1 COPYRIGHT | ||
| 876 | |||
| 877 | Copyright 2002 Kevin Michael Vail. All rights reserved. | ||
| 878 | |||
| 879 | This program is free software. You may redistribute and/or modify it under the | ||
| 880 | same terms as Perl itself. | ||
| 881 | |||
| 882 | =head1 AUTHOR | ||
| 883 | |||
| 884 | Kevin Michael Vail <kevin@vaildc.net> | ||
| 885 | |||
| 886 | =cut | ||
| 887 | |||
| 888 | 1; | ||
| 889 | |||
| 890 | ##============================================================================== | ||
| 891 | ## $Log: Task.pm,v $ | ||
| 892 | ## Revision 1.1 2002/10/24 01:12:14 kevin | ||
| 893 | ## Allow Task to be created from any widget, not just a MainWindow. | ||
| 894 | ## | ||
| 895 | ## Revision 1.0 2002/03/18 02:29:07 kevin | ||
| 896 | ## Initial revision | ||
| 897 | ##============================================================================== |