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.