Merge pull request #80 from lf-lang/document-modular-schedulers

Document modular schedulers.

Author: petervdonovan

packages/documentation/copy/en/reference/Target Language Details.md

@@ -2673,6 +2673,25 @@ Note that when building with a release profile (i.e., target property `build-typ
 
 </div>
 
+<div class="lf-c lf-py">
+
+## Scheduler Target Property
+
+The `scheduler` target property is used to select the scheduler used by the C runtime. This scheduler determines the exact order in which reactions are processed, as long as the order complies with the deterministic semantics of Lingua Franca. It also assigns reactions to user-level threads and can thereby influence the assignment of reactions to processors.
+
+Because the C runtime scheduler operates at a higher level of abstraction than the OS, none of the scheduling policies that we currently support allow preemption; furthermore, they do not control migration of threads between processors.
+
+Another limitation of these schedulers is that they are constrained to process the reaction graph breadth-first. We define the _level_ of a reaction _r_ to be the length of the longest chain of causally dependent reactions that are all (causally) upstream of _r_. Current LF schedulers process one level of reactions at a time, but this constraint is more restrictive than necessary to implement Lingua Franca's semantics and is notable only for its effect on execution times.
+
+The following schedulers are available:
+
+- `GEDF_NP` (global earliest-deadline-first): This scheduler is the default scheduler for programs that have deadlines. When the semantics of Lingua Franca allows for concurrent execution of two or more ready reactions with the same level at a particular tag, this scheduler will prioritize the reaction with the earliest deadline to run first (but with the limitation that reaction executions are non-preemptive). Reactions with no explicit deadline implicitly have an infinitely late deadline.
+- `NP` (non-preemptive): This scheduler is the default scheduler for programs that have no deadlines. It makes minimal guarantees about its behavior, and this allows it to include optimizations that can result in lower execution times than the GEDF_NP scheduler.
+- `adaptive`: This scheduler behaves similarly to the `NP` scheduler, with the additional limitation that it is designed for applications that can tolerate potentially wide variability in physical execution times. It performs experiments and measures execution times at runtime to determine the degree of exploitable parallelism in various parts of the program. This lets it automate judgments which are made more naively by the other schedulers and which are typically made by the programmer in general-purpose languages.
+- `GEDF_NP_CI` (global earliest-deadline-first, with chain ID): This scheduler implements the same policy as `GEDF_NP`, but it is designed for an optimization called chain ID that is described on page 92 [here](https://www2.eecs.berkeley.edu/Pubs/TechRpts/2020/EECS-2020-235.pdf). This optimization is currently disabled because it is not yet fully developed, so we advise against the use of this scheduler in practical applications.
+
+</div>
+
 [comment]: <> (================= NEW SECTION =====================)
 
 ## Target Implementation Details