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.
LinkChannel
s 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 Link
s and LinkChannel
s 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
LinkChannel
s 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 . |
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 sendreceiver
- 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 eventsreceiver
- 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