qspy_ref.txt

事件驱动程序设计很好的框架

\image html FigQSPY.01.jpg "Timing diagrams for all Philo state machines."

\section MATLAB_Q_ACTIVE Q_ACTIVE Matrix

The N-by-5 \c Q_ACTIVE matrix stores QS records pertaining to adding/removing
active objects and subscribing/unsubscribing to events from active objects.
The following table summarizes how the QS records are stored in the matrix:

<TABLE SUMMARY="Q_ACTIVE Matrix" cellSpacing=4 cellPadding=1 border=0
ALIGN="center">
  <TR bgColor="#c8cedc" ALIGN="center">
    <TD><B>&nbsp;MATLAB index --&gt;</B></TD>
    <TD><B>1</B></TD>
    <TD><B>2</B></TD>
    <TD><B>3</B></TD>
    <TD><B>4</B></TD>
    <TD><B>5</B></TD>
  </TR>

  <TR bgColor="#f0f0f0" ALIGN="center">
    <TD><B>QS Record\n |\n V</B></TD>
    <TD><B>Time\n Stamp</B></TD>
    <TD><B>Signal</B></TD>
    <TD><B>Active\n Object</B></TD>
    <TD><B>QF\n Priority</B></TD>
    <TD><B>Delta</B></TD>
  </TR>

  <TR bgColor="#c0c0c0" ALIGN="center">
    <TD>\c #QS_QF_ACTIVE_ADD</TD>
    <TD>#</TD>
    <TD>NaN</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>+1</TD>
  </TR>

  <TR bgColor="#f0f0f0" ALIGN="center">
    <TD>\c #QS_QF_ACTIVE_REMOVE</TD>
    <TD>#</TD>
    <TD>NaN</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>-1</TD>
  </TR>

  <TR bgColor="#c0c0c0" ALIGN="center">
    <TD>\c #QS_QF_ACTIVE_SUBSCRIBE</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>NaN</TD>
    <TD>+1</TD>
  </TR>

  <TR bgColor="#f0f0f0" ALIGN="center">
    <TD>\c #QS_QF_ACTIVE_UNSUBSCRIBE</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>NaN</TD>
    <TD>-1</TD>
  </TR>
</TABLE>

The following criteria (index matrices in MATLAB) unambiguously select the QS
records from the \c Q_ACTIVE matrix:

<TABLE SUMMARY="Q_ACTIVE records" cellSpacing=4 cellPadding=1 border=0
ALIGN="center">
  <TR bgColor="#c8cedc" ALIGN="center">
    <TD><B>QS Record</B></TD>
    <TD><B>MATLAB Index Matrix</B></TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>\c #QS_QF_ACTIVE_ADD</TD>
    <TD><TT>isnan(Q_ACTIVE(:,2)) & Q_ACTIVE(:,5) &gt; 0</TT></TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>\c #QS_QF_ACTIVE_REMOVE</TD>
    <TD><TT>isnan(Q_ACTIVE(:,2)) & Q_ACTIVE(:,5) &lt; 0</TT></TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>\c #QS_QF_ACTIVE_SUBSCRIBE</TD>
    <TD><TT>isnan(Q_ACTIVE(:,4)) & Q_ACTIVE(:,5) &gt; 0</TT></TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>\c #QS_QF_ACTIVE_UNSUBSCRIBE</TD>
    <TD><TT>isnan(Q_ACTIVE(:,4)) & Q_ACTIVE(:,5) &lt; 0</TT></TD>
  </TR>
</TABLE>


\section MATLAB_Q_EQUEUE Q_EQUEUE Matrix

The N-by-9 \c Q_EQUEUE matrix stores QS records pertaining to queuing events
in the QF. Both the active object event queues and the "raw" thread-safe
queues are included. The 'nUsed' field denotes the current number of used
entries in the queue. The 'Maximum nUsed' filed denotes the maximum number of
used entries since initialization (high watermark). Both fields contain the
number of used entries in the queues ring-buffer plus one, to account for the
extra location at the front of the queue. The following table summarizes how
the QS records are stored in the matrix:

