org.apache.xml.dtm.ref

## Class CoroutineManager

- java.lang.Object
- - org.apache.xml.dtm.ref.CoroutineManager

    public class CoroutineManager
    extends java.lang.Object

Support the coroutine design pattern.

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:

- One coroutine in the set has control, which it retains until it either exits or resumes another coroutine.
- A coroutine is activated when it is resumed by some other coroutine for the first time.
- 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.

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.

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.

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.

"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.

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.

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.

(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.)

%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.

### Constructor Summary

Constructors
Constructor and Description
`CoroutineManager()`

### Method Summary

Methods
`java.lang.Object` `co_entry_pause(int thisCoroutine)` 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.
`void` `co_exit_to(java.lang.Object arg_object, int thisCoroutine, int toCoroutine)` Make the ID available for reuse and terminate this coroutine, transferring control to the specified coroutine.
`void` `co_exit(int thisCoroutine)` Terminate this entire set of coroutines.
`int` `co_joinCoroutineSet(int coroutineID)` Each coroutine in the set managed by a single CoroutineManager is identified by a small positive integer.
`java.lang.Object` `co_resume(java.lang.Object arg_object, int thisCoroutine, int toCoroutine)` Transfer control to another coroutine which has already been started and is waiting on this CoroutineManager.

### Methods inherited from class java.lang.Object

`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### CoroutineManager

    public CoroutineManager()

### Method Detail

#### co_joinCoroutineSet

    public int co_joinCoroutineSet(int coroutineID)

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.

%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.

Parameters:
  `coroutineID` - If >=0, requests that we reserve this number. If <0, requests that we find, reserve, and return an available ID number.
Returns:
  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

#### co_entry_pause

    public java.lang.Object co_entry_pause(int thisCoroutine)
                                    throws java.lang.NoSuchMethodException

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...

Parameters:
  `thisCoroutine` - the identifier of this coroutine, so we can recognize when we are being resumed.
Throws:
  `java.lang.NoSuchMethodException` - if thisCoroutine isn't a registered member of this group. %REVIEW% whether this is the best choice.

#### co_resume

    public java.lang.Object co_resume(java.lang.Object arg_object,
                             int thisCoroutine,
                             int toCoroutine)
                               throws java.lang.NoSuchMethodException

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?

Parameters:
  `arg_object` - A value to be passed to the other coroutine.
  `thisCoroutine` - Integer identifier for this coroutine. This is the ID we watch for to see if we're the ones being resumed.
  `toCoroutine` - Integer identifier for the coroutine we wish to invoke.
Throws:
  `java.lang.NoSuchMethodException` - if toCoroutine isn't a registered member of this group. %REVIEW% whether this is the best choice.

#### co_exit

    public void co_exit(int thisCoroutine)

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)?

Parameters:
  `thisCoroutine` - Integer identifier for the coroutine requesting exit.

#### co_exit_to

    public void co_exit_to(java.lang.Object arg_object,
                  int thisCoroutine,
                  int toCoroutine)
                    throws java.lang.NoSuchMethodException

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.

Parameters:
  `arg_object` - A value to be passed to the other coroutine.
  `thisCoroutine` - Integer identifier for the coroutine leaving the set.
  `toCoroutine` - Integer identifier for the coroutine we wish to invoke.
Throws:
  `java.lang.NoSuchMethodException` - if toCoroutine isn't a registered member of this group. %REVIEW% whether this is the best choice.