thoughts on scope

distaff/src/scope.rs

@@ -18,6 +18,39 @@ use crate::{
     workerthread::WorkerThread,
 };
 
+// thinking:
+
+// the scope needs to keep track of any spawn() and spawn_async() calls, across all worker threads.
+// that means, that for any spawn() or spawn_async() calls, we have to share a counter across all worker threads.
+// we want to minimise the number of atomic operations in general.
+// atomic operations occur in the following cases:
+// - when we spawn() or spawn_async() a job, we increment the counter
+// - when the same job finishes, we decrement the counter
+// - when a join() job finishes, it's latch is set
+// - when we wait for a join() job, we loop over the latch until it is set
+
+// find below a sketch of an unbalanced tree:
+//              []
+//             /  \
+//           []    []
+//          /  \   / \
+//        []   [] [] []
+//       /  \  /  \
+//     []   [][]  []
+//    /  \   /  \
+//   []  [] []  []
+//  /  \   /  \
+// []  [] []  []
+//    /  \
+//   []  []
+
+// in this tree of join() calls, it is possible to wait for a long time, so it is necessary to keep waking up when a job is shared.
+
+// the worker waits on it's latch, which may be woken by:
+// - a job finishing
+// - another thread sharing a job
+// - the heartbeat waking up the worker // does this make sense? if the thread was sleeping, it didn't have any work to share.
+
 pub struct Scope<'scope, 'env: 'scope> {
     // latch to wait on before the scope finishes
     job_counter: CountLatch<MutexLatch>,