More implementation details for atomic ordering constraints

Author: alice-i-cecile

rfcs/45-stageless.md

@@ -230,14 +230,7 @@ In order to understand exactly what this means, we need to understand atomic ord
 At least, as far as "directly after" is a meaningful concept in a parallel, nonlinear ordering.
 Like the atom, they are indivisible: nothing can get between them!
 
-To be fully precise, if we have system `A` that runs "atomically before" system `B` (`.add_system(a.atomically_before(b))`):
-
-- `A` is strictly before `B`
-- the "write" data locks of system `A` are relaxed to "read" data locks upon system `A`'s completion
-- "read" data locks of system `A` will not be released until system `B` (and all other atomic dependents) has completed
-- the data locks from system `A` are ignored for the purposes of checking if system `B` can run
-  - after all, they're not actualy locked, merely reserved
-  - competing read-locks caused by other systems will still need to complete before a data store can be mutated; the effect is to "ignore the locks of `A`", not "skip the check completely"
+To be more precise, if a system `A` is `atomically_before` system `B`, nothing (other than system `B`) can mutate the data that system `A` could access.
 
 In addition to their use in run criteria, atomic ordering constraints are extremely useful for forcing tight interlocking behavior between systems.
 They allow us to ensure that the state read from and written to the earlier system cannot be invalidated.
@@ -450,6 +443,21 @@ struct SystemConfig {
 }
 ```
 
+### Atomic ordering constraints
+
+To be fully precise, if we have system `A` that runs "atomically before" system `B` (`.add_system(a.atomically_before(b))`):
+
+- `A` is strictly before `B`
+- the "write" data locks of system `A` are relaxed to "read" data locks upon system `A`'s completion
+- "read" data locks of system `A` will not be released until system `B` (and all other atomic dependents) have completed
+- the data locks from system `A` are ignored for the purposes of checking if system `B` can run
+  - after all, they're not actualy locked, merely reserved
+  - competing read-locks caused by other systems will still need to complete before a data store can be mutated; the effect is to "ignore the locks of `A`", not "skip the check completely"
+  - if and only if `A` has multiple atomic dependents, they cannot mutate the data read by `A`, as that would invalidate the state created by `A` that other dependents may be relying on
+
+In addition, atomic ordering constraints introduce a new form of schedule unsatisfiability.
+If a system must run between `A` and `B`, but can mutate data that `A` has access to, the schedule is unsatisfiable.
+
 ### Flushed ordering constraints
 
 Being able to assert that commands are processed (or state is flushed) between two systems is a critical requirement for being able to specify logically-meaningful ordering of systems without a global view of the schedule.
@@ -529,6 +537,8 @@ There are two reasons why this doesn't work:
 In practice, almost all run criteria are extremely simple, and fast to check.
 Verifying that the cache is still valid will require access to the data anyways, and involve more overhead than simple computations on one or two resources.
 
+In addition, adding multiple atomic ordering constraints originating from a single system is extremely prone to dead-locks; we should not hand users this foot-gun.
+
 ### Why do we want to store multiple schedules in the `App`?
 
 We could store these in a resource in the `World`.