1 files changed, 49 insertions, 0 deletions
diff --git a/docs/reservation-lifecycle b/docs/reservation-lifecycle
new file mode 100644
index 0000000..593347f
--- /dev/null
+++ b/docs/reservation-lifecycle
@@ -0,0 +1,49 @@
+
+== Problem: Define the uid reservation lifecycle ==  #none
+
+Situation:
+
+  Several processes are engaged in uid reservation, use, or collection. A
+  precise description of the life-cycle for uids will help avoid race
+  conditions between these processes.
+
+Thoughts:
+
+  A state-cell is created in the 'launching_<pid>' state.
+    (uid is known, but not yet in use.)
+
+  The reservation is atomically symlinked to the pre-initialized state-cell.
+    This way, the reservation always starts off in a consistent state.
+
+  Perhaps, the launch succeeds in dropping privileges:
+    - The reservation can be now be marked 'launch_succeeded'.
+    - 'launch_succeeded' uids can be collected whenever there are no processes
+      running under 'uid'.
+    - However, because permissions were dropped, some other process will need
+      to update the state-cell.
+
+  Perhaps, the launch fails to drop privileges and exits abnormally or diverges:
+    - Since divergence will be rare, we can speed things up by marking the
+      reservations of known-failed launches as 'launch_failed'.
+    - 'launch_failed' uids can be collected at any time.
+    - Divergent uids will be halted by reboots and their reservations can be
+      collected at system startup.
+
+  From time to time, a gc step examines reservations.
+
+    Reservations for '<uid>' marked as 'launching_<pid>' should be collected if
+    <pid> is no longer running.
+      - (How do we handle reboot detection?)
+
+    Reservations marked as 'launch_succeeded' should be collected
+
+    marked 'launch_succeeded', 'launch_failed':
+      the gc process may decide to claim the reservation by marking it
+      'gcing_<pid>'
+
+  gc succeeds: reservation is deleted.
+
+  gc fails: the reservation will never be touched by rainbow-daemon again. (other
+      collection tools might be applied, but only under controlled
+      circumstances)
+