vcl/README.scheduler.md | 23 ++++++++++++++++++-----
1 file changed, 18 insertions(+), 5 deletions(-)
New commits:
commit 67615c8461eccc031c1934863a94df6bf8269641
Author: Hossein <hoss...@libreoffice.org>
AuthorDate: Sat Jul 30 20:30:19 2022 +0200
Commit: Hossein <hoss...@libreoffice.org>
CommitDate: Sat Jul 30 20:34:50 2022 +0200
Improve vcl scheduler documentation
* Fixed a heading problem
* Marked variables, functions and identifiers as fixed width
* Added several related links
Change-Id: If5e56c1e2a474fcfa52601ccda7911bf9e80c913
Reviewed-on: https://gerrit.libreoffice.org/c/core/+/137636
Tested-by: Hossein <hoss...@libreoffice.org>
Reviewed-by: Hossein <hoss...@libreoffice.org>
diff --git a/vcl/README.scheduler.md b/vcl/README.scheduler.md
index bfaf53e017d0..b213448762a7 100644
--- a/vcl/README.scheduler.md
+++ b/vcl/README.scheduler.md
@@ -9,10 +9,15 @@ using round-robin for reoccurring tasks.
The scheduler has the following behaviour:
B.1. Tasks are scheduled just priority based
+
B.2. Implicitly cooperative AKA non-preemptive
+
B.3. It's not "fair" in any way (a consequence of B.2)
+
B.4. Tasks are handled round-robin (per priority)
+
B.5. Higher priorities have lower values
+
B.6. A small set of priorities instead of an flexible value AKA int
There are some consequences due to this design.
@@ -224,8 +229,7 @@ other long running tasks, so interactivity can be improved.
There were some questions coming up when implementing it:
-#### Why does the scheduler not detect that we only have idle tasks pending,
-and skip the instant timeout?
+#### Why does the scheduler not detect that we only have idle tasks pending,
and skip the instant timeout?
You never know how long a task will run. Currently the scheduler simply asks
each task when it'll be ready to run, until two runnable tasks are found.
@@ -274,12 +278,12 @@ the `DBG_TESTSOLARMUTEX` calls are disabled, as we can't
release the
Those wakeup events must be ignored to prevent busy-locks. For more info read
the "General: main thread deferral" section.
-We can neither rely on macOS dispatch_sync code block execution nor the
+We can neither rely on macOS `dispatch_sync` code block execution nor the
message handling, as both can't be prioritized or filtered and the first
does also not allow nested execution and is just processed in sequence.
There is also a workaround for a problem for pushing tasks to an empty queue,
-as [NSApp postEvent: ... atStart: NO] doesn't append the event, if the
+as `[NSApp postEvent: ... atStart: NO]` doesn't append the event, if the
message queue is empty.
An additional problem is the filtering of events on Window close. This drops
@@ -415,7 +419,7 @@ do {
while ( bHasPending )
```
-The idea is to use g_main_context_prepare and keep the `max_priority` as an
+The idea is to use `g_main_context_prepare` and keep the `max_priority` as an
indicator. We cannot prevent running newer lower events, but we can prevent
running new higher events, which should be sufficient for most stuff.
@@ -433,3 +437,12 @@ will also affect the Gtk+ and KDE backend for the user
event handling.
This way it can be easier used to profile Tasks, eventually to improve LO's
interactivity.
+
+## See Also
+
+- [Solar Mutex](https://wiki.openoffice.org/wiki/Terms/Solar_Mutex)
+- [LibreOffice Main
Loop](https://wiki.documentfoundation.org/Development/LHM_LiMux/Main_Loop)
+- [AOO Advanced Threading-Architecture
(proposal)](https://wiki.openoffice.org/wiki/Architecture/Proposal/Advanced_Threading-Architecture)
+- [Revise OOo Multi-Threading
Efforts](https://wiki.openoffice.org/wiki/Effort/Revise_OOo_Multi-Threading)
+- [Multi-Threading
Analysis](https://wiki.openoffice.org/wiki/Analysis/Multi-Threading)
+- [AOO Wiki -
Category:Multi-Threading](https://wiki.openoffice.org/wiki/Category:Multi-Threading)
