Wow, check out this use of ASCII artistry in the code comment in Brian Catrill's posting on Solaris 10 Revealed.
Bet you can't draw thatgood! :-)
/*
* DTrace Speculations
*
* Speculations have a per-CPU buffer and a global state. Once a speculation
* buffer has been committed or discarded, it cannot be reused until all CPUs
* have taken the same action (commit or discard) on their respective
* speculative buffer. However, because DTrace probes may execute in arbitrary
* context, other CPUs cannot simply be cross-called at probe firing time to
* perform the necessary commit or discard. The speculation states thus
* optimize for the case that a speculative buffer is only active on one CPU at
* the time of a commit() or discard() -- for if this is the case, other CPUs
* need not take action, and the speculation is immediately available for
* reuse. If the speculation is active on multiple CPUs, it must be
* asynchronously cleaned -- potentially leading to a higher rate of dirty
* speculative drops. The speculation states are as follows:
*
* DTRACESPEC_INACTIVE <= Initial state; inactive speculation
* DTRACESPEC_ACTIVE <= Allocated, but not yet speculatively traced to
* DTRACESPEC_ACTIVEONE <= Speculatively traced to on one CPU
* DTRACESPEC_ACTIVEMANY <= Speculatively traced to on more than one CPU
* DTRACESPEC_COMMITTING <= Currently being committed on one CPU
* DTRACESPEC_COMMITTINGMANY <= Currently being committed on many CPUs
* DTRACESPEC_DISCARDING <= Currently being discarded on many CPUs
*
* The state transition diagram is as follows:
*
* +----------------------------------------------------------+
* | |
* | +------------+ |
* | +-------------------| COMMITTING |<-----------------+ |
* | | +------------+ | |
* | | copied spec. ^ commit() on | | discard() on
* | | into principal | active CPU | | active CPU
* | | | commit() | |
* V V | | |
* +----------+ +--------+ +-----------+
* | INACTIVE |---------------->| ACTIVE |--------------->| ACTIVEONE |
* +----------+ speculation() +--------+ speculate() +-----------+
* ^ ^ | | |
* | | | discard() | |
* | | asynchronously | discard() on | | speculate()
* | | cleaned V inactive CPU | | on inactive
* | | +------------+ | | CPU
* | +-------------------| DISCARDING |<-----------------+ |
* | +------------+ |
* | asynchronously ^ |
* | copied spec. | discard() |
* | into principal +------------------------+ |
* | | V
* +----------------+ commit() +------------+
* | COMMITTINGMANY |<----------------------------------| ACTIVEMANY |
* +----------------+ +------------+
*/
{
(__)
(@@)
/-------\/
/ | ||
* ||----||
~~ ~~
}