<TABLE SUMMARY="Q_EQUEUE Matrix" cellSpacing=4 cellPadding=1 border=0
ALIGN="center">
  <TR bgColor="#c8cedc" ALIGN="center">
    <TD><B>&nbsp;MATLAB index --&gt;</B></TD>
    <TD><B>1</B></TD>
    <TD><B>2</B></TD>
    <TD><B>3</B></TD>
    <TD><B>4</B></TD>
    <TD><B>5</B></TD>
    <TD><B>6</B></TD>
    <TD><B>7</B></TD>
    <TD><B>8</B></TD>
    <TD><B>9</B></TD>
  </TR>

  <TR bgColor="#f0f0f0" ALIGN="center">
    <TD><B>QS Record\n |\n V</B></TD>
    <TD><B>Time\n Stamp</B></TD>
    <TD><B>Event\n Queue (1)</B></TD>
    <TD><B>nFree</B></TD>
    <TD><B>Minimum\n Used</B></TD>
    <TD><B>Signal</B></TD>
    <TD><B>Pool ID</B></TD>
    <TD><B>Ref.\n Count</B></TD>
    <TD><B>LIFO</B></TD>
    <TD><B>Delta</B></TD>
  </TR>

  <TR bgColor="#c0c0c0" ALIGN="center">
    <TD>\c #QS_QF_EQUEUE_INIT</TD>
    <TD>NaN</TD>
    <TD>#</TD>
    <TD>NaN</TD>
    <TD>0</TD>
    <TD>NaN</TD>
    <TD>NaN</TD>
    <TD>NaN</TD>
    <TD>0</TD>
    <TD>0</TD>
  </TR>

  <TR bgColor="#f0f0f0" ALIGN="center">
    <TD>\c #QS_QF_ACTIVE_POST_FIFO</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>0</TD>
    <TD>+1</TD>
  </TR>

  <TR bgColor="#c0c0c0" ALIGN="center">
    <TD>\c #QS_QF_ACTIVE_POST_LIFO</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>1</TD>
    <TD>+1</TD>
  </TR>

  <TR bgColor="#f0f0f0" ALIGN="center">
    <TD>\c #QS_QF_ACTIVE_GET</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>NaN</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>0</TD>
    <TD>-1</TD>
  </TR>

  <TR bgColor="#c0c0c0" ALIGN="center">
    <TD>\c #QS_QF_ACTIVE_GET_LAST</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>NaN</TD>
    <TD>NaN</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>0</TD>
    <TD>-1</TD>
  </TR>

  <TR bgColor="#f0f0f0" ALIGN="center">
    <TD>\c #QS_QF_EQUEUE_POST_FIFO</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>1</TD>
    <TD>#</TD>
    <TD>0</TD>
    <TD>+1</TD>
  </TR>

  <TR bgColor="#c0c0c0" ALIGN="center">
    <TD>\c #QS_QF_EQUEUE_POST_LIFO</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>1</TD>
    <TD>+1</TD>
  </TR>

  <TR bgColor="#f0f0f0" ALIGN="center">
    <TD>\c #QS_QF_EQUEUE_GET</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>0</TD>
    <TD>-1</TD>
  </TR>

  <TR bgColor="#c0c0c0" ALIGN="center">
    <TD>\c #QS_QF_EQUEUE_GET_LAST</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>NaN</TD>
    <TD>NaN</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>0</TD>
    <TD>-1</TD>
  </TR>
</TABLE>
(1) This field (index 2) is actually the pointer to the ring buffer of the
queue.

The following criteria (index matrices in MATLAB) unambiguously select the QS
records from the \c Q_EQUEUE matrix:

<TABLE SUMMARY="Q_EQUEUE records" cellSpacing=4 cellPadding=1 border=0
ALIGN="center">
  <TR bgColor="#c8cedc" ALIGN="center">
    <TD><B>QS Record</B></TD>
    <TD><B>MATLAB Index Matrix</B></TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>\c #QS_QF_EQUEUE_INIT</TD>
    <TD><TT>Q_EQUEUE(:,9) == 0</TT></TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>\c #QS_QF_ACTIVE_POST_FIFO</TD>
    <TD><TT>Q_EQUEUE(:,2) == &lt;active obj&gt; & ~Q_EQUEUE(:,8) & Q_EQUEUE(:,9) &gt; 0</TT></TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>\c #QS_QF_ACTIVE_POST_LIFO</TD>
    <TD><TT>Q_EQUEUE(:,2) == &lt;active obj&gt; & Q_EQUEUE(:,8) & Q_EQUEUE(:,9) &gt; 0</TT></TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>\c #QS_QF_ACTIVE_GET</TD>
    <TD><TT>Q_EQUEUE(:,2) == &lt;active obj&gt; & ~isnan(Q_EQUEUE(:,3) & Q_EQUEUE(:,9) &lt; 0</TT></TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>\c #QS_QF_ACTIVE_GET_LAST</TD>
    <TD><TT>Q_EQUEUE(:,2) == &lt;active obj&gt; & isnan(Q_EQUEUE(:,3) & Q_EQUEUE(:,9) &lt; 0</TT></TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>\c #QS_QF_EQUEUE_POST_FIFO</TD>
    <TD><TT>Q_EQUEUE(:,2) == &lt;raw queue&gt; & ~Q_EQUEUE(:,8) & Q_EQUEUE(:,9) &gt; 0</TT></TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>\c #QS_QF_EQUEUE_POST_LIFO</TD>
    <TD><TT>Q_EQUEUE(:,2) == &lt;raw queue&gt; & Q_EQUEUE(:,8) & Q_EQUEUE(:,9) &gt; 0</TT></TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>\c #QS_QF_EQUEUE_GET</TD>
    <TD><TT>Q_EQUEUE(:,2) == &lt;raw queue&gt; & ~isnan(Q_EQUEUE(:,3) & Q_EQUEUE(:,9) &lt; 0</TT></TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>\c #QS_QF_EQUEUE_GET_LAST</TD>
    <TD><TT>Q_EQUEUE(:,2) == &lt;raw queue&gt; & isnan(Q_EQUEUE(:,3) & Q_EQUEUE(:,9) &lt; 0</TT></TD>
  </TR>
</TABLE>


\section MATLAB_Q_MPOOL Q_MPOOL Matrix

The N-by-5 \c Q_MPOOL matrix stores QS records pertaining to memory pools in
the QF. The 'nFree' field denotes the current number of free blocks in the
event pool. The 'Minimum nFree' filed denotes the minimal number of free
blocks since initialization (low watermark). The following table summarizes
how the QS records are stored in the matrix:

<TABLE SUMMARY="Q_MPOOL Matrix" cellSpacing=4 cellPadding=1 border=0
ALIGN="center">
  <TR bgColor="#c8cedc" ALIGN="center">
    <TD><B>&nbsp;MATLAB index --&gt;</B></TD>
    <TD><B>1</B></TD>
    <TD><B>2</B></TD>
    <TD><B>3</B></TD>
    <TD><B>4</B></TD>
    <TD><B>5</B></TD>
  </TR>

  <TR bgColor="#f0f0f0" ALIGN="center">
    <TD><B>QS Record\n |\n V</B></TD>
    <TD><B>Time\n Stamp</B></TD>
    <TD><B>Pool\n Object</B></TD>
    <TD><B>nFree</B></TD>
    <TD><B>Minimal\n nFree</B></TD>
    <TD><B>Delta</B></TD>
  </TR>

  <TR bgColor="#c0c0c0" ALIGN="center">
    <TD>\c #QS_QF_MPOOL_INIT</TD>
    <TD>NaN</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>NaN</TD>
    <TD>0</TD>
  </TR>

  <TR bgColor="#f0f0f0" ALIGN="center">
    <TD>\c #QS_QF_MPOOL_GET</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>-1</TD>
  </TR>

  <TR bgColor="#c0c0c0" ALIGN="center">
    <TD>\c #QS_QF_MPOOL_PUT</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>NaN</TD>
    <TD>+1</TD>
  </TR>
</TABLE>

The cumulative sum over the 'Delta' column should not have any long-time
trends, because this would indicate a leak from the pool. The following
picture shows the plot for the test data.

\image html FigQSPY.02.jpg "Plot stairs(Q_MPOOL(:,1), cumsum(Q_MPOOL(:,5)))"

The following criteria (index matrices in MATLAB) unambiguously select the QS
records from the \c Q_MPOOL matrix:

<TABLE SUMMARY="Q_MPOOL records" cellSpacing=4 cellPadding=1 border=0
ALIGN="center">
  <TR bgColor="#c8cedc" ALIGN="center">
    <TD><B>QS Record</B></TD>
    <TD><B>MATLAB Index Matrix</B></TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>\c #QS_QF_MPOOL_INIT</TD>
    <TD><TT>Q_MPOOL(:,5) == 0</TT></TD>
  </TR>

  <TR bgColor="#c0c0c0">
    <TD>\c #QS_QF_MPOOL_GET</TD>
    <TD><TT>Q_MPOOL(:,5) &lt; 0</TT></TD>
  </TR>

  <TR bgColor="#f0f0f0">
    <TD>\c #QS_QF_MPOOL_PUT</TD>
    <TD><TT>Q_MPOOL(:,5) &gt; 0</TT></TD>
  </TR>
</TABLE>


\section MATLAB_Q_NEW Q_NEW Matrix

The N-by-6 \c Q_NEW matrix stores QS records pertaining to dynamic event
allocation and automatic event recycling (garbage collection) in the QF. The
following table summarizes how the QS records are stored in the matrix:

<TABLE SUMMARY="Q_NEW Matrix" cellSpacing=4 cellPadding=1 border=0
ALIGN="center">
  <TR bgColor="#c8cedc" ALIGN="center">
    <TD><B>&nbsp;MATLAB index --&gt;</B></TD>
    <TD><B>1</B></TD>
    <TD><B>2</B></TD>
    <TD><B>3</B></TD>
    <TD><B>4</B></TD>
    <TD><B>5</B></TD>
    <TD><B>6</B></TD>
  </TR>

  <TR bgColor="#f0f0f0" ALIGN="center">
    <TD><B>QS Record\n |\n V</B></TD>
    <TD><B>Time\n Stamp</B></TD>
    <TD><B>Signal</B></TD>
    <TD><B>PoolID</B></TD>
    <TD><B>Ref.\n Count</B></TD>
    <TD><B>Event\n Size</B></TD>
    <TD><B>Delta</B></TD>
  </TR>

  <TR bgColor="#c0c0c0" ALIGN="center">
    <TD>\c #QS_QF_NEW</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>NaN</TD>
    <TD>NaN</TD>
    <TD>#</TD>
    <TD>+1</TD>
  </TR>

  <TR bgColor="#f0f0f0" ALIGN="center">
    <TD>\c #QS_QF_GC_ATTEMPT</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>NaN</TD>
    <TD>0</TD>
  </TR>

  <TR bgColor="#c0c0c0" ALIGN="center">
    <TD>\c #QS_QF_GC</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>#</TD>
    <TD>NaN</TD>
    <TD>NaN</TD>
    <TD>-1</TD>
  </TR>
</TABLE>

The cumulative sum over the 'Delta' column should not have any long-time
trends, because this would indicate event leak. The following picture shows
the plot for the test data.

\image html FigQSPY.03.jpg "Plot stairs(Q_NEW(:,1), cumsum(Q_NEW(:,6)))"

The following criteria (index matrices in MATLAB) unambiguously select the QS
records from the \c Q_NEW matrix:

<TABLE SUMMARY="Q_NEW records" cellSpacing=4 cellPadding=1 border=0
ALIGN="center">
  <TR bgColor="#c8cedc" ALIGN="center">
    <TD><B>QS Record</B></TD>