From 08bae37de7b0f23854e5cb4ce4589a3846feb52d Mon Sep 17 00:00:00 2001
From: Ichthyostega <prg@ichthyostega.de>
Date: Wed, 9 Jan 2013 12:27:45 +0100
Subject: [PATCH] RFC: Scheduler Requirements

initial draft of an RfC to discuss and define the
requirements for other parts of the application to relie on
---
 doc/devel/rfc/SchedulerRequirements.txt       | 122 ++++++++++++++++++
 .../rfc_pending/SchedulerRequirements.txt     |   1 +
 2 files changed, 123 insertions(+)
 create mode 100644 doc/devel/rfc/SchedulerRequirements.txt
 create mode 120000 doc/devel/rfc_pending/SchedulerRequirements.txt

diff --git a/doc/devel/rfc/SchedulerRequirements.txt b/doc/devel/rfc/SchedulerRequirements.txt
new file mode 100644
index 000000000..71b504efb
--- /dev/null
+++ b/doc/devel/rfc/SchedulerRequirements.txt
@@ -0,0 +1,122 @@
+SchedulerRequirements
+=====================
+
+// please don't remove the //word: comments
+
+[grid="all"]
+`------------`-----------------------
+*State*         _Idea_
+*Date*          _Mi 09 Jan 2013 12:04:03 CET_
+*Proposed by*   Ichthyostega <prg@ichthyostega.de>
+-------------------------------------
+
+********************************************************************************
+.Abstract
+The rendering and playback subsystem relies on a Scheduler component to invoke
+individual frame rendering and resource fetching jobs. This RfC summarises the
+general assumptions and requirements other parts of the application are relying
+on
+********************************************************************************
+
+Define the core properties and requirements of the Scheduler.
+
+Description
+-----------
+//description: add a detailed description:
+
+The *Scheduler* is responsible for getting the individual _render jobs_ to run.
+The basic idea is that individual render jobs _should never block_ -- and thus
+the calculation of a single frame might be split into several atomic jobs,
+including resource fetching. Together with the data exchange protocol defined
+for the `OutputSlot`, and the requirements of storage management (especially
+releasing of superseded render nodes -> `Fixture` storage), this leads to
+certain requirements to be ensured by the scheduler:
+
+ordering of jobs::
+  the scheduler has to ensure all prerequisites of a given job are met
+  
+job time window::
+  when it is not possible to run a job within the defined target time window, it
+  must not be run any more but rather be marked as failure
+
+failure propagation::
+  when a job fails, either due to an job internal error, or by timing glitch,
+  any dependent jobs need to receive that failure state
+
+guaranteed execution::
+  some jobs are marked as ``ensure run''. These need to run reliable, even when
+  prerequisite jobs fail -- and this failure state needs to be propagated
+
+detecting termination
+~~~~~~~~~~~~~~~~~~~~~
+
+The way other parts of the system are built, requires us to obtain a guaranteed
+knowledge of some job's termination. It is possible to obtain that knowledge
+with some limited delay, but it needs to be absolutely reliable (violations
+leading to segfault). The requirements stated above assume this can be achieved
+through _jobs with guaranteed execution._ Alternatively we could consider
+installing specific callbacks -- in this case the scheduler itself has to
+_guarantee the invocation of these callbacks,_ even if the corresponding job
+fails or is never invoked. It doesn't seem like there is any other option.
+
+
+
+Tasks
+~~~~~
+// List what needs to be done to implement this Proposal:
+// * first step ([green]#✔ done#)
+ * define the job interface [yellow-background]#WIP#
+ * define a protocol for job state handling [red yellow-background]#TBD#
+ * define the representation of dependencies and the notifications in practice [red yellow-background]#TBD#
+ * verify the proposed requirements by an scheduler implementation sketch [red yellow-background]#TBD#
+
+
+///////
+
+Discussion
+~~~~~~~~~~
+
+Pros
+^^^^
+// add a fact list/enumeration which make this suitable:
+//  * foo
+//  * bar ...
+
+
+
+Cons
+^^^^
+// fact list of the known/considered bad implications:
+
+
+
+Alternatives
+^^^^^^^^^^^^
+//alternatives: explain alternatives and tell why they are not viable:
+
+/////////
+
+
+Rationale
+---------
+//rationale: Give a concise summary why it should be done *this* way:
+[red yellow-background]#to be written#
+
+
+//Conclusion
+//----------
+//conclusion: When approbate (this proposal becomes a Final)
+//            write some conclusions about its process:
+
+
+
+
+Comments
+--------
+//comments: append below
+
+
+//endof_comments:
+
+''''
+Back to link:/documentation/devel/rfc.html[Lumiera Design Process overview]
diff --git a/doc/devel/rfc_pending/SchedulerRequirements.txt b/doc/devel/rfc_pending/SchedulerRequirements.txt
new file mode 120000
index 000000000..58a4257c2
--- /dev/null
+++ b/doc/devel/rfc_pending/SchedulerRequirements.txt
@@ -0,0 +1 @@
+../rfc/SchedulerRequirements.txt
\ No newline at end of file