pyrasun.eio
Class Endpoint

java.lang.Object
  pyrasun.eio.Endpoint

Direct Known Subclasses:

AcceptingEndpoint, ReadWriteEndpoint

public abstract class Endpoint

extends java.lang.Object

Along with EIOEvent, EndpointCoordinator, and EIOGlobalContext, Endpoint is a core class within EmberIO.

An Endpoint represents an object which can generate EIO I/O events, and typically are also something that you can directly perform some type of I/O operation upon. Conceptually, all of these - a socket, a serversocket, an open file, etc - could be considered Endpoints (but EIO only supports sockets right now). Some people would think of these as a Connection - but Connection doesn't work well when you talk about something like a file or shared memory, now does it?

It's called an Endpoint because this represents only one side of an I/O resource - and presumably there are one or mother processes on the other side.

Endpoints must be constructed with an associated EndpointCoordinator. The coordinator defines the strategy that will be used to propogate events related to this Endpoint to the appropriate workers - and also physically propogates those events.

Note that this sucker is abstract - it's only a conceptual Endpoint. Real physical Endpoints include ReadWriteEndpoint (think: a socket) and AcceptingEndpoint (think: a socket server). Future Endpoints might include a FileEndpoint, a SharedMemory endpoint, and variations on ReadWriteEndpoint like MulticastEndpoint and maybe even PigeonEndpoint.

Endpoints maintain three sets of event indicators:

• Interest Indicators. Events that this Endpoint is interested in handling.
• Ready Indicators. Events that may be ready for processing for this Endpoint.
• Processing Indicators. Events that are being processed right now for this Endpoint

End users of EIO should generally only manipulate the Interest indicators, indicating what sort of I/O events they are interested in. When an Endpoint is ready to handle its interest set, it should be registered with its EndpointCoordinator via the call EndpointCoordinator.registerForEvents (Endpoint).

