1Padre::Role::Task(3) User Contributed Perl Documentation Padre::Role::Task(3)
2
6 Padre::Role::Task - A role for objects that commission tasks
7
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 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 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 Padre::Role::Task provides the concept of "task revisions" to support
24 this functionality.
25 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 When an object transitions a state boundary it will increment it's
31 revision, whether there are any running tasks or not.
32 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 Sending messages to your tasks
40 The Padre::Task API supports bidirection communication between tasks
41 and their owners.
42 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 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 The solution is provided by the "on_message" handler, which is passed
54 the parent task object as its first paramater.
55 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 In the following example, we assume a long running "service" style task
63 that will need to be interacted with over time.
64 sub service_start {
66 my $self = shift;
67 $self->task_reset;
69 $self->task_request(
70 task => 'My::Service',
71 on_message => 'my_message',
72 on_finish => 'my_finish',
73 );
74 }
75 sub my_message {
77 my $self = shift;
78 my $task = shift;
79 # In this example our task sends an empty message to indicate "started"
81 unless ( @_ ) {
82 $self->{my_service} = $task;
83 return;
84 }
85 # Handle other messages...
87 }
88
90 task_owner
91 Padre::Role::Task->task_owner( 1234 );
92 The "task_owner" static method is a convenience method which takes an
94 owner id and will look up the owner object.
95 Returns the object if it still exists and has not changed it's task
97 revision.
98 Returns "undef" of the owner object no longer exists, or has changed
100 its task revision since the original owner id was issued.
101 task_manager
103 The "task_manager" method is a convenience for quick access to the
104 Padre's Padre::TaskManager instance.
105 task_revision
107 The "task_revision" accessor returns the current task revision for an
108 object.
109 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 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 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 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 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 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 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 If no "on_message" parameter is provided the default method null
145 "task_message" will be called.
146 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 It is passed a single parameter, which is the Padre::Task object.
153 If no "on_finish" parameter is provided the default method null
155 "task_finish" will be called.
156 Any other parameters are passed through the constructor method of the
158 task.
159 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 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 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 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 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 If none of your tasks will send messages back to their owner, you do
185 not need to define this method.
186 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 This program is free software; you can redistribute it and/or modify it
195 under the same terms as Perl itself.
196 The full text of the license can be found in the LICENSE file included
198 with this module.
199perl v5.32.1 2021-01-27 Padre::Role::Task(3)