[Libreoffice-commits] core.git: Branch 'feature/new-vcl-scheduler' - vcl/README.scheduler

[Jan-Marek Glogowski]

 vcl/README.scheduler |   47 +++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 45 insertions(+), 2 deletions(-)

New commits:
commit 58daed5d2c7f0f374e2bf11c547792380bc595e1
Author: Jan-Marek Glogowski <glogow at fbihome.de>
Date:   Thu Nov 3 17:32:10 2016 +0100

    WIP: updated docs
    
    Change-Id: Id19f98303b8bef597bd62ac89cbadeaa15520db8

diff --git a/vcl/README.scheduler b/vcl/README.scheduler
index b99fe8f..7556a9b 100644
--- a/vcl/README.scheduler
+++ b/vcl/README.scheduler
@@ -1,7 +1,9 @@
 = Introduction =
 
 The VCL scheduler handles LOs primary event queue.
-It is simple by design, currently just a single-linked list, and has the following behaviour:
+It is simple by design, currently just a single-linked list.
+
+The scheduler has the following behaviour:
 
 B.1. Tasks are scheduled just priority based
 B.2. Implicitly cooperative AKA non-preemptive
@@ -24,6 +26,47 @@ C.3. This is not an OS scheduler
      OS schedulers need to be "fair". There are complex approaches, like RCU, priority inversion, priority inheritance, etc. to fix C.1., but most aren't useable in userspace (there even is a userspace RCU library, FWIW).
 
 
+= Driving the scheduler AKA the system timer =
+
+Scheduling is done using a single system timer
+
+  1. There is just one system timer, which drives LO event loop
+  2. The timer has to run in the main window thread
+  3. Messages are processed in order, so there is no real need for calling SendMessageW instead of PostMessageW
+  4. LO event loop is supposed to be processed in the main window thread with the Solar mutex acquired
+  5. The system timer is a single-shot timer
+
+
+= Locking (mp-sc) =
+
+Locking is implemented for multiple producers and a single consumer.
+
+While the consumer can process any task in the list, a producer is just allowed to append a task (like a queue).
+
+The scheduler is implicitly deinitialized, when VCL start deinitialization starts setting ImplSVData::mbDeInit to true.
+At this point no more tasks can be scheduled.
+
+The scheduler have to handle locking for the following situations:
+
+  1. when changing the last element
+    1.1 when adding an element
+    1.2 when removing the last element
+  2. when changing the list of freed scheduler objects
+  3. when invoking a task
+    3.1 prevent dispose of Scheduler while invoked
+    3.2 prevent detaching ImplSchedulerData from the Scheduler object
+
+Stop is handled by invalidating (nullptr) the ImplSchedulerData::mpScheduler, but keeping the Scheduler::mpSchedulerData pointer valid.
+The scheduler must always only run in the main thread.
+
+
+= Lifecycle / thread-safety of Scheduler-based objects =
+
+A scheduler object it thread-safe in the way, that it can be associated to any thread and any thread is free to call any functions on it. The owner must guarantee that the Invoke() function can be called, while the Scheduler object exists / is not disposed.
+
+The Dispose() function should be called before the object destruction or the destruction of any prerequisites of Invoke(). It'll block until the object can be freed securely, which means it is currently not invoked. Calls done on the object after Dispose() will do nothing.
+
+
 = Anti-pattern: Dependencies via (fine grained) priorities =
 
 "Idle 1" should run before "Idle 2", therefore give "Idle 1" a higher priority then "Idle 2".
@@ -57,7 +100,7 @@ The downside of this approach: Insert / Start / Reschedule(for "auto" tasks) now
 
 Currently Application::Reschedule() processes a single event or "all" events, with "all" defined as "100" events in most backends. This already is "ignored" by the KDE4 backend, as Qt defines its ProcessPendingEvents() as always processing all pending events (there are ways to skip event classes, but no easy but one hard way to process just a single event).
 
-== Convert Scheduler from single-linked list to queue ==
+== Convert Scheduler from single-linked list to a kind of "queue" ==
 
 Keep a pointer to the last list element to speed up adding new events.
 This is a prerequisite to implement I.2 of the "Thread-safe scheduler".