com.neeve.link
Interface ILnkSTRRootEndpoint

All Superinterfaces:

ILnkRootEndpoint

public interface ILnkSTRRootEndpoint
extends ILnkRootEndpoint

The Single Threaded Reader Link Root Endpoint interface.

The STR (Single Threaded Reader) root endpoint is a root endpoint that restricts the read machinery of a link tree to be driven by only a single reader thread. It also prescribes mechanisms by which the reader thread is associated with the endpoint's read machinery.

Basically, this interface adds two additional method i.e. the startRead(com.neeve.emx.IEmxDispatcher, int) and the stopRead(int) method. A user uses the former method to kick off the read machinery i.e. the receipt of packets from the remote endpoint that is the peer of the root endpoint. The thread (dispatcher) that will be driving the read operation is specified in the same method. The latter method is used to stop the receipt of packets and to disassociate the reader thread from the endpoint's read machinery.

Threading:

This endpoint restricts the receipt of packets through the endpoint to a single thread. It should be noted by implementers that, for such an endpoint, it is illegal to accept a request to read using multiple threads.

Nested Class Summary

Nested classes/interfaces inherited from interface com.neeve.link.ILnkRootEndpoint

ILnkRootEndpoint.ThreadingModel

Method Summary

void	startRead(IEmxDispatcher dispatcher, int flags) Start the receipt of packets through the link tree.
void	stopRead(int flags) Stop the receipt of packets from the remote endpoint.

Methods inherited from interface com.neeve.link.ILnkRootEndpoint

getThreadingModel, isReadOperational, registerMessageFactory, scheduleRead

Method Detail

startRead

void startRead(IEmxDispatcher dispatcher,
               int flags)
               throws ELnkInvalidStateException,
                      ELnkNotOwnerException,
                      ELnkOpFailedException

Start the receipt of packets through the link tree.

Parameters:

dispatcher - The dispatcher that is to drive the link tree (aka the endpoint's) read machinery. Upon return from this method, the caller will drive this dispatcher that will, in turn, drive the receipt of packets from the remote endpoint. The calling thread must be the owner of the specified dispatcher.

flags - Flags used to qualify the read operation. Currently, there are no flags supported for use here. The user will always specify a value of 0 in this parameter

Throws:

ELnkInvalidStateException - Thrown in case the user is attempting to start a read on a closed endpoint or a ready has already been started on this endpoint.

ELnkNotOwnerException - Thrown in case this method is invoked by a thread that is not the owner of the specified dispatcher.

ELnkOpFailedException - Thrown in case an error was encountered during the starting of the read.

This method should be used to associate a thread (dispatcher) with the endpoints read machinery and to kick off the receipt of packets from the remote endpoint to be dispatched through the link tree of which this endpoint is the root.

Threading:

This method is not safe for concurrent access by multiple threads. Furthermore, the calling thread must be the same as the owner thread of the provided dispatcher.

stopRead

void stopRead(int flags)
              throws ELnkInvalidStateException,
                     ELnkNotOwnerException,
                     ELnkOpFailedException

Stop the receipt of packets from the remote endpoint.

Parameters:

flags - Flags used to qualify the read operation. Currently, there are no flags supported for use here. The user will always specify a value of 0 in this parameter

Throws:

ELnkInvalidStateException - Thrown in case the user is attempting to stop a read on a closed endpoint or an endpoint on which the read has not been previously started.

ELnkNotOwnerException - Thrown in case this method is invoked by a thread that is not the owner of the specified dispatcher.

ELnkOpFailedException - Thrown in case an error was encountered during the stopping of the read.

This method should be used to stop the read on an endpoint. Upon successful return from this method, the read machinery should have been disassociated from the reader thread and no more packets will be dispatched through the root endpoint's link tree.

Threading:

This method is not safe for concurrent access by multiple threads. Furthermore, the calling thread must be the same as the owner thread of the provided dispatcher.