1Padre::Role::Task(3)  User Contributed Perl Documentation Padre::Role::Task(3)
2
3
4

NAME

6       Padre::Role::Task - A role for objects that commission tasks
7

DESCRIPTION

9       This is a role that should be inherited from by objects in Padre's
10       permanent model that want to commision tasks to be run and have the
11       results fed back to them, if the answer is still relevant.
12
13   Task Revisions
14       Objects in Padre that commission tasks to run in the background can
15       continue processing and changing state during the queue'ing and/or
16       execution of their background tasks.
17
18       If the object state changes in such a way as to make the results of a
19       background task irrelevant, a mechanism is needed to ensure these
20       background tasks are aborted where possible, or their results thrown
21       away when not.
22
23       Padre::Role::Task provides the concept of "task revisions" to support
24       this functionality.
25
26       A task revision is an incrementing number for each owner that remains
27       the same as long as the results from any arbitrary launched task
28       remains relevant for the current state of the object.
29
30       When an object transitions a state boundary it will increment it's
31       revision, whether there are any running tasks or not.
32
33       When a task has completed the task manager will look up the owner (if
34       it has one) and check to see if the current revision of the owner
35       object is the same as when the task was scheduled. If so the Task
36       Manager will call the "on_finish" handler passing it the task. If not,
37       the completed task will be silently discarded.
38
39   Sending messages to your tasks
40       The Padre::Task API supports bidirection communication between tasks
41       and their owners.
42
43       However, when you commission a task via "task_request" the task object
44       is not returned, leaving you without access to the task and thus
45       without a method by which to send messages to the child.
46
47       This is intentional, as there is no guarentee that your task will be
48       launched immediately and so sending messages immediately may be unsafe.
49       The task may need to be delayed until a new background worker can be
50       spawned, or for longer if the maximum background worker limit has been
51       reached.
52
53       The solution is provided by the "on_message" handler, which is passed
54       the parent task object as its first paramater.
55
56       Tasks which expect to be sent messages from their owner should send the
57       owner a greeting message as soon as they have started. Not only does
58       this let the parent know that work has commenced on their task, but it
59       provides the task object to the owner once there is certainty that any
60       parent messages can be dispatched to the child successfully.
61
62       In the following example, we assume a long running "service" style task
63       that will need to be interacted with over time.
64
65         sub service_start {
66             my $self = shift;
67
68             $self->task_reset;
69             $self->task_request(
70                 task       => 'My::Service',
71                 on_message => 'my_message',
72                 on_finish  => 'my_finish',
73             );
74         }
75
76         sub my_message {
77             my $self = shift;
78             my $task = shift;
79
80             # In this example our task sends an empty message to indicate "started"
81             unless ( @_ ) {
82                 $self->{my_service} = $task;
83                 return;
84             }
85
86             # Handle other messages...
87         }
88

METHODS

90   task_owner
91         Padre::Role::Task->task_owner( 1234 );
92
93       The "task_owner" static method is a convenience method which takes an
94       owner id and will look up the owner object.
95
96       Returns the object if it still exists and has not changed it's task
97       revision.
98
99       Returns "undef" of the owner object no longer exists, or has changed
100       its task revision since the original owner id was issued.
101
102   task_manager
103       The "task_manager" method is a convenience for quick access to the
104       Padre's Padre::TaskManager instance.
105
106   task_revision
107       The "task_revision" accessor returns the current task revision for an
108       object.
109
110   task_reset
111       The "task_reset" method is called when the state of an owner object
112       significantly changes, and outstanding tasks should be deleted or
113       ignored.
114
115       It will change the task revision of the owner and request the task
116       manager to send a standard "cancel" message to any currently executing
117       background tasks, allowing them to terminate elegantly (if they handle
118
119   task_request
120         $self->task_request(
121             task       => 'Padre::Task::SomeTask',
122             on_message => 'message_handler_method',
123             on_finish  => 'finish_handler_method',
124             my_param1  => 123,
125             my_param2  => 'abc',
126         );
127
128       The "task_request" method is used to spawn a new background task for
129       the owner, loading the class and registering for callback messages in
130       the process.
131
132       The "task" parameter indicates the class of the task to be executed,
133       which must inherit from Padre::Task. The class itself will be
134       automatically loaded if required.
135
136       The optional "on_message" parameter should be the name of a method
137       (which must exist if provided) that will receive owner-targetted
138       messages from the background process.
139
140       The method will be passed the task object (as it exists after the
141       "prepare" phase in the parent thread) as its first parameter, followed
142       by any values passed by the background task.
143
144       If no "on_message" parameter is provided the default method null
145       "task_message" will be called.
146
147       The optional "on_finish" parameter should be the name of a method
148       (which must exist if provided) that will receive the task object back
149       from the background worker once the task has completed, complete with
150       any state saved in the task during its background execution.
151
152       It is passed a single parameter, which is the Padre::Task object.
153
154       If no "on_finish" parameter is provided the default method null
155       "task_finish" will be called.
156
157       Any other parameters are passed through the constructor method of the
158       task.
159
160   task_finish
161       The "task_finish" method is the default handler method for completed
162       tasks, and will be called for any "task_request" where no specific
163       "on_finish" handler was provided.
164
165       If your object issues only one task, or if you would prefer a single
166       common finish handler for all your different tasks, you should override
167       this method instead of explicitly defining an "on_finish" handler for
168       every task.
169
170       The default implementation ensures that every task has an appropriate
171       finish handler by throwing an exception with a message indicating the
172       owner and task class for which no finish handler could be found.
173
174   task_message
175       The "task_message" method is the default handler method for completed
176       tasks, and will be called for any "task_request" where no specific
177       "on_message" handler was provided.
178
179       If your object issues only one task, or if you would prefer a single
180       common message handler for all your different tasks, you should
181       override this method instead of explicitly defining an "on_finish"
182       handler for every task.
183
184       If none of your tasks will send messages back to their owner, you do
185       not need to define this method.
186
187       The default implementation ensures that every task has an appropriate
188       finish handler by throwing an exception with a message indicating the
189       owner and task class for which no finish handler could be found.
190
192       Copyright 2008-2011 The Padre development team as listed in Padre.pm.
193
194       This program is free software; you can redistribute it and/or modify it
195       under the same terms as Perl itself.
196
197       The full text of the license can be found in the LICENSE file included
198       with this module.
199
200
201
202perl v5.28.0                      2011-08-16              Padre::Role::Task(3)
Impressum