java.nio.channels
Class LinkChannel

java.lang.Object
  |
  +--java.nio.channels.spi.AbstractChannel
        |
        +--java.nio.channels.SelectableChannel
              |
              +--java.nio.channels.spi.AbstractSelectableChannel
                    |
                    +--java.nio.channels.LinkChannel
All Implemented Interfaces:
Channel

public abstract class LinkChannel
extends AbstractSelectableChannel

A selectable channel for a Link.

NOTICE: This class is not part of the JSR-121 specification but instead represents a proposal for consideration as a future java.nio API.

LinkChannels support applications managing a large number of links in a scalable fashion in conjunction with a Selector. Instances of this class may be obtained either via an invocation of Link.getChannel on an existing Link, or directly via an invocation of the openLinkChannel or openEventLinkChannel static factory methods. In both cases Links and LinkChannels are uniquely associated, and the following assertions will be satisfied,

   assert link.getChannel().getLink() == link;
   assert linkChannel.getLink().getChannel() == linkChannel;
 

Other than the support for non-blocking behavior provided by send and receive the effects of LinkChannel methods are indistinguishable from those of the corresponding Link methods.

When used with a Selector applications may register LinkChannels for SelectionKey.OP_WRITE and SelectionKey.OP_READ events. On the sender side of the link the OP_WRITE event interest should be registered, and when the event occurs it indicates either that a subsequent invocation of send will probably succeed or that the link has been closed. On the receiver side of the link the OP_READ event interest should be registered, and when the event occurs indicates either that a subsequent invocation of receive will probably succeed or that the link has been closed. Note that in all cases the occurrence of the event is a hint rather than a guarantee, hence that it should not be assumed that a send or receive will return non-null when in non-blocking mode, or will not block when in blocking mode.

Applications which wish to distinguish between an OP_READ (resp. OP_WRITE) indicating the likelihood of a successful receive (resp. send) rather than link closure may test the LinkChannel status via isOpen.

As with Link, the send and receive methods on a LinkChannel require a strict rendezvous between sender and receiver. Consequently only one side (sender or receiver) of a LinkChannel should be put in non-blocking mode, otherwise neither side will block, and rendezvous will not occur. Additionally, while a LinkChannel instance is configured for non-blocking transfers the associated Link should not be used for transfers: invocations of its send and receive methods will throw IllegalBlockingModeException.

The following example assumes that links are established to isolates to report their "status" (i.e., for each job completed, a report is sent). The run() method will execute as long as the Selector is open, waiting for available reports and processing them as necessary.

 public class ReportAggregator {
    private Selector reporters = new Selector.open();
 
    private static class Status { ... };

    public void registerLink(Isolate i, Link l) {
       assert l.isRecevier(Isolate.currentIsolate());
       assert l.isSender(i);
       SelectionKey sk;
       sk = l.getChannel().register(reporters, Selector.OP_READ);
       sk.attach(new Status(i));
    }

    private void handleReadyReporters() throws IOException {
       Iterator i = reporter.selectedKeys().iterator();
       while (i.hasNext()) {
          SelectionKey key = (SelectionKey)(i.next());
          Status status = (Status)(key.attachment());
          IsolateMessage lm = ((LinkChannel)(key.channel())).receive();
          if (lm != null)
             status.addReport(lm);
          i.remove();
       }
    }

    public void run() throws IOException {
       while (reporters.isOpen()) {
          try {
             reporters.select();
             handleReadyReporters();
          } 
          catch (ClosedSelectorException cse) { ; }
       }
    }
 }
 

See Also:
Link

Method Summary
abstract  boolean isReceiver(java.lang.isolate.Isolate i)
          Returns true if the given Isolate is structurally allowed to receive on this LinkChannel.
abstract  boolean isSender(java.lang.isolate.Isolate i)
          Returns true if the given Isolate is structurally allowed to send on this LinkChannel.
 java.lang.isolate.Link link()
          Returns the unique Link associated with this LinkChannel.
static LinkChannel openEventLinkChannel(java.lang.isolate.Isolate sender, java.lang.isolate.Isolate receiver)
          Create a new event link associated with the given Isolate, from which the given receiver Isolate can receive events.
static LinkChannel openLinkChannel(java.lang.isolate.Isolate sender, java.lang.isolate.Isolate receiver)
          Creates a new application link between the given pair of Isolate instances.
abstract  java.lang.isolate.IsolateMessage receive()
          Receives a message from this link.
