async
Interface ASyncProvider

public interface ASyncProvider

The interface through an ASync instance exports its methods to a service.

Author:

Michael Parker

Method Summary

java.nio.channels.SelectionKey	addChannel(java.nio.channels.SelectableChannel sc, int interest_ops) Registers the provided SelectableChannel object with this provider.
boolean	addEvent(ASyncEvent event) Enqueues the event so that its run method will be invoked at the earliest convenient moment by the thread running the main loop of this ASync instance.
boolean	addEvent(ASyncEvent event, long time_ms) Enqueues the event so that its run method will be invoked at time time_ms by the thread running the main loop of this ASync instance.
boolean	containsChannel(java.nio.channels.SelectableChannel sc) Queries whether the provided SelectableChannel object is registered with this provider.
java.util.List<java.nio.channels.SelectableChannel>	getChannels() Returns a list containing all SelectableChannel objects registered by the service provided for.
	getEvents() Retrieves the heap of events associated with the service provided for.
ASyncService	getService() Returns the ASyncService that this object provides for.
ASyncServiceInspector	getServiceInspector() Returns the ASyncServiceInspector, allowing this service to inspect other services running on the system.
long	getTime() Returns the current time, in milliseconds.
boolean	removeChannel(java.nio.channels.SelectableChannel sc) De-registers the provided SelectableChannel object with this provider.

Method Detail

getService

ASyncService getService()

Returns the ASyncService that this object provides for.

Returns:

the service provided for, or null if this provider is not active and provides for no service

getServiceInspector

ASyncServiceInspector getServiceInspector()

Returns the ASyncServiceInspector, allowing this service to inspect other services running on the system.

Returns:

the service inspector, or null if this provider is not active and provides for no service

getTime

long getTime()

Returns the current time, in milliseconds. This is equivalent to invoking method System.currTimeMillis, but may use a cached copy of the time for performance if possible. Note that this approach may sacrifice accuracy, and that this method should only be invoked by the thread that is running the main loop of the associated ASync instance.

Returns:

approximately the current time, in milliseconds

addEvent

boolean addEvent(ASyncEvent event)

Enqueues the event so that its run method will be invoked at the earliest convenient moment by the thread running the main loop of this ASync instance. Note that the thread executing the main loop may exit before this time, in which case method run is never invoked. This method will only succeed if ASync is currently running.

Parameters:

event - the event to invoke at the earliest convenient moment

Returns:

true if another thread is running the main loop, false otherwise

addEvent

boolean addEvent(ASyncEvent event,
                 long time_ms)

Enqueues the event so that its run method will be invoked at time time_ms by the thread running the main loop of this ASync instance. Note that the thread executing the main loop may exit before time_ms, in which case method run is never invoked. This method will only succeed if ASync is currently running.

Parameters:

event - the event to invoke at the specified time

time_ms - the time at which to run method run of argument event

Returns:

true if another thread is running the main loop, false otherwise

getEvents

 getEvents()

Retrieves the heap of events associated with the service provided for. Through this heap, events can be managed. When the time an event is scheduled to execute passes, it and the current time are passed to method eventHappens of argument service. Note that this method should only be invoked by the thread that is running the main loop of the associated ASync instance.

Returns:

a Heap containing all pending events for the given service

addChannel

java.nio.channels.SelectionKey addChannel(java.nio.channels.SelectableChannel sc,
                                          int interest_ops)

Registers the provided SelectableChannel object with this provider. If the channel is not already registered, a SelectionKey object is returned, through which interest in asynchronous events can be specified. When the appropriate event occurs, method keyReadable, keyWritable, keyConnectable, or keyAcceptable is invoked on argument service. If the channel is already registered with this provider, this method returns null and has no effect. Note that this method should only be invoked by the thread that is running the main loop of the associated ASync instance.

Parameters:

sc - the SelectableChannel object to register

interest_ops - the interest set to initially register sc under

Returns:

the SelectionKey if sc was registered successfully with this provider, or null otherwise

removeChannel

boolean removeChannel(java.nio.channels.SelectableChannel sc)

De-registers the provided SelectableChannel object with this provider. Once this is done, the SelectionKey returned when the channel was originally registered is no longer active, and this method returns true. If the channel is not registered with the provider, this method returns false and has no effect. Note that this method should only be invoked by the thread that is running the main loop of the associated ASync instance.

Parameters:

sc - the SelectableChannel object to de-register

Returns:

true if sc is no longer registered with this provider, false otherwise

containsChannel

boolean containsChannel(java.nio.channels.SelectableChannel sc)

Queries whether the provided SelectableChannel object is registered with this provider. Note that this method should only be invoked by the thread that is running the main loop of the associated ASync instance.

Parameters:

sc - the SelectableChannel object to query as registered

Returns:

true if sc is registered with this provider, false otherwise

getChannels

java.util.List<java.nio.channels.SelectableChannel> getChannels()

Returns a list containing all SelectableChannel objects registered by the service provided for. The list returned is immutable; to add new channels or remove existing ones, the appropriate methods in this ASyncProvider must be used. Note that this method should only be invoked by the thread that is running the main loop of the associated ASync instance.

Returns:

a list containing all channels registered under the given service, or null if the service is not active