AsyncTask

abstract class · pocketmine\scheduler\AsyncTask · source

Extends pmmp\thread\Runnable

Class used to run async tasks in other threads.

An AsyncTask is run by a thread pool of reusable threads, and doesn't have its own dedicated thread. A thread is usually chosen from the pool at random to run the task (though a specific thread in the pool may be selected manually, if needed). Reusing threads this way has a much lower performance cost than starting an entirely new thread for every operation. AsyncTasks are therefore suitable for brief CPU-bound tasks, such as world generation, compression/decompression of data, etc.

AsyncTask SHOULD NOT be used for I/O-bound tasks, such as network I/O, file I/O, database I/O, etc. The server's central AsyncPool is used for things like compressing network packets for sending, so using AsyncTask for I/O will slow the whole server down, stall chunk loading, etc.

An AsyncTask SHOULD NOT run for more than a few seconds. For tasks that run for a long time or indefinitely, create a dedicated thread instead.

The Server instance is not accessible inside AsyncTask::onRun(). It can only be accessed in the main server thread, e.g. during AsyncTask::onCompletion() or AsyncTask::onProgressUpdate(). This means that whatever you do in onRun() must be able to work without the Server instance.

If you want to store non-thread-safe objects to access when the task completes, store them using AsyncTask::storeLocal.

Methods

__destruct()

final public function __destruct()

cancelRun()

public function cancelRun() : void

Deprecated

Deprecated.

fetchLocal() protected

protected function fetchLocal(string $key)

Retrieves data stored in thread-local storage.

If you used storeLocal(), you can use this on the same thread to fetch data stored. This should be used during onProgressUpdate() and onCompletion() to fetch thread-local data stored on the parent thread.

getResult()

public function getResult()

hasCancelledRun()

public function hasCancelledRun() : bool

Deprecated

Deprecated.

hasResult()

public function hasResult() : bool

isCrashed()

public function isCrashed() : bool

Deprecated

Deprecated.

isFinished()

public function isFinished() : bool

Returns whether this task has finished executing, whether successfully or not. This differs from isRunning() because it is not true prior to task execution.

isSubmitted()

public function isSubmitted() : bool

onCompletion()

public function onCompletion() : void

Actions to execute when completed (on main thread) Implement this if you want to handle the data in your AsyncTask after it has been processed

onError()

public function onError() : void

Deprecated

No longer used

onProgressUpdate()

public function onProgressUpdate($progress) : void

Deprecated

Deprecated.

Called from the main thread after AsyncTask::publishProgress is called. All AsyncTask::publishProgress calls should result in AsyncTask::onProgressUpdate calls before AsyncTask::onCompletion is called.

onRun()

abstract public function onRun() : void

Actions to execute when run

publishProgress()

public function publishProgress(mixed $progress) : void

Deprecated

Deprecated.

Call this method from AsyncTask::onRun (AsyncTask execution thread) to schedule a call to AsyncTask::onProgressUpdate from the main thread with the given progress parameter.

reallyDestruct() protected

protected function reallyDestruct() : void

Override this to do normal __destruct() cleanup from a child class.

run()

public function run() : void

setResult()

public function setResult(mixed $result) : void

setSubmitted()

public function setSubmitted() : void

storeLocal() protected

protected function storeLocal(string $key, mixed $complexData) : void

Saves mixed data in thread-local storage. Data stored using this storage is only accessible from the thread it was stored on. Data stored using this method will not be serialized. This can be used to store references to variables which you need later on on the same thread, but not others.

For example, plugin references could be stored in the constructor of the async task (which is called on the main thread) using this, and then fetched in onCompletion() (which is also called on the main thread), without them becoming serialized.

Scalar types can be stored directly in class properties instead of using this storage.

Objects stored in this storage can be retrieved using fetchLocal() on the same thread that this method was called from.