com.sun.sgs.nio.channels
Class AsynchronousChannelGroup

java.lang.Object
  com.sun.sgs.nio.channels.AsynchronousChannelGroup

public abstract class AsynchronousChannelGroup
extends Object

An organization of asynchronous channels for the purpose of resource sharing.

An asynchronous channel group encapsulates the mechanics required to handle the completion of I/O operations initiated by asynchronous channels that are bound to the group. A group is created with an ExecutorService to which tasks are submitted to handle I/O events and dispatch to completion handlers that consume the result of asynchronous operations performed on channels in the group.

An asynchronous channel group is created by invoking the open(java.util.concurrent.ExecutorService) method. Channels are bound to a group by specifying the group when the channel is constructed. If a group is not specified then the channel is bound to a default group that is constructed automatically. The executor for the default group is created by invoking the newThreadPool method on a ThreadPoolFactory located as follows:

• If the system property java.nio.channels.DefaultThreadPoolFactory is defined then it is taken to be the fully-qualified name of a concrete thread pool factory class. The class is loaded and instantiated.
• If the system property is not defined, or the process to load and instantiate it fails, then a system-default factory class is instantiated.

Shutdown and Termination

The shutdown() method is used to initiate an orderly shutdown of the group. An orderly shutdown marks the group as shutdown; further attempts to construct a channel that binds to the group will throw ShutdownChannelGroupException. Whether or not a group is shutdown can be tested using the isShutdown() method. Once shutdown, a group terminates when all asynchronous channels that are bound to the group are closed and resources used by the group are released. Once a group is terminated then any actively executing completion handlers run to completion; no attempt is made to stop or interrupt threads that are executing completion handlers. The isTerminated() method is used to test if the group has terminated, and the awaitTermination(long, java.util.concurrent.TimeUnit) method can be used to block until the group has terminated.

The shutdownNow() method can be used to initiate a forceful shutdown of the group. In addition to the actions performed by an orderly shutdown, the shutdownNow method closes all open channels in the group as if by invoking the close method. A group will typically terminate quickly after the shutdownNow method has been invoked.

See Also:

AsynchronousSocketChannel.open(AsynchronousChannelGroup), AsynchronousServerSocketChannel.open(AsynchronousChannelGroup), AsynchronousDatagramChannel.open(ProtocolFamily, AsynchronousChannelGroup)

Method Summary

abstract boolean	awaitTermination(long timeout, TimeUnit unit) Awaits termination of the group.
static Thread.UncaughtExceptionHandler	getDefaultUncaughtExceptionHandler() Returns the uncaught exception handler for the default group.
abstract boolean	isShutdown() Tells whether or not this asynchronous channel group is shutdown.
abstract boolean	isTerminated() Tells whether or not this asynchronous channel group is terminated.
static AsynchronousChannelGroup	open(ExecutorService executor) Creates an asynchronous channel group.
AsynchronousChannelProvider	provider() Returns the provider that created this channel group.
static void	setDefaultUncaughtExceptionHandler(Thread.UncaughtExceptionHandler eh) Set the uncaught exception handler for the default group.
abstract AsynchronousChannelGroup	shutdown() Initiates an orderly shutdown of the group.
abstract AsynchronousChannelGroup	shutdownNow() Shuts down the group and closes all open channels in the group.

Methods inherited from class java.lang.Object

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

Method Detail

provider

public final AsynchronousChannelProvider provider()

Returns the provider that created this channel group.

Returns:

the provider that created this channel group

open

public static AsynchronousChannelGroup open(ExecutorService executor)
                                     throws IOException

Creates an asynchronous channel group.

The new group is created by invoking the openAsynchronousChannelGroup method of the system-wide default AsynchronousChannelProvider object.

The executor parameter is the ExecutorService to which tasks will be submitted to handle I/O events and dispatch completion results for operations initiated on asynchronous channels in the group.

The tasks and the usage of the executor are highly implementation specific. Consequently, care should be taken when configuring the thread pool and it should allow for unbounded queuing. Depending on the implementation, a number of tasks may be required to execute at the same time so as to wait on I/O events from multiple dictinct sources. A thread pool with a single worker, for example, may result in starvation and may be unsuitable for such implementations. It is recommended that the executor be used exclusively for the resulting asynchronous channel group.

Parameters:

executor - the executor service

Returns:

a new asynchronous channel group

Throws:

IOException - if an I/O error occurs

isShutdown

public abstract boolean isShutdown()

Tells whether or not this asynchronous channel group is shutdown.

Returns:

true if this asynchronous channel group is shutdown

isTerminated

public abstract boolean isTerminated()

Tells whether or not this asynchronous channel group is terminated.

Returns:

true if this asynchronous channel group is terminated

shutdown

public abstract AsynchronousChannelGroup shutdown()

Initiates an orderly shutdown of the group.

This method marks the group as shutdown. Further attempts to construct a channel that binds to this group will throw ShutdownChannelGroupException. The group terminates when all asynchronous channels in the group are closed and all resources have been released. This method has no effect if the group is already shutdown.

Returns:

this group

shutdownNow

public abstract AsynchronousChannelGroup shutdownNow()
                                              throws IOException

Shuts down the group and closes all open channels in the group.

In addition to the actions performed by the shutdown() method, this method invokes the close method on all open channels in the group. This method does not attempt to stop actively executing completion handlers.

The group is likely to terminate quickly after invoking this method but there is no guarantee that the group has terminated on completion of this method.

Returns:

this group

Throws:

IOException - if an I/O error occurs

awaitTermination

public abstract boolean awaitTermination(long timeout,
                                         TimeUnit unit)
                                  throws InterruptedException

Awaits termination of the group.

This method blocks until all channels in the group have been closed and all resources associated with the group have been released.

Parameters:

timeout - the maximum time to wait

unit - the time unit of the timeout argument

Returns:

true if the group has terminated; false if the timeout elapsed before termination

Throws:

InterruptedException - if interrupted while waiting

setDefaultUncaughtExceptionHandler

public static void setDefaultUncaughtExceptionHandler(Thread.UncaughtExceptionHandler eh)

Set the uncaught exception handler for the default group.

The uncaught exception handler is invoked when the execution of a CompletionHandler, consuming the result of an operation on a channel bound to the default group, terminates with an uncaught Error or RuntimeException.

[TBD - need to define interaction with normal uncaught exception handling mechanism]

Parameters:

eh - the object to use as the default uncaught exception handler, or null for no default handler

Throws:

SecurityException - [TBD]

getDefaultUncaughtExceptionHandler

public static Thread.UncaughtExceptionHandler getDefaultUncaughtExceptionHandler()

Returns the uncaught exception handler for the default group.

Returns:

the uncaught exception handler for the default group, or null if there is no default handler