NAME¶
Padre::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).
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 the master
thread.
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.
cancelled¶
$manager->cancelled( $owner );
The "cancelled" method is used with the "task ownership"
feature of the Padre::Task 3.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.
run¶
The "run" method tells the Task Manager to sweep the queue of pending
tasks and dispatch as many as possible to worker threads.
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.
good_task¶
my $ok = $manager->good_task($task);
The "good_task" method takes a Padre::Task object and determines if
the task can be executed, given the resources available to the task manager.
Returns a Padre::Task object, or "undef" if there is no task to
execute.
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. Without the slave master logic enabled
this will result in the editor blocking in the foreground briefly, this is
something we can live with until the slave master feature is working again.
Returns a Padre::TaskWorker object, or "undef" if there is no worker
in which the task can be run.
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-2013 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.