Padre::TaskManager(3) User Contributed Perl DocumentationPadre::TaskManager(3)NAMEPadre::TaskManager - Padre Background Task and Service Manager
DESCRIPTION
The Padre Task Manager is responsible for scheduling, queueing and
executing all operations that do not occur in the main application
thead.
While there is rarely any need for code elsewhere in Padre or a plugin
to make calls to this API, documentation is included for maintenance
purposes.
It spawns and manages a pool of workers which act as containers for the
execution of standalone serialisable tasks. This execution model is
based loosely on the CPAN Process API, and involves the parent process
creating Padre::Task objects representing the work to do. These tasks
are serialised to a bytestream, passed down a shared queue to an
appropriate worker, deserialised back into an object, executed, and
then reserialised for transmission back to the parent thread.
Task Structure
Tasks operate on a shared-nothing basis. Each worker is required to
reload any modules needed by the task, and the task cannot access any
of the data structures. To compensate for these limits, tasks are able
to send messages back and forth between the instance of the task object
in the parent and the instance of the same task in the child.
Using this messaging channel, a task object in the child can send
status message or incremental results up to the parent, and the task
object in the parent can make changes to the GUI based on these
messages.
The same messaging channel allows a background task to be cancelled
elegantly by the parent, although support for the "cancel" message is
voluntary on the part of the background task.
Service Structure
Services are implemented via the Padre::Service API. This is nearly
identical to, and sub-classes directly, the Padre::Task API.
The main difference between a task and a service is that a service will
be allocated a private, unused and dedicated worker that has never been
used by a task. Further, workers allocated to services will also not be
counted against the "maximum workers" limit.
METHODS
new
my $manager = Padre::TaskManager->new(
conduit => $message_conduit,
);
The "new" constructor creates a new Task Manager instance. While it is
theoretically possible to create more than one instance, in practice
this is never likely to occur.
The constructor has a single compulsory parameter, which is an object
that implements the "message conduit" role Padre::Wx::Role::Conduit.
The message conduit is an object which provides direct integration with
the underlying child-to-parent messaging pipeline, which in Padre is
done via Wx::PlThreadEvent thread events.
Because the message conduit is provided to the constructor, the Task
Manager itself is able to function with no Wx-specific code whatsoever.
This simplifies implementation, allows sophisticated test rigs to be
created, and makes it easier for us to spin off the Task Manager as a
some notional standalone CPAN module.
active
The "active" accessor returns true if the task manager is currently
running, or false if not. Generally task manager startup will occur
relatively early in the Padre startup sequence, and task manager
shutdown will occur relatively early in the shutdown sequence (to
prevent accidental task execution during shutdown).
threads
The "threads" accessor returns true if the Task Manager requires the
use of Perl threads, or false if not. This method is provided to
notionally allow support for alternative task implementations that use
processes rather than threads, however during the upgrade to the
Padre::Task 2.0 API only a threading backend was implemented.
A future Task 2.0 backend implementation that uses processes instead of
threads should be possible, but nobody on the current Padre team has
plans to implement this alternative at this time. Contact the Padre
team if you are interested in implementing the alternative backend.
minimum
The "minimum" accessor returns the minimum number of workers that the
task manager will keep spawned. This value is typically set to zero if
some use cases of the application will not need to run tasks at all and
we wish to reduce memory and startup time, or a small number (one or
two) if startup time of the first few tasks is important.
maximum
The "maximum" accessor returns the maximum quantity of worker threads
that the task manager will use for running ordinary finite-length
tasks. Once the number of active workers reaches the "maximum" limit,
futher tasks will be pushed onto a queue to wait for a free worker.
start
$manager->start;
The "start" method bootstraps the task manager, creating "minimum"
workers immediately if needed.
stop
$manager->stop;
The "stop" method shuts down the task manager, signalling active
workers that they should do an elegant shutdown.
schedule
The "schedule" method is used to give a task to the task manager and
indicate it should be run as soon as possible.
This may be immediately (with the task sent to a worker before the
method returns) or it may be delayed until some time in the future if
all workers are busy.
As a convenience, this method returns true if the task could be
dispatched immediately, or false if it was queued for future execution.
cancel
$manager->cancel( $owner );
The "cancel" method is used with the "task ownership" feature of the
Padre::Task 2.0 API to signal tasks running in the background that were
created by a particular object that they should voluntarily abort as
their results are no longer wanted.
start_worker
my $worker = $manager->start_worker;
The "start_worker" starts and returns a new registered
Padre::TaskWorker object, ready to execute a task or service in.
You generally should never need to call this method from outside
Padre::TaskManager.
stop_worker
$manager->stop_worker(1);
The "stop_worker" method shuts down a single worker, which
(unfortunately) at this time is indicated via the internal index
position in the workers array.
kill_worker
$manager->kill_worker(1);
The "kill_worker" method forcefully and immediately terminates a
worker, and like "stop_worker" the worker to kill is indicated by the
internal index position within the workers array.
This method is not yet in use, the Task Manager does not current have
the ability to forcefully terminate workers.
best_worker
my $worker = $manager->best_worker( $task_object );
The "best_worker" method is used to find the best worker from the
worker pool for the execution of a particular task object.
This method makes use of a number of different strategies for
optimising the way in which workers are used, such as maximising worker
reuse for the same type of task, and "specialising" workers for
particular types of tasks.
If all existing workers are in use this method may also spawn new
workers, up to the "maximum" worker limit.
Returns a Padre::TaskWorker object, or "undef" if there is no worker in
which the task can be run.
run
The "step" method tells the Task Manager to attempt to process the
queue of pending tasks and dispatch as many as possible.
Generally you should never need to call this method directly, as it
will be called whenever you schedule a task or when a worker becomes
available.
Returns true if all pending tasks were dispatched, or false if any
tasks remain on the queue.
on_signal
$manager->on_signal( \@message );
The "on_signal" method is called from the conduit object and acts as a
central distribution mechanism for messages coming from all child
workers.
Messages arrive as a list of elements in an "ARRAY" with their first
element being the handle identifier of the Padre::TaskHandle for the
task.
This "envelope" element is stripped from the front of the message, and
the remainder of the message is passed down into the handle (and the
task within the handle).
Certain special messages, such as "STARTED" and "STOPPED" are emitted
not by the task but by the surrounding handle, and indicate to the task
manager the state of the child worker.
COPYRIGHT & LICENSE
Copyright 2008-2011 The Padre development team as listed in Padre.pm.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included
with this module.
perl v5.14.1 2011-06-18 Padre::TaskManager(3)
