old/xalan-j/apidocs/org/apache/xml/dtm/ref/CoroutineManager.html - xalan-site - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
 <!--NewPage-->
 <HTML>
 <HEAD>
 <!-- Generated by javadoc on Thu Nov 22 17:12:56 EST 2007 -->
 <TITLE>
 Xalan-Java 2.7.1: Class  CoroutineManager
 </TITLE>
 <LINK REL ="stylesheet" TYPE="text/css" HREF="../../../../../stylesheet.css" TITLE="Style">
 </HEAD>
 <BODY BGCOLOR="white">

 <!-- ========== START OF NAVBAR ========== -->
 <A NAME="navbar_top"><!-- --></A>
 <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0">
 <TR>
 <TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
 <A NAME="navbar_top_firstrow"><!-- --></A>
 <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3">
   <TR ALIGN="center" VALIGN="top">
   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A>&nbsp;</TD>
   <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT>&nbsp;</TD>
   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="class-use/CoroutineManager.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
   </TR>
 </TABLE>
 </TD>
 <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
 </EM>
 </TD>
 </TR>

 <TR>
 <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
 &nbsp;PREV CLASS&nbsp;
 &nbsp;<A HREF="../../../../../org/apache/xml/dtm/ref/CustomStringPool.html"><B>NEXT CLASS</B></A></FONT></TD>
 <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
   <A HREF="../../../../../index.html" TARGET="_top"><B>FRAMES</B></A>  &nbsp;
 &nbsp;<A HREF="CoroutineManager.html" TARGET="_top"><B>NO FRAMES</B></A></FONT></TD>
 </TR>
 <TR>
 <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
   SUMMARY: &nbsp;INNER&nbsp;|&nbsp;FIELD&nbsp;|&nbsp;<A HREF="#constructor_summary">CONSTR</A>&nbsp;|&nbsp;<A HREF="#method_summary">METHOD</A></FONT></TD>
 <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
 DETAIL: &nbsp;FIELD&nbsp;|&nbsp;<A HREF="#constructor_detail">CONSTR</A>&nbsp;|&nbsp;<A HREF="#method_detail">METHOD</A></FONT></TD>
 </TR>
 </TABLE>
 <!-- =========== END OF NAVBAR =========== -->

 <HR>
 <!-- ======== START OF CLASS DATA ======== -->
 <H2>
 <FONT SIZE="-1">
 org.apache.xml.dtm.ref</FONT>
 <BR>
 Class  CoroutineManager</H2>
 <PRE>
 java.lang.Object
   |
   +--<B>org.apache.xml.dtm.ref.CoroutineManager</B>
 </PRE>
 <HR>
 <DL>
 <DT>public class <B>CoroutineManager</B><DT>extends java.lang.Object</DL>

 <P>
 <p>Support the coroutine design pattern.</p>

  <p>A coroutine set is a very simple cooperative non-preemptive
  multitasking model, where the switch from one task to another is
  performed via an explicit request. Coroutines interact according to
  the following rules:</p>

  <ul>
  <li>One coroutine in the set has control, which it retains until it
  either exits or resumes another coroutine.</li>
  <li>A coroutine is activated when it is resumed by some other coroutine
  for the first time.</li>
  <li>An active coroutine that gives up control by resuming another in
  the set retains its context -- including call stack and local variables
  -- so that if/when it is resumed, it will proceed from the point at which
  it last gave up control.</li>
  </ul>

  <p>Coroutines can be thought of as falling somewhere between pipes and
  subroutines. Like call/return, there is an explicit flow of control
  from one coroutine to another. Like pipes, neither coroutine is
  actually "in charge", and neither must exit in order to transfer
  control to the other. </p>

  <p>One classic application of coroutines is in compilers, where both
  the parser and the lexer are maintaining complex state
  information. The parser resumes the lexer to process incoming
  characters into lexical tokens, and the lexer resumes the parser
  when it has reached a point at which it has a reliably interpreted
  set of tokens available for semantic processing. Structuring this
  as call-and-return would require saving and restoring a
  considerable amount of state each time. Structuring it as two tasks
  connected by a queue may involve higher overhead (in systems which
  can optimize the coroutine metaphor), isn't necessarily as clear in
  intent, may have trouble handling cases where data flows in both
  directions, and may not handle some of the more complex cases where
  more than two coroutines are involved.</p>

  <p>Most coroutine systems also provide a way to pass data between the
  source and target of a resume operation; this is sometimes referred
  to as "yielding" a value.  Others rely on the fact that, since only
  one member of a coroutine set is running at a time and does not
  lose control until it chooses to do so, data structures may be
  directly shared between them with only minimal precautions.</p>

  <p>"Note: This should not be taken to mean that producer/consumer
  problems should be always be done with coroutines." Queueing is
  often a better solution when only two threads of execution are
  involved and full two-way handshaking is not required. It's a bit
  difficult to find short pedagogical examples that require
  coroutines for a clear solution.</p>

  <p>The fact that only one of a group of coroutines is running at a
  time, and the control transfer between them is explicit, simplifies
  their possible interactions, and in some implementations permits
  them to be implemented more efficiently than general multitasking.
  In some situations, coroutines can be compiled out entirely;
  in others, they may only require a few instructions more than a
  simple function call.</p>

  <p>This version is built on top of standard Java threading, since
  that's all we have available right now. It's been encapsulated for
  code clarity and possible future optimization.</p>

  <p>(Two possible approaches: wait-notify based and queue-based. Some
  folks think that a one-item queue is a cleaner solution because it's
  more abstract -- but since coroutine _is_ an abstraction I'm not really
  worried about that; folks should be able to switch this code without
  concern.)</p>

  <p>%TBD% THIS SHOULD BE AN INTERFACE, to facilitate building other
  implementations... perhaps including a true coroutine system
  someday, rather than controlled threading. Arguably Coroutine
  itself should be an interface much like Runnable, but I think that
  can be built on top of this.</p>
 <P>
 <HR>

 <P>
 <!-- ======== INNER CLASS SUMMARY ======== -->


 <!-- =========== FIELD SUMMARY =========== -->


 <!-- ======== CONSTRUCTOR SUMMARY ======== -->

 <A NAME="constructor_summary"><!-- --></A>
 <TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
 <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
 <TD COLSPAN=2><FONT SIZE="+2">
 <B>Constructor Summary</B></FONT></TD>
 </TR>
 <TR BGCOLOR="white" CLASS="TableRowColor">
 <TD><CODE><B><A HREF="../../../../../org/apache/xml/dtm/ref/CoroutineManager.html#CoroutineManager()">CoroutineManager</A></B>()</CODE>

 <BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</TD>
 </TR>
 </TABLE>
 &nbsp;
 <!-- ========== METHOD SUMMARY =========== -->

 <A NAME="method_summary"><!-- --></A>
 <TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
 <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
 <TD COLSPAN=2><FONT SIZE="+2">
 <B>Method Summary</B></FONT></TD>
 </TR>
 <TR BGCOLOR="white" CLASS="TableRowColor">
 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
 <CODE>&nbsp;java.lang.Object</CODE></FONT></TD>
 <TD><CODE><B><A HREF="../../../../../org/apache/xml/dtm/ref/CoroutineManager.html#co_entry_pause(int)">co_entry_pause</A></B>(int&nbsp;thisCoroutine)</CODE>

 <BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;In the standard coroutine architecture, coroutines are
  identified by their method names and are launched and run up to
  their first yield by simply resuming them; its's presumed that
  this recognizes the not-already-running case and does the right
  thing.</TD>
 </TR>
 <TR BGCOLOR="white" CLASS="TableRowColor">
 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
 <CODE>&nbsp;void</CODE></FONT></TD>
 <TD><CODE><B><A HREF="../../../../../org/apache/xml/dtm/ref/CoroutineManager.html#co_exit_to(java.lang.Object, int, int)">co_exit_to</A></B>(java.lang.Object&nbsp;arg_object,
            int&nbsp;thisCoroutine,
            int&nbsp;toCoroutine)</CODE>

 <BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Make the ID available for reuse and terminate this coroutine,
  transferring control to the specified coroutine.</TD>
 </TR>
 <TR BGCOLOR="white" CLASS="TableRowColor">
 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
 <CODE>&nbsp;void</CODE></FONT></TD>
 <TD><CODE><B><A HREF="../../../../../org/apache/xml/dtm/ref/CoroutineManager.html#co_exit(int)">co_exit</A></B>(int&nbsp;thisCoroutine)</CODE>

 <BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Terminate this entire set of coroutines.</TD>
 </TR>
 <TR BGCOLOR="white" CLASS="TableRowColor">
 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
 <CODE>&nbsp;int</CODE></FONT></TD>
 <TD><CODE><B><A HREF="../../../../../org/apache/xml/dtm/ref/CoroutineManager.html#co_joinCoroutineSet(int)">co_joinCoroutineSet</A></B>(int&nbsp;coroutineID)</CODE>

 <BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Each coroutine in the set managed by a single
  CoroutineManager is identified by a small positive integer.</TD>
 </TR>
 <TR BGCOLOR="white" CLASS="TableRowColor">
 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
 <CODE>&nbsp;java.lang.Object</CODE></FONT></TD>
 <TD><CODE><B><A HREF="../../../../../org/apache/xml/dtm/ref/CoroutineManager.html#co_resume(java.lang.Object, int, int)">co_resume</A></B>(java.lang.Object&nbsp;arg_object,
           int&nbsp;thisCoroutine,
           int&nbsp;toCoroutine)</CODE>

 <BR>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Transfer control to another coroutine which has already been started and
  is waiting on this CoroutineManager.</TD>
 </TR>
 </TABLE>
 &nbsp;<A NAME="methods_inherited_from_class_java.lang.Object"><!-- --></A>
 <TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
 <TR BGCOLOR="#EEEEFF" CLASS="TableSubHeadingColor">
 <TD><B>Methods inherited from class java.lang.Object</B></TD>
 </TR>
 <TR BGCOLOR="white" CLASS="TableRowColor">
 <TD><CODE>equals,
 getClass,
 hashCode,
 notify,
 notifyAll,
 toString,
 wait,
 wait,
 wait</CODE></TD>
 </TR>
 </TABLE>
 &nbsp;
 <P>

 <!-- ============ FIELD DETAIL =========== -->


 <!-- ========= CONSTRUCTOR DETAIL ======== -->

 <A NAME="constructor_detail"><!-- --></A>
 <TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
 <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
 <TD COLSPAN=1><FONT SIZE="+2">
 <B>Constructor Detail</B></FONT></TD>
 </TR>
 </TABLE>

 <A NAME="CoroutineManager()"><!-- --></A><H3>
 CoroutineManager</H3>
 <PRE>
 public <B>CoroutineManager</B>()</PRE>
 <DL>
 </DL>

 <!-- ============ METHOD DETAIL ========== -->

 <A NAME="method_detail"><!-- --></A>
 <TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
 <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
 <TD COLSPAN=1><FONT SIZE="+2">
 <B>Method Detail</B></FONT></TD>
 </TR>
 </TABLE>

 <A NAME="co_joinCoroutineSet(int)"><!-- --></A><H3>
 co_joinCoroutineSet</H3>
 <PRE>
 public int <B>co_joinCoroutineSet</B>(int&nbsp;coroutineID)</PRE>
 <DL>
 <DD><p>Each coroutine in the set managed by a single
  CoroutineManager is identified by a small positive integer. This
  brings up the question of how to manage those integers to avoid
  reuse... since if two coroutines use the same ID number, resuming
  that ID could resume either. I can see arguments for either
  allowing applications to select their own numbers (they may want
  to declare mnemonics via manefest constants) or generating
  numbers on demand.  This routine's intended to support both
  approaches.</p>

  <p>%REVIEW% We could use an object as the identifier. Not sure
  it's a net gain, though it would allow the thread to be its own
  ID. Ponder.</p><DD><DL>
 <DT><B>Parameters:</B><DD><CODE>coroutineID</CODE> - If >=0, requests that we reserve this number.
  If <0, requests that we find, reserve, and return an available ID
  number.<DT><B>Returns:</B><DD>If >=0, the ID number to be used by this coroutine. If <0,
  an error occurred -- the ID requested was already in use, or we
  couldn't assign one without going over the "unreasonable value" mark</DL>
 </DD>
 </DL>
 <HR>

 <A NAME="co_entry_pause(int)"><!-- --></A><H3>
 co_entry_pause</H3>
 <PRE>
 public java.lang.Object <B>co_entry_pause</B>(int&nbsp;thisCoroutine)
                                 throws java.lang.NoSuchMethodException</PRE>
 <DL>
 <DD>In the standard coroutine architecture, coroutines are
  identified by their method names and are launched and run up to
  their first yield by simply resuming them; its's presumed that
  this recognizes the not-already-running case and does the right
  thing. We seem to need a way to achieve that same threadsafe
  run-up...  eg, start the coroutine with a wait.

  %TBD% whether this makes any sense...<DD><DL>
 <DT><B>Parameters:</B><DD><CODE>thisCoroutine</CODE> - the identifier of this coroutine, so we can
  recognize when we are being resumed.<DT><B>Throws:</B><DD>java.lang.NoSuchMethodException - if thisCoroutine isn't
  a registered member of this group. %REVIEW% whether this is the
  best choice.</DL>
 </DD>
 </DL>
 <HR>

 <A NAME="co_resume(java.lang.Object, int, int)"><!-- --></A><H3>
 co_resume</H3>
 <PRE>
 public java.lang.Object <B>co_resume</B>(java.lang.Object&nbsp;arg_object,
                                   int&nbsp;thisCoroutine,
                                   int&nbsp;toCoroutine)
                            throws java.lang.NoSuchMethodException</PRE>
 <DL>
 <DD>Transfer control to another coroutine which has already been started and
  is waiting on this CoroutineManager. We won't return from this call
  until that routine has relinquished control.

  %TBD% What should we do if toCoroutine isn't registered? Exception?<DD><DL>
 <DT><B>Parameters:</B><DD><CODE>arg_object</CODE> - A value to be passed to the other coroutine.<DD><CODE>thisCoroutine</CODE> - Integer identifier for this coroutine. This is the
  ID we watch for to see if we're the ones being resumed.<DD><CODE>toCoroutine</CODE> - Integer identifier for the coroutine we wish to
  invoke.<DT><B>Throws:</B><DD>java.lang.NoSuchMethodException - if toCoroutine isn't a
  registered member of this group. %REVIEW% whether this is the best choice.</DL>
 </DD>
 </DL>
 <HR>

 <A NAME="co_exit(int)"><!-- --></A><H3>
 co_exit</H3>
 <PRE>
 public void <B>co_exit</B>(int&nbsp;thisCoroutine)</PRE>
 <DL>
 <DD>Terminate this entire set of coroutines. The others will be
  deregistered and have exceptions thrown at them. Note that this
  is intended as a panic-shutdown operation; under normal
  circumstances a coroutine should always end with co_exit_to() in
  order to politely inform at least one of its partners that it is
  going away.

  %TBD% This may need significantly more work.

  %TBD% Should this just be co_exit_to(,,CoroutineManager.PANIC)?<DD><DL>
 <DT><B>Parameters:</B><DD><CODE>thisCoroutine</CODE> - Integer identifier for the coroutine requesting exit.</DL>
 </DD>
 </DL>
 <HR>

 <A NAME="co_exit_to(java.lang.Object, int, int)"><!-- --></A><H3>
 co_exit_to</H3>
 <PRE>
 public void <B>co_exit_to</B>(java.lang.Object&nbsp;arg_object,
                        int&nbsp;thisCoroutine,
                        int&nbsp;toCoroutine)
                 throws java.lang.NoSuchMethodException</PRE>
 <DL>
 <DD>Make the ID available for reuse and terminate this coroutine,
  transferring control to the specified coroutine. Note that this
  returns immediately rather than waiting for any further coroutine
  traffic, so the thread can proceed with other shutdown activities.<DD><DL>
 <DT><B>Parameters:</B><DD><CODE>arg_object</CODE> - A value to be passed to the other coroutine.<DD><CODE>thisCoroutine</CODE> - Integer identifier for the coroutine leaving the set.<DD><CODE>toCoroutine</CODE> - Integer identifier for the coroutine we wish to
  invoke.<DT><B>Throws:</B><DD>java.lang.NoSuchMethodException - if toCoroutine isn't a
  registered member of this group. %REVIEW% whether this is the best choice.</DL>
 </DD>
 </DL>
 <!-- ========= END OF CLASS DATA ========= -->
 <HR>

 <!-- ========== START OF NAVBAR ========== -->
 <A NAME="navbar_bottom"><!-- --></A>
 <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0">
 <TR>
 <TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
 <A NAME="navbar_bottom_firstrow"><!-- --></A>
 <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3">
   <TR ALIGN="center" VALIGN="top">
   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A>&nbsp;</TD>
   <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT>&nbsp;</TD>
   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="class-use/CoroutineManager.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
   </TR>
 </TABLE>
 </TD>
 <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
 </EM>
 </TD>
 </TR>

 <TR>
 <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
 &nbsp;PREV CLASS&nbsp;
 &nbsp;<A HREF="../../../../../org/apache/xml/dtm/ref/CustomStringPool.html"><B>NEXT CLASS</B></A></FONT></TD>
 <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
   <A HREF="../../../../../index.html" TARGET="_top"><B>FRAMES</B></A>  &nbsp;
 &nbsp;<A HREF="CoroutineManager.html" TARGET="_top"><B>NO FRAMES</B></A></FONT></TD>
 </TR>
 <TR>
 <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
   SUMMARY: &nbsp;INNER&nbsp;|&nbsp;FIELD&nbsp;|&nbsp;<A HREF="#constructor_summary">CONSTR</A>&nbsp;|&nbsp;<A HREF="#method_summary">METHOD</A></FONT></TD>
 <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
 DETAIL: &nbsp;FIELD&nbsp;|&nbsp;<A HREF="#constructor_detail">CONSTR</A>&nbsp;|&nbsp;<A HREF="#method_detail">METHOD</A></FONT></TD>
 </TR>
 </TABLE>
 <!-- =========== END OF NAVBAR =========== -->

 <HR>
 Copyright © 2006 Apache XML Project. All Rights Reserved.
 </BODY>
 </HTML>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
	<!--NewPage-->
	<HTML>
	<HEAD>
	<!-- Generated by javadoc on Thu Nov 22 17:12:56 EST 2007 -->
	<TITLE>
	Xalan-Java 2.7.1: Class CoroutineManager
	</TITLE>
	<LINK REL ="stylesheet" TYPE="text/css" HREF="../../../../../stylesheet.css" TITLE="Style">
	</HEAD>
	<BODY BGCOLOR="white">

	<!-- ========== START OF NAVBAR ========== -->
	<A NAME="navbar_top"><!-- --></A>
	<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0">
	<TR>
	<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
	<A NAME="navbar_top_firstrow"><!-- --></A>
	<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3">
	<TR ALIGN="center" VALIGN="top">
	<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD>
	<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD>
	<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev">  <FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT> </TD>
	<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/CoroutineManager.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD>
	<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD>
	<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD>
	<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD>
	<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD>
	</TR>
	</TABLE>
	</TD>
	<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
	</EM>
	</TD>
	</TR>

	<TR>
	<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
	PREV CLASS
	<A HREF="../../../../../org/apache/xml/dtm/ref/CustomStringPool.html"><B>NEXT CLASS</B></A></FONT></TD>
	<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
	<A HREF="../../../../../index.html" TARGET="_top"><B>FRAMES</B></A>
	<A HREF="CoroutineManager.html" TARGET="_top"><B>NO FRAMES</B></A></FONT></TD>
	</TR>
	<TR>
	<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
	SUMMARY:  INNER \| FIELD \| <A HREF="#constructor_summary">CONSTR</A> \| <A HREF="#method_summary">METHOD</A></FONT></TD>
	<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
	DETAIL:  FIELD \| <A HREF="#constructor_detail">CONSTR</A> \| <A HREF="#method_detail">METHOD</A></FONT></TD>
	</TR>
	</TABLE>
	<!-- =========== END OF NAVBAR =========== -->

	<HR>
	<!-- ======== START OF CLASS DATA ======== -->
	<H2>
	<FONT SIZE="-1">
	org.apache.xml.dtm.ref</FONT>
	<BR>
	Class CoroutineManager</H2>
	<PRE>
	java.lang.Object
	\|
	+--<B>org.apache.xml.dtm.ref.CoroutineManager</B>
	</PRE>
	<HR>
	<DL>
	<DT>public class <B>CoroutineManager</B><DT>extends java.lang.Object</DL>

	<P>
	<p>Support the coroutine design pattern.</p>

	<p>A coroutine set is a very simple cooperative non-preemptive
	multitasking model, where the switch from one task to another is
	performed via an explicit request. Coroutines interact according to
	the following rules:</p>

	<ul>
	<li>One coroutine in the set has control, which it retains until it
	either exits or resumes another coroutine.</li>
	<li>A coroutine is activated when it is resumed by some other coroutine
	for the first time.</li>
	<li>An active coroutine that gives up control by resuming another in
	the set retains its context -- including call stack and local variables
	-- so that if/when it is resumed, it will proceed from the point at which
	it last gave up control.</li>
	</ul>

	<p>Coroutines can be thought of as falling somewhere between pipes and
	subroutines. Like call/return, there is an explicit flow of control
	from one coroutine to another. Like pipes, neither coroutine is
	actually "in charge", and neither must exit in order to transfer
	control to the other. </p>

	<p>One classic application of coroutines is in compilers, where both
	the parser and the lexer are maintaining complex state
	information. The parser resumes the lexer to process incoming
	characters into lexical tokens, and the lexer resumes the parser
	when it has reached a point at which it has a reliably interpreted
	set of tokens available for semantic processing. Structuring this
	as call-and-return would require saving and restoring a
	considerable amount of state each time. Structuring it as two tasks
	connected by a queue may involve higher overhead (in systems which
	can optimize the coroutine metaphor), isn't necessarily as clear in
	intent, may have trouble handling cases where data flows in both
	directions, and may not handle some of the more complex cases where
	more than two coroutines are involved.</p>

	<p>Most coroutine systems also provide a way to pass data between the
	source and target of a resume operation; this is sometimes referred
	to as "yielding" a value. Others rely on the fact that, since only
	one member of a coroutine set is running at a time and does not
	lose control until it chooses to do so, data structures may be
	directly shared between them with only minimal precautions.</p>

	<p>"Note: This should not be taken to mean that producer/consumer
	problems should be always be done with coroutines." Queueing is
	often a better solution when only two threads of execution are
	involved and full two-way handshaking is not required. It's a bit
	difficult to find short pedagogical examples that require
	coroutines for a clear solution.</p>

	<p>The fact that only one of a group of coroutines is running at a
	time, and the control transfer between them is explicit, simplifies
	their possible interactions, and in some implementations permits
	them to be implemented more efficiently than general multitasking.
	In some situations, coroutines can be compiled out entirely;
	in others, they may only require a few instructions more than a
	simple function call.</p>

	<p>This version is built on top of standard Java threading, since
	that's all we have available right now. It's been encapsulated for
	code clarity and possible future optimization.</p>

	<p>(Two possible approaches: wait-notify based and queue-based. Some
	folks think that a one-item queue is a cleaner solution because it's
	more abstract -- but since coroutine _is_ an abstraction I'm not really
	worried about that; folks should be able to switch this code without
	concern.)</p>

	<p>%TBD% THIS SHOULD BE AN INTERFACE, to facilitate building other
	implementations... perhaps including a true coroutine system
	someday, rather than controlled threading. Arguably Coroutine
	itself should be an interface much like Runnable, but I think that
	can be built on top of this.</p>
	<P>
	<HR>

	<P>
	<!-- ======== INNER CLASS SUMMARY ======== -->


	<!-- =========== FIELD SUMMARY =========== -->


	<!-- ======== CONSTRUCTOR SUMMARY ======== -->

	<A NAME="constructor_summary"><!-- --></A>
	<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
	<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
	<TD COLSPAN=2><FONT SIZE="+2">
	<B>Constructor Summary</B></FONT></TD>
	</TR>
	<TR BGCOLOR="white" CLASS="TableRowColor">
	<TD><CODE><B><A HREF="../../../../../org/apache/xml/dtm/ref/CoroutineManager.html#CoroutineManager()">CoroutineManager</A></B>()</CODE>

	<BR>
	</TD>
	</TR>
	</TABLE>

	<!-- ========== METHOD SUMMARY =========== -->

	<A NAME="method_summary"><!-- --></A>
	<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
	<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
	<TD COLSPAN=2><FONT SIZE="+2">
	<B>Method Summary</B></FONT></TD>
	</TR>
	<TR BGCOLOR="white" CLASS="TableRowColor">
	<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
	<CODE> java.lang.Object</CODE></FONT></TD>
	<TD><CODE><B><A HREF="../../../../../org/apache/xml/dtm/ref/CoroutineManager.html#co_entry_pause(int)">co_entry_pause</A></B>(int thisCoroutine)</CODE>

	<BR>
	In the standard coroutine architecture, coroutines are
	identified by their method names and are launched and run up to
	their first yield by simply resuming them; its's presumed that
	this recognizes the not-already-running case and does the right
	thing.</TD>
	</TR>
	<TR BGCOLOR="white" CLASS="TableRowColor">
	<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
	<CODE> void</CODE></FONT></TD>
	<TD><CODE><B><A HREF="../../../../../org/apache/xml/dtm/ref/CoroutineManager.html#co_exit_to(java.lang.Object, int, int)">co_exit_to</A></B>(java.lang.Object arg_object,
	int thisCoroutine,
	int toCoroutine)</CODE>

	<BR>
	Make the ID available for reuse and terminate this coroutine,
	transferring control to the specified coroutine.</TD>
	</TR>
	<TR BGCOLOR="white" CLASS="TableRowColor">
	<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
	<CODE> void</CODE></FONT></TD>
	<TD><CODE><B><A HREF="../../../../../org/apache/xml/dtm/ref/CoroutineManager.html#co_exit(int)">co_exit</A></B>(int thisCoroutine)</CODE>

	<BR>
	Terminate this entire set of coroutines.</TD>
	</TR>
	<TR BGCOLOR="white" CLASS="TableRowColor">
	<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
	<CODE> int</CODE></FONT></TD>
	<TD><CODE><B><A HREF="../../../../../org/apache/xml/dtm/ref/CoroutineManager.html#co_joinCoroutineSet(int)">co_joinCoroutineSet</A></B>(int coroutineID)</CODE>

	<BR>
	Each coroutine in the set managed by a single
	CoroutineManager is identified by a small positive integer.</TD>
	</TR>
	<TR BGCOLOR="white" CLASS="TableRowColor">
	<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
	<CODE> java.lang.Object</CODE></FONT></TD>
	<TD><CODE><B><A HREF="../../../../../org/apache/xml/dtm/ref/CoroutineManager.html#co_resume(java.lang.Object, int, int)">co_resume</A></B>(java.lang.Object arg_object,
	int thisCoroutine,
	int toCoroutine)</CODE>

	<BR>
	Transfer control to another coroutine which has already been started and
	is waiting on this CoroutineManager.</TD>
	</TR>
	</TABLE>
	<A NAME="methods_inherited_from_class_java.lang.Object"><!-- --></A>
	<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
	<TR BGCOLOR="#EEEEFF" CLASS="TableSubHeadingColor">
	<TD><B>Methods inherited from class java.lang.Object</B></TD>
	</TR>
	<TR BGCOLOR="white" CLASS="TableRowColor">
	<TD><CODE>equals,
	getClass,
	hashCode,
	notify,
	notifyAll,
	toString,
	wait,
	wait,
	wait</CODE></TD>
	</TR>
	</TABLE>

	<P>

	<!-- ============ FIELD DETAIL =========== -->


	<!-- ========= CONSTRUCTOR DETAIL ======== -->

	<A NAME="constructor_detail"><!-- --></A>
	<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
	<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
	<TD COLSPAN=1><FONT SIZE="+2">
	<B>Constructor Detail</B></FONT></TD>
	</TR>
	</TABLE>

	<A NAME="CoroutineManager()"><!-- --></A><H3>
	CoroutineManager</H3>
	<PRE>
	public <B>CoroutineManager</B>()</PRE>
	<DL>
	</DL>

	<!-- ============ METHOD DETAIL ========== -->

	<A NAME="method_detail"><!-- --></A>
	<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
	<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
	<TD COLSPAN=1><FONT SIZE="+2">
	<B>Method Detail</B></FONT></TD>
	</TR>
	</TABLE>

	<A NAME="co_joinCoroutineSet(int)"><!-- --></A><H3>
	co_joinCoroutineSet</H3>
	<PRE>
	public int <B>co_joinCoroutineSet</B>(int coroutineID)</PRE>
	<DL>
	<DD><p>Each coroutine in the set managed by a single
	CoroutineManager is identified by a small positive integer. This
	brings up the question of how to manage those integers to avoid
	reuse... since if two coroutines use the same ID number, resuming
	that ID could resume either. I can see arguments for either
	allowing applications to select their own numbers (they may want
	to declare mnemonics via manefest constants) or generating
	numbers on demand. This routine's intended to support both
	approaches.</p>

	<p>%REVIEW% We could use an object as the identifier. Not sure
	it's a net gain, though it would allow the thread to be its own
	ID. Ponder.</p><DD><DL>
	<DT><B>Parameters:</B><DD><CODE>coroutineID</CODE> - If >=0, requests that we reserve this number.
	If <0, requests that we find, reserve, and return an available ID
	number.<DT><B>Returns:</B><DD>If >=0, the ID number to be used by this coroutine. If <0,
	an error occurred -- the ID requested was already in use, or we
	couldn't assign one without going over the "unreasonable value" mark</DL>
	</DD>
	</DL>
	<HR>

	<A NAME="co_entry_pause(int)"><!-- --></A><H3>
	co_entry_pause</H3>
	<PRE>
	public java.lang.Object <B>co_entry_pause</B>(int thisCoroutine)
	throws java.lang.NoSuchMethodException</PRE>
	<DL>
	<DD>In the standard coroutine architecture, coroutines are
	identified by their method names and are launched and run up to
	their first yield by simply resuming them; its's presumed that
	this recognizes the not-already-running case and does the right
	thing. We seem to need a way to achieve that same threadsafe
	run-up... eg, start the coroutine with a wait.

	%TBD% whether this makes any sense...<DD><DL>
	<DT><B>Parameters:</B><DD><CODE>thisCoroutine</CODE> - the identifier of this coroutine, so we can
	recognize when we are being resumed.<DT><B>Throws:</B><DD>java.lang.NoSuchMethodException - if thisCoroutine isn't
	a registered member of this group. %REVIEW% whether this is the
	best choice.</DL>
	</DD>
	</DL>
	<HR>

	<A NAME="co_resume(java.lang.Object, int, int)"><!-- --></A><H3>
	co_resume</H3>
	<PRE>
	public java.lang.Object <B>co_resume</B>(java.lang.Object arg_object,
	int thisCoroutine,
	int toCoroutine)
	throws java.lang.NoSuchMethodException</PRE>
	<DL>
	<DD>Transfer control to another coroutine which has already been started and
	is waiting on this CoroutineManager. We won't return from this call
	until that routine has relinquished control.

	%TBD% What should we do if toCoroutine isn't registered? Exception?<DD><DL>
	<DT><B>Parameters:</B><DD><CODE>arg_object</CODE> - A value to be passed to the other coroutine.<DD><CODE>thisCoroutine</CODE> - Integer identifier for this coroutine. This is the
	ID we watch for to see if we're the ones being resumed.<DD><CODE>toCoroutine</CODE> - Integer identifier for the coroutine we wish to
	invoke.<DT><B>Throws:</B><DD>java.lang.NoSuchMethodException - if toCoroutine isn't a
	registered member of this group. %REVIEW% whether this is the best choice.</DL>
	</DD>
	</DL>
	<HR>

	<A NAME="co_exit(int)"><!-- --></A><H3>
	co_exit</H3>
	<PRE>
	public void <B>co_exit</B>(int thisCoroutine)</PRE>
	<DL>
	<DD>Terminate this entire set of coroutines. The others will be
	deregistered and have exceptions thrown at them. Note that this
	is intended as a panic-shutdown operation; under normal
	circumstances a coroutine should always end with co_exit_to() in
	order to politely inform at least one of its partners that it is
	going away.

	%TBD% This may need significantly more work.

	%TBD% Should this just be co_exit_to(,,CoroutineManager.PANIC)?<DD><DL>
	<DT><B>Parameters:</B><DD><CODE>thisCoroutine</CODE> - Integer identifier for the coroutine requesting exit.</DL>
	</DD>
	</DL>
	<HR>

	<A NAME="co_exit_to(java.lang.Object, int, int)"><!-- --></A><H3>
	co_exit_to</H3>
	<PRE>
	public void <B>co_exit_to</B>(java.lang.Object arg_object,
	int thisCoroutine,
	int toCoroutine)
	throws java.lang.NoSuchMethodException</PRE>
	<DL>
	<DD>Make the ID available for reuse and terminate this coroutine,
	transferring control to the specified coroutine. Note that this
	returns immediately rather than waiting for any further coroutine
	traffic, so the thread can proceed with other shutdown activities.<DD><DL>
	<DT><B>Parameters:</B><DD><CODE>arg_object</CODE> - A value to be passed to the other coroutine.<DD><CODE>thisCoroutine</CODE> - Integer identifier for the coroutine leaving the set.<DD><CODE>toCoroutine</CODE> - Integer identifier for the coroutine we wish to
	invoke.<DT><B>Throws:</B><DD>java.lang.NoSuchMethodException - if toCoroutine isn't a
	registered member of this group. %REVIEW% whether this is the best choice.</DL>
	</DD>
	</DL>
	<!-- ========= END OF CLASS DATA ========= -->
	<HR>

	<!-- ========== START OF NAVBAR ========== -->
	<A NAME="navbar_bottom"><!-- --></A>
	<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0">
	<TR>
	<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
	<A NAME="navbar_bottom_firstrow"><!-- --></A>
	<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3">
	<TR ALIGN="center" VALIGN="top">
	<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD>
	<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD>
	<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev">  <FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT> </TD>
	<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/CoroutineManager.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD>
	<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD>
	<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD>
	<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD>
	<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD>
	</TR>
	</TABLE>
	</TD>
	<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
	</EM>
	</TD>
	</TR>

	<TR>
	<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
	PREV CLASS
	<A HREF="../../../../../org/apache/xml/dtm/ref/CustomStringPool.html"><B>NEXT CLASS</B></A></FONT></TD>
	<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
	<A HREF="../../../../../index.html" TARGET="_top"><B>FRAMES</B></A>
	<A HREF="CoroutineManager.html" TARGET="_top"><B>NO FRAMES</B></A></FONT></TD>
	</TR>
	<TR>
	<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
	SUMMARY:  INNER \| FIELD \| <A HREF="#constructor_summary">CONSTR</A> \| <A HREF="#method_summary">METHOD</A></FONT></TD>
	<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
	DETAIL:  FIELD \| <A HREF="#constructor_detail">CONSTR</A> \| <A HREF="#method_detail">METHOD</A></FONT></TD>
	</TR>
	</TABLE>
	<!-- =========== END OF NAVBAR =========== -->

	<HR>
	Copyright © 2006 Apache XML Project. All Rights Reserved.
	</BODY>
	</HTML>