1Padre::TaskManager(3) User Contributed Perl DocumentationPadre::TaskManager(3)
2
3
4

NAME

6       Padre::TaskManager - Padre Background Task and Service Manager
7

DESCRIPTION

9       The Padre Task Manager is responsible for scheduling, queueing and
10       executing all operations that do not occur in the main application
11       thead.
12
13       While there is rarely any need for code elsewhere in Padre or a plugin
14       to make calls to this API, documentation is included for maintenance
15       purposes.
16
17       It spawns and manages a pool of workers which act as containers for the
18       execution of standalone serialisable tasks. This execution model is
19       based loosely on the CPAN Process API, and involves the parent process
20       creating Padre::Task objects representing the work to do. These tasks
21       are serialised to a bytestream, passed down a shared queue to an
22       appropriate worker, deserialised back into an object, executed, and
23       then reserialised for transmission back to the parent thread.
24
25   Task Structure
26       Tasks operate on a shared-nothing basis. Each worker is required to
27       reload any modules needed by the task, and the task cannot access any
28       of the data structures. To compensate for these limits, tasks are able
29       to send messages back and forth between the instance of the task object
30       in the parent and the instance of the same task in the child.
31
32       Using this messaging channel, a task object in the child can send
33       status message or incremental results up to the parent, and the task
34       object in the parent can make changes to the GUI based on these
35       messages.
36
37       The same messaging channel allows a background task to be cancelled
38       elegantly by the parent, although support for the "cancel" message is
39       voluntary on the part of the background task.
40
41   Service Structure
42       Services are implemented via the Padre::Service API. This is nearly
43       identical to, and sub-classes directly, the Padre::Task API.
44
45       The main difference between a task and a service is that a service will
46       be allocated a private, unused and dedicated worker that has never been
47       used by a task. Further, workers allocated to services will also not be
48       counted against the "maximum workers" limit.
49

METHODS

51   new
52         my $manager = Padre::TaskManager->new(
53             conduit => $message_conduit,
54         );
55
56       The "new" constructor creates a new Task Manager instance. While it is
57       theoretically possible to create more than one instance, in practice
58       this is never likely to occur.
59
60       The constructor has a single compulsory parameter, which is an object
61       that implements the "message conduit" role Padre::Wx::Role::Conduit.
62
63       The message conduit is an object which provides direct integration with
64       the underlying child-to-parent messaging pipeline, which in Padre is
65       done via Wx::PlThreadEvent thread events.
66
67       Because the message conduit is provided to the constructor, the Task
68       Manager itself is able to function with no Wx-specific code whatsoever.
69       This simplifies implementation, allows sophisticated test rigs to be
70       created, and makes it easier for us to spin off the Task Manager as a
71       some notional standalone CPAN module.
72
73   active
74       The "active" accessor returns true if the task manager is currently
75       running, or false if not. Generally task manager startup will occur
76       relatively early in the Padre startup sequence, and task manager
77       shutdown will occur relatively early in the shutdown sequence (to
78       prevent accidental task execution during shutdown).
79
80   threads
81       The "threads" accessor returns true if the Task Manager requires the
82       use of Perl threads, or false if not. This method is provided to
83       notionally allow support for alternative task implementations that use
84       processes rather than threads, however during the upgrade to the
85       Padre::Task 2.0 API only a threading backend was implemented.
86
87       A future Task 2.0 backend implementation that uses processes instead of
88       threads should be possible, but nobody on the current Padre team has
89       plans to implement this alternative at this time. Contact the Padre
90       team if you are interested in implementing the alternative backend.
91
92   minimum
93       The "minimum" accessor returns the minimum number of workers that the
94       task manager will keep spawned. This value is typically set to zero if
95       some use cases of the application will not need to run tasks at all and
96       we wish to reduce memory and startup time, or a small number (one or
97       two) if startup time of the first few tasks is important.
98
99   maximum
100       The "maximum" accessor returns the maximum quantity of worker threads
101       that the task manager will use for running ordinary finite-length
102       tasks. Once the number of active workers reaches the "maximum" limit,
103       futher tasks will be pushed onto a queue to wait for a free worker.
104
105   start
106         $manager->start;
107
108       The "start" method bootstraps the task manager, creating "minimum"
109       workers immediately if needed.
110
111   stop
112         $manager->stop;
113
114       The "stop" method shuts down the task manager, signalling active
115       workers that they should do an elegant shutdown.
116
117   schedule
118       The "schedule" method is used to give a task to the task manager and
119       indicate it should be run as soon as possible.
120
121       This may be immediately (with the task sent to a worker before the
122       method returns) or it may be delayed until some time in the future if
123       all workers are busy.
124
125       As a convenience, this method returns true if the task could be
126       dispatched immediately, or false if it was queued for future execution.
127
128   cancel
129         $manager->cancel( $owner );
130
131       The "cancel" method is used with the "task ownership" feature of the
132       Padre::Task 2.0 API to signal tasks running in the background that were
133       created by a particular object that they should voluntarily abort as
134       their results are no longer wanted.
135
136   start_worker
137         my $worker = $manager->start_worker;
138
139       The "start_worker" starts and returns a new registered
140       Padre::TaskWorker object, ready to execute a task or service in.
141
142       You generally should never need to call this method from outside
143       Padre::TaskManager.
144
145   stop_worker
146         $manager->stop_worker(1);
147
148       The "stop_worker" method shuts down a single worker, which
149       (unfortunately) at this time is indicated via the internal index
150       position in the workers array.
151
152   kill_worker
153         $manager->kill_worker(1);
154
155       The "kill_worker" method forcefully and immediately terminates a
156       worker, and like "stop_worker" the worker to kill is indicated by the
157       internal index position within the workers array.
158
159       This method is not yet in use, the Task Manager does not current have
160       the ability to forcefully terminate workers.
161
162   best_worker
163         my $worker = $manager->best_worker( $task_object );
164
165       The "best_worker" method is used to find the best worker from the
166       worker pool for the execution of a particular task object.
167
168       This method makes use of a number of different strategies for
169       optimising the way in which workers are used, such as maximising worker
170       reuse for the same type of task, and "specialising" workers for
171       particular types of tasks.
172
173       If all existing workers are in use this method may also spawn new
174       workers, up to the "maximum" worker limit. Without the slave master
175       logic enabled this will result in the editor blocking in the foreground
176       briefly, this is something we can live with until the slave master
177       feature is working again.
178
179       Returns a Padre::TaskWorker object, or "undef" if there is no worker in
180       which the task can be run.
181
182   run
183       The "step" method tells the Task Manager to attempt to process the
184       queue of pending tasks and dispatch as many as possible.
185
186       Generally you should never need to call this method directly, as it
187       will be called whenever you schedule a task or when a worker becomes
188       available.
189
190       Returns true if all pending tasks were dispatched, or false if any
191       tasks remain on the queue.
192
193   on_signal
194         $manager->on_signal( \@message );
195
196       The "on_signal" method is called from the conduit object and acts as a
197       central distribution mechanism for messages coming from all child
198       workers.
199
200       Messages arrive as a list of elements in an "ARRAY" with their first
201       element being the handle identifier of the Padre::TaskHandle for the
202       task.
203
204       This "envelope" element is stripped from the front of the message, and
205       the remainder of the message is passed down into the handle (and the
206       task within the handle).
207
208       Certain special messages, such as "STARTED" and "STOPPED" are emitted
209       not by the task but by the surrounding handle, and indicate to the task
210       manager the state of the child worker.
211
213       Copyright 2008-2011 The Padre development team as listed in Padre.pm.
214
215       This program is free software; you can redistribute it and/or modify it
216       under the same terms as Perl itself.
217
218       The full text of the license can be found in the LICENSE file included
219       with this module.
220
221
222
223perl v5.28.1                      2011-08-16             Padre::TaskManager(3)
Impressum