1Padre::TaskManager(3) User Contributed Perl DocumentationPadre::TaskManager(3)
2
6 Padre::TaskManager - Padre Background Task and Service Manager
7
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 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 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 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 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 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 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 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
51 new
52 my $manager = Padre::TaskManager->new(
53 conduit => $message_conduit,
54 );
55 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 The constructor has a single compulsory parameter, which is an object
61 that implements the "message conduit" role Padre::Wx::Role::Conduit.
62 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 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 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 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 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 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 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 start
106 $manager->start;
107 The "start" method bootstraps the task manager, creating "minimum"
109 workers immediately if needed.
110 stop
112 $manager->stop;
113 The "stop" method shuts down the task manager, signalling active
115 workers that they should do an elegant shutdown.
116 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 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 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 cancel
129 $manager->cancel( $owner );
130 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 start_worker
137 my $worker = $manager->start_worker;
138 The "start_worker" starts and returns a new registered
140 Padre::TaskWorker object, ready to execute a task or service in.
141 You generally should never need to call this method from outside
143 Padre::TaskManager.
144 stop_worker
146 $manager->stop_worker(1);
147 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 kill_worker
153 $manager->kill_worker(1);
154 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 This method is not yet in use, the Task Manager does not current have
160 the ability to forcefully terminate workers.
161 best_worker
163 my $worker = $manager->best_worker( $task_object );
164 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 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 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 Returns a Padre::TaskWorker object, or "undef" if there is no worker in
180 which the task can be run.
181 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 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 Returns true if all pending tasks were dispatched, or false if any
191 tasks remain on the queue.
192 on_signal
194 $manager->on_signal( \@message );
195 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 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 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 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 This program is free software; you can redistribute it and/or modify it
216 under the same terms as Perl itself.
217 The full text of the license can be found in the LICENSE file included
219 with this module.
220perl v5.28.1 2011-08-16 Padre::TaskManager(3)