-
Notifications
You must be signed in to change notification settings - Fork 1
/
TaskInterface.php
168 lines (154 loc) · 5.35 KB
/
TaskInterface.php
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
<?php
namespace Aternos\Taskmaster\Task;
use Aternos\Taskmaster\Communication\Promise\TaskPromise;
use Aternos\Taskmaster\Exception\PhpError;
use Aternos\Taskmaster\Exception\PhpFatalErrorException;
use Aternos\Taskmaster\Runtime\RuntimeInterface;
use Exception;
/**
* Interface TaskInterface
*
* A task class represents a single task that runs in the child runtime and can
* communicate back to the parent. A task has to be serializable.
*
* @package Aternos\Taskmaster\Task
*/
interface TaskInterface
{
/**
* A callback that is executed when the task is finished.
*
* The first argument is the return value of the {@link TaskInterface::run()} method
* or null if no value was returned.
*
* The {@link TaskInterface::handleError()} method is not called when this method is called.
*
* @param mixed $result
* @return void
*/
#[OnParent]
public function handleResult(mixed $result): void;
/**
* A callback that is executed when the task has a fatal error
*
* The first argument is an {@link Exception}.
* There are different fatal error causes, e.g. a fatal php error, an
* unexpected worker exit or an uncaught exception.
*
* A fatal php error is represented by a {@link PhpFatalErrorException} which contains
* a {@link PhpError} object. An unexpected worker exit is represented by a {@link WorkerFailedException}.
*
* The {@link TaskInterface::handleResult()} method is not called when this method is called.
*
* @param Exception $error
* @return void
*/
#[OnParent]
public function handleError(Exception $error): void;
/**
* Get the worker group this tasks should be executed on
*
* @return string|null
*/
#[OnParent]
public function getGroup(): ?string;
/**
* Run the task
*
* This is the method where your main task logic should be implemented.
* The return value can later be handled on the parent using the {@link TaskInterface::handleResult()} method.
*
* Throwing an exception in this method will result in a fatal error and the {@link TaskInterface::handleError()}
* method will be called.
*
* @return mixed
* @noinspection PhpMissingReturnTypeInspection No return type is intentional, to allow void as return type in child classes
*/
#[OnChild]
public function run();
/**
* A callback that is executed in the child runtime when the task has an uncritical error, e.g. a warning
*
* The first argument is a {@link PhpError} object.
*
* Returning false will cause the default PHP error handling to proceed, see {@link set_error_handler()}.
*
* @param PhpError $error
* @return bool
*/
#[OnChild]
public function handleUncriticalError(PhpError $error): bool;
/**
* Set the runtime instance
*
* This is set in the runtime automatically to allow the task to communicate through the runtime
* with the parent worker.
*
* @param RuntimeInterface $runtime
* @return $this
*/
#[OnChild]
public function setRuntime(RuntimeInterface $runtime): static;
/**
* Get the unique promise for this task
*
* This promise is resolved when the task is finished or rejected when the task has a fatal error.
* It should be stored using the #[OnParent] attribute as promises are not serializable.
*
* @return TaskPromise
*/
#[OnParent]
public function getPromise(): TaskPromise;
/**
* Get the task result after the task has finished
*
* The task result is the return value of the {@link TaskInterface::run()} method.
* If the {@link TaskInterface::handleResult()} method is overwritten, make sure to
* call the parent method or set the {@link TaskInterface::result} property yourself.
*
* @return mixed
*/
#[OnParent]
public function getResult(): mixed;
/**
* Get the task error after the task has finished
*
* The task error is an error caused in the {@link TaskInterface::run()} method or
* an unexpected worker exit.
* If the {@link TaskInterface::handleError()} method is overwritten, make sure to
* call the parent method or set the {@link TaskInterface::error} property yourself.
*
* @return Exception|null
*/
#[OnParent]
public function getError(): ?Exception;
/**
* Get the current timeout for this task in seconds
*
* Decimals are allowed for sub-second timeouts.
* 0 means no timeout, null means default timeout should be used
*
* @return float|null
*/
public function getTimeout(): ?float;
/**
* Set the timeout for this task in seconds
*
* Decimals are allowed for sub-second timeouts.
* 0 means no timeout, null means default timeout should be used
*
* @param float|null $timeout
* @return $this
*/
public function setTimeout(?float $timeout): static;
/**
* Tell the task that it's being executed in a sync environment
*
* Some cases must be handled differently in a sync environment because
* you are operating on the same and not just equal objects, e.g. you
* might not want to close file handles that are still used by other tasks.
*
* @return $this
*/
public function setSync(bool $sync = true): static;
}