Even interest indicator maintenance generally does not need to be performed by EIO users - concrete Endpoints generally manage these on behalf of the user. For example, AcceptingEndpoint auto-sets the ACCEPT interest indicator, and ReadWriteEndpoint auto-sets READ events at initialization, and manages WRITE event indicators as appropriate (e.g. when there's actually something written to the Endpoint).

Constructor Summary

Endpoint(EndpointCoordinator coordinator)
Constructs a brand new Endpoint associated with the given EndpointCoordinator.

Method Summary

void	addInterest(EIOEvent event) Show your interest in a new type of event.
void	addProcessing(int what)
void	attach(java.lang.Object obj) EIO steals the NIO attachment, so we give the poor user a break and let them stick one here.
java.lang.Object	attachment() EIO steals the NIO attachment, so we give the poor user a break and let them stick one here.
void	close()
void	close(EIOReasonCode reason)
void	close(EIOReasonCode reason, java.lang.String msg)
void	close(EIOReasonCode reason, java.lang.String msg, java.lang.Throwable t, java.lang.Object context)
void	close(EIOReasonCode reason, java.lang.Throwable t)
void	configureBlocking(boolean doBlocking)
java.lang.String	dumpProcessedStats(java.lang.String prefix)
EIOGlobalContext	getContext() Retrieve the global context this guy is running within
EndpointCoordinator	getCoordinator() Get the coordinator associated with this Endpoint.
int	getInterestEvents() Get the events we're interested in in bitmask form.
abstract java.nio.channels.SelectableChannel	getNIOChannel() Get the NIO channel associated with this endpoint.
int	getNIOInterestEvents() Get _only_ the NIO-selectable events we're interested in in bitmask form.
int	getProcessingEvents() Return the events that are currently being processed against this endpoint, in bitmask form.
int	getReadyEvents() Get the events that have fired as "ready" against this endpoint.
EPStatus	getState() Returns the current state of the Endpoint.
boolean	isAborted(EIOEvent event) HACK HACK HACK
boolean	isBlocking() Returns true if this Endpoint is in blocking mode at the moment.
boolean	isLockedForProcessing(int eventIDs) Returns true if any of the specified event flags are locked for processing, false otherwise
boolean	isLockedReady(int events) Returns true if any of the specified flags are locked as "ready".
boolean	isOpen() Returns true if this endpoint is alive and well, false if it got whacked.
boolean	isReady(EIOEvent event)
boolean	isSelectorized() Returns true if the NIO selector owns this Endpoint's ass.
boolean	lockForEventManager() Tries to atomically switch the endpoint over to a WAITING state for injection into the EventManager.
boolean	lockForProcessing(EIOEvent event) Tries to lock down an event for processing.
boolean	lockForReady(java.nio.channels.SelectionKey readyStates) Attempt to lock a new event or set of events as "ready".
java.lang.String	masksAsString()
void	registerEventListener(EndpointEventListener listener) Register an event listener against this Endpoint.
void	removeInterest(EIOEvent event)
void	removeProcessing(int what)
void	removeReadiness(int event)
void	reportReadError(EIOReasonCode why, java.lang.String msg, java.lang.Throwable t, java.lang.Object context)
void	reportWriteError(EIOReasonCode why, java.lang.String msg, java.lang.Throwable t, java.lang.Object context)
void	setName(java.lang.String name) Set a name for this endpoint which is meaningful to the application - useful for logging and debugging.
void	setReadiness(int events)
void	setReadiness(java.nio.channels.SelectionKey readiKey)
java.lang.String	toString()
void	unlockProcessing(EIOEvent event) Unlocks an event from processing.
void	updateProcessedStats(EIOEvent event, int numOps)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Endpoint

public Endpoint(EndpointCoordinator coordinator)

Constructs a brand new Endpoint associated with the given EndpointCoordinator. The EIOGlobalContext is retrieved from the coordinator (among other things!).

Method Detail

updateProcessedStats

public void updateProcessedStats(EIOEvent event,
                                 int numOps)

dumpProcessedStats

public java.lang.String dumpProcessedStats(java.lang.String prefix)

getContext

public EIOGlobalContext getContext()

Retrieve the global context this guy is running within

attachment

public java.lang.Object attachment()

EIO steals the NIO attachment, so we give the poor user a break and let them stick one here.

attach

public void attach(java.lang.Object obj)

EIO steals the NIO attachment, so we give the poor user a break and let them stick one here.

getCoordinator

public EndpointCoordinator getCoordinator()

Get the coordinator associated with this Endpoint.

getNIOChannel

public abstract java.nio.channels.SelectableChannel getNIOChannel()

Get the NIO channel associated with this endpoint. This method is wicked and evil in a library that purports to be greater than just NIO

configureBlocking

public void configureBlocking(boolean doBlocking)

isBlocking

public boolean isBlocking()

Returns true if this Endpoint is in blocking mode at the moment.

setName

public void setName(java.lang.String name)

Set a name for this endpoint which is meaningful to the application - useful for logging and debugging. This gets combined with an internal name.

addInterest

public void addInterest(EIOEvent event)

Show your interest in a new type of event. You shouldn't need to use this - EIO will do this for you right now. Might need re-thinking when non-NIO events are supported.

removeInterest

public void removeInterest(EIOEvent event)

getInterestEvents

public int getInterestEvents()

Get the events we're interested in in bitmask form.

getNIOInterestEvents

public int getNIOInterestEvents()

Get _only_ the NIO-selectable events we're interested in in bitmask form.

setReadiness

public void setReadiness(java.nio.channels.SelectionKey readiKey)

setReadiness

public void setReadiness(int events)

removeReadiness

public void removeReadiness(int event)

isReady

public boolean isReady(EIOEvent event)

getReadyEvents

public int getReadyEvents()

Get the events that have fired as "ready" against this endpoint. The events are returned in bit mask form.

addProcessing

public void addProcessing(int what)

removeProcessing

public void removeProcessing(int what)

getProcessingEvents

public int getProcessingEvents()

Return the events that are currently being processed against this endpoint, in bitmask form.

lockForReady

public boolean lockForReady(java.nio.channels.SelectionKey readyStates)

Attempt to lock a new event or set of events as "ready". This will be denied if we're already processing the indicated event(s).

lockForProcessing

public boolean lockForProcessing(EIOEvent event)

Tries to lock down an event for processing. If it's not set as ready, or if someone's already processing it, we return false. If we can lock it, we do and return true.

unlockProcessing

public void unlockProcessing(EIOEvent event)

Unlocks an event from processing. When all NIO events are unlocked, we reset the internal state as locked for the event manager, and then reinject the endpoint back into the NIOEventManager

lockForEventManager

public boolean lockForEventManager()

Tries to atomically switch the endpoint over to a WAITING state for injection into the EventManager. If there is any outstanding work on NIO events this attempt will fail. Once we achieve this switch, workers are locked out from doing NIO-related work, and will remain so until we switch back to a non-WAITING state. Returns true if the lock worked, false otherwise.

isLockedForProcessing

public boolean isLockedForProcessing(int eventIDs)

Returns true if any of the specified event flags are locked for processing, false otherwise

isLockedReady

public boolean isLockedReady(int events)

Returns true if any of the specified flags are locked as "ready".

masksAsString

public java.lang.String masksAsString()

registerEventListener

public void registerEventListener(EndpointEventListener listener)

Register an event listener against this Endpoint. NOTE: this may not be what you think it is.

isOpen

public boolean isOpen()

Returns true if this endpoint is alive and well, false if it got whacked.

isSelectorized

public boolean isSelectorized()

Returns true if the NIO selector owns this Endpoint's ass.

getState

public EPStatus getState()

Returns the current state of the Endpoint.

isAborted

public boolean isAborted(EIOEvent event)

HACK HACK HACK

close

public void close()

close

public void close(EIOReasonCode reason)

close

public void close(EIOReasonCode reason,
                  java.lang.Throwable t)

close

public void close(EIOReasonCode reason,
                  java.lang.String msg)

close

public void close(EIOReasonCode reason,
                  java.lang.String msg,
                  java.lang.Throwable t,
                  java.lang.Object context)

reportReadError

public void reportReadError(EIOReasonCode why,
                            java.lang.String msg,
                            java.lang.Throwable t,
                            java.lang.Object context)

reportWriteError

public void reportWriteError(EIOReasonCode why,
                             java.lang.String msg,
                             java.lang.Throwable t,
                             java.lang.Object context)

toString

public java.lang.String toString()