abstract  boolean send(java.lang.isolate.IsolateMessage message)
          Sends the given message on this link.
 int validOps()
          Returns an "operation set" (see SelectionKey) identifying the operations supported on this LinkChannel.
 
Methods inherited from class java.nio.channels.spi.AbstractSelectableChannel
blockingLock, configureBlocking, isBlocking, isRegistered, keyFor, provider, register
 
Methods inherited from class java.nio.channels.SelectableChannel
register
 
Methods inherited from class java.nio.channels.spi.AbstractChannel
close, isOpen
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface java.nio.channels.Channel
close, isOpen
 

Method Detail

openLinkChannel

public static LinkChannel openLinkChannel(java.lang.isolate.Isolate sender,
                                          java.lang.isolate.Isolate receiver)
                                   throws ClosedLinkException
Creates a new application link between the given pair of Isolate instances.

Like Link.newLink.

Parameters:
sender - The isolate that will send
receiver - The isolate that will receive
Returns:
A new LinkChannel instance
Throws:
NullPointerException - See Link.newLink
IsolateResourceError - See Link.newLink
ClosedLinkException - See Link.newLink

openEventLinkChannel

public static LinkChannel openEventLinkChannel(java.lang.isolate.Isolate sender,
                                               java.lang.isolate.Isolate receiver)
                                        throws ClosedLinkException
Create a new event link associated with the given Isolate, from which the given receiver Isolate can receive events.

Like Link.newEventLink.

Parameters:
sender - The isolate that will send events
receiver - The isolate that will receive events
Returns:
a new LinkChannel associated with the sender isolate
Throws:
NullPointerException - See Link.newEventLink
IsolateResourceError - See Link.newEventLink
ClosedLinkException - See Link.newEventLink

validOps

public int validOps()
Returns an "operation set" (see SelectionKey) identifying the operations supported on this LinkChannel.

Returns (SelectionKey.OP_READ | SelectionKey.OP_WRITE)

Specified by:
validOps in class SelectableChannel
Returns:
valid Channel-related ops for this LinkChannel

isSender

public abstract boolean isSender(java.lang.isolate.Isolate i)
Returns true if the given Isolate is structurally allowed to send on this LinkChannel.

Like Link.isSender.

Parameters:
i - The isolate to test to see if it can send on this LinkChannel
Returns:
true if the given isolate can structurally send on this LinkChannel
Throws:
NullPointerException - See Link.isSender

isReceiver

public abstract boolean isReceiver(java.lang.isolate.Isolate i)
Returns true if the given Isolate is structurally allowed to receive on this LinkChannel.

Like Link.isReceiver.

Parameters:
i - The isolate to test to see if it can receive on this LinkChannel
Returns:
true if the given isolate can potentially receive on this LinkChannel
Throws:
NullPointerException - See Link.isReceiver

link

public java.lang.isolate.Link link()
Returns the unique Link associated with this LinkChannel.

Returns:
the associated Link

send

public abstract boolean send(java.lang.isolate.IsolateMessage message)
                      throws IOException
Sends the given message on this link.

Like Link.send except that this method returns a boolean which indicates if the send succeeded (true) or if there was no waiting receiver thread (false). False can only be returned if this LinkChannel has been configured non-blocking and there is no receiver available; otherwise, the invoking thread will block until a receiver is available.

Parameters:
message - the message to send
Returns:
true if the send succeeded, false if there was no waiting receiver
Throws:
NullPointerException - See Link.send
ClosedLinkException - See Link.send
AsynchronousCloseException - See Link.send
ClosedByInterruptException - See Link.send
IsolateResourceError - See Link.send
LinkSerializationException - See Link.send
UnsupportedOperationException - See Link.send
SecurityException - See Link.send
IOException

receive

public abstract java.lang.isolate.IsolateMessage receive()
                                                  throws IOException
Receives a message from this link.

Like Link.receive except that this method returns null if there was no waiting sender. A null can only be returned if this LinkChannel has been configured non-blocking, and there is no sender available; otherwise, the invoking thread will block until a sender is available.

Returns:
A IsolateMessage containing the message from the sender or null if there was no waiting sender to rendezvous with
Throws:
ClosedLinkException - See Link.receive
AsynchronousCloseException - See Link.receive
ClosedByInterruptException - See Link.receive
IsolateResourceError - See Link.receive
UnsupportedOperationException - See Link.receive
SecurityException - See Link.receive
IOException