1 files changed, 65 insertions, 0 deletions
diff --git a/docs/comm/the-beast/optimistic.html b/docs/comm/the-beast/optimistic.html
new file mode 100644
index 0000000000..4d158022e8
--- /dev/null
+++ b/docs/comm/the-beast/optimistic.html
@@ -0,0 +1,65 @@
+<h2> Architectural stuff </h2>
+
+New fields in the TSO:
+<ul>
+<li> New global speculation-depth register; always counts the number of specuation frames
+on the stack; incremented when 
+starting speculation, decremented when finishing.
+<li> Profiling stuff
+</ul>
+
+
+<h2> Speculation frames </h2>
+
+The info table for a speculation frame points to the static spec-depth configuration
+for that speculation point. (Points to, because the config is mutable, and the info
+table has to be adjacent to the (immutable) code.)
+
+ 
+
+<h2> Abortion</h2>
+
+Abortion is modelled by a special asynchronous exception ThreadAbort.
+
+<ul>
+<li> In the scheduler, if a thread returns with ThreadBlocked, and non-zero SpecDepth, send it
+an asynchronous exception.
+
+<li> In the implementation of the <tt>catch#</tt> primop, raise an asynchonous exception if 
+SpecDepth is nonzero.
+
+<li> Timeout, administered by scheduler.  Current story: abort if a speculation frame lasts from
+one minor GC to the next.  We detect this by seeing if there's a profiling frame on the stack --- a 
+profiling frame is added at a minor GC in place of a speculation frame (see Online Profiling).
+</ul>
+
+
+When tearing frames off the stack, we start a new chunk at every speculation frame, as well as every
+update frame.  We proceed down to the deepest speculation frame.  
+<p>
+The <tt>AP_STACK</tt> closure built for a speculation frame must be careful <em>not</em> to enter the 
+next <tt>AP_STACK</tt> closure up, because that would re-enter a possible loop.
+<p>
+Delivering an asynch exception to a thread that is speculating.  Invariant: there can be no catch frames
+inside speculation (we abort in <tt>catch#</tt> when speculating.  So the asynch exception just 
+tears off frames in the standard way until it gets to a catch frame, just as it would usually do.
+<p>
+Abortion can punish one or more of the speculation frames by decrementing their static config variables.
+
+<h3>Synchronous exceptions</h3>
+ 
+Synchronous exceptions are treated similarly as before.  The stack is discarded up to an update frame; the
+thunk to be updated is overwritten with "raise x", and the process continues.  Until a catch frame.
+<p>
+When we find a spec frame, we allocate a "raise x" object, and resume execution with the return address
+in the spec frame.  In that way the spec frame is like a catch frame; it stops the unwinding process.
+<p>
+It's essential that every hard failure is caught, else speculation is unsafe.  In particular, divide by zero
+is hard to catch using OS support, so we test explicitly in library code.  You can shoot yourself in the foot 
+by writing <tt>x `div#` 0</tt>, side-stepping the test.
+
+
+<h3> Online profiling </h3>
+
+Sampling can be more frequent than minor GC (by jiggling the end-of-block code) but cannot
+be less frequent, because GC doesn't expect to see profiling frames.
+\ No newline at end of file