mirrors/PocketMine-MP
1
0
Fork 0
mirror of https://github.com/pmmp/PocketMine-MP.git synced 2025-06-12 22:45:28 +00:00
Code Issues Projects Releases Wiki Activity

AsyncTask: update documentation

Browse Source
This commit is contained in:
Dylan K. Taylor 2022-07-21 23:26:35 +01:00
parent c4f85e526b
commit 4852f8029a
No known key found for this signature in database
GPG Key ID: 8927471A91CAFD3D
1 changed files with 18 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
src/scheduler/AsyncTask.php
View File

@ -33,19 +33,31 @@ use function spl_object_id;
/** /**
* Class used to run async tasks in other threads. * Class used to run async tasks in other threads.
* *
* An AsyncTask does not have its own thread. It is queued into an AsyncPool and executed if there is an async worker * An AsyncTask is run by a thread pool of reusable threads, and doesn't have its own dedicated thread. A thread is
* with no AsyncTask running. Therefore, an AsyncTask SHOULD NOT execute for more than a few seconds. For tasks that * usually chosen from the pool at random to run the task (though a specific thread in the pool may be selected
* run for a long time or infinitely, start another thread instead. * 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 {@link AsyncTask::onRun()}. It can only be accessed in the main server
* thread, e.g. during {@link AsyncTask::onCompletion()} or {@link AsyncTask::onProgressUpdate()}. This means that
* whatever you do in onRun() must be able to work without the Server instance.
* *
* WARNING: Any non-Threaded objects WILL BE SERIALIZED when assigned to members of AsyncTasks or other Threaded object. * WARNING: Any non-Threaded objects WILL BE SERIALIZED when assigned to members of AsyncTasks or other Threaded object.
* If later accessed from said Threaded object, you will be operating on a COPY OF THE OBJECT, NOT THE ORIGINAL OBJECT. * If later accessed from said Threaded object, you will be operating on a COPY OF THE OBJECT, NOT THE ORIGINAL OBJECT.
* If you want to store non-serializable objects to access when the task completes, store them using * If you want to store non-serializable objects to access when the task completes, store them using
* {@link AsyncTask::storeLocal}. * {@link AsyncTask::storeLocal}.
* *
* WARNING: As of pthreads v3.1.6, arrays are converted to Volatile objects when assigned as members of Threaded objects. * WARNING: Arrays are converted to Volatile objects when assigned as members of Threaded objects.
* Keep this in mind when using arrays stored as members of your AsyncTask. * Keep this in mind when using arrays stored as members of your AsyncTask.
*
* WARNING: Do not call PocketMine-MP API methods from other Threads!!
*/ */
abstract class AsyncTask extends \Threaded{ abstract class AsyncTask extends \Threaded{
/** /**