- java.lang.Object
-
- java.nio.channels.AsynchronousChannelGroup
-
public abstract class AsynchronousChannelGroup extends Object
A grouping 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 channelsthat are bound to the group. A group has an associated thread pool to which tasks are submitted to handle I/O events and dispatch tocompletion-handlersthat consume the result of asynchronous operations performed on channels in the group. In addition to handling I/O events, the pooled threads may also execute other tasks required to support the execution of asynchronous I/O operations.An asynchronous channel group is created by invoking the
withFixedThreadPoolorwithCachedThreadPoolmethods defined here. Channels are bound to a group by specifying the group when constructing the channel. The associated thread pool is owned by the group; termination of the group results in the shutdown of the associated thread pool.In addition to groups created explicitly, the Java virtual machine maintains a system-wide default group that is constructed automatically. Asynchronous channels that do not specify a group at construction time are bound to the default group. The default group has an associated thread pool that creates new threads as needed. The default group may be configured by means of system properties defined in the table below. Where the
ThreadFactoryfor the default group is not configured then the pooled threads of the default group aredaemonthreads.System property Description java.nio.channels.DefaultThreadPool.threadFactoryThe value of this property is taken to be the fully-qualified name of a concrete ThreadFactoryclass. The class is loaded using the system class loader and instantiated. The factory'snewThreadmethod is invoked to create each thread for the default group's thread pool. If the process to load and instantiate the value of the property fails then an unspecified error is thrown during the construction of the default group.java.nio.channels.DefaultThreadPool.initialSizeThe value of the initialSizeparameter for the default group (seewithCachedThreadPool). The value of the property is taken to be theStringrepresentation of anIntegerthat is the initial size parameter. If the value cannot be parsed as anIntegerit causes an unspecified error to be thrown during the construction of the default group.Threading
The completion handler for an I/O operation initiated on a channel bound to a group is guaranteed to be invoked by one of the pooled threads in the group. This ensures that the completion handler is run by a thread with the expected identity.
Where an I/O operation completes immediately, and the initiating thread is one of the pooled threads in the group then the completion handler may be invoked directly by the initiating thread. To avoid stack overflow, an implementation may impose a limit as to the number of activations on the thread stack. Some I/O operations may prohibit invoking the completion handler directly by the initiating thread (see
accept).Shutdown and Termination
The
shutdownmethod is used to initiate an orderly shutdown of a group. An orderly shutdown marks the group as shutdown; further attempts to construct a channel that binds to the group will throwShutdownChannelGroupException. Whether or not a group is shutdown can be tested using theisShutdownmethod. Once shutdown, the group terminates when all asynchronous channels that are bound to the group are closed, all actively executing completion handlers have run to completion, and resources used by the group are released. No attempt is made to stop or interrupt threads that are executing completion handlers. TheisTerminatedmethod is used to test if the group has terminated, and theawaitTerminationmethod can be used to block until the group has terminated.The
shutdownNowmethod can be used to initiate a forceful shutdown of the group. In addition to the actions performed by an orderly shutdown, theshutdownNowmethod closes all open channels in the group as if by invoking theclosemethod.
-
-
Constructor Summary
Constructors Modifier Constructor Description protectedAsynchronousChannelGroup(AsynchronousChannelProvider provider)Initialize a new instance of this class.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description abstract booleanawaitTermination(long timeout, TimeUnit unit)Awaits termination of the group.abstract booleanisShutdown()Tells whether or not this asynchronous channel group is shutdown.abstract booleanisTerminated()Tells whether or not this group has terminated.AsynchronousChannelProviderprovider()Returns the provider that created this channel group.abstract voidshutdown()Initiates an orderly shutdown of the group.abstract voidshutdownNow()Shuts down the group and closes all open channels in the group.static AsynchronousChannelGroupwithCachedThreadPool(ExecutorService executor, int initialSize)Creates an asynchronous channel group with a given thread pool that creates new threads as needed.static AsynchronousChannelGroupwithFixedThreadPool(int nThreads, ThreadFactory threadFactory)Creates an asynchronous channel group with a fixed thread pool.static AsynchronousChannelGroupwithThreadPool(ExecutorService executor)Creates an asynchronous channel group with a given thread pool.
-
-
-
Constructor Detail
-
AsynchronousChannelGroup
protected AsynchronousChannelGroup(AsynchronousChannelProvider provider)
Initialize a new instance of this class.- Parameters:
provider- The asynchronous channel provider for this group
-
-
Method Detail
-
provider
public final AsynchronousChannelProvider provider()
Returns the provider that created this channel group.- Returns:
- The provider that created this channel group
-
withFixedThreadPool
public static AsynchronousChannelGroup withFixedThreadPool(int nThreads, ThreadFactory threadFactory) throws IOException
Creates an asynchronous channel group with a fixed thread pool.The resulting asynchronous channel group reuses a fixed number of threads. At any point, at most
nThreadsthreads will be active processing tasks that are submitted to handle I/O events and dispatch completion results for operations initiated on asynchronous channels in the group.The group is created by invoking the
openAsynchronousChannelGroup(int,ThreadFactory)method of the system-wide defaultAsynchronousChannelProviderobject.- Parameters:
nThreads- The number of threads in the poolthreadFactory- The factory to use when creating new threads- Returns:
- A new asynchronous channel group
- Throws:
IllegalArgumentException- IfnThreads <= 0IOException- If an I/O error occurs
-
withCachedThreadPool
public static AsynchronousChannelGroup withCachedThreadPool(ExecutorService executor, int initialSize) throws IOException
Creates an asynchronous channel group with a given thread pool that creates new threads as needed.The
executorparameter is anExecutorServicethat creates new threads as needed to execute tasks that are submitted to handle I/O events and dispatch completion results for operations initiated on asynchronous channels in the group. It may reuse previously constructed threads when they are available.The
initialSizeparameter may be used by the implementation as a hint as to the initial number of tasks it may submit. For example, it may be used to indicate the initial number of threads that wait on I/O events.The executor is intended to be used exclusively by the resulting asynchronous channel group. Termination of the group results in the orderly
shutdownof the executor service. Shutting down the executor service by other means results in unspecified behavior.The group is created by invoking the
openAsynchronousChannelGroup(ExecutorService,int)method of the system-wide defaultAsynchronousChannelProviderobject.- Parameters:
executor- The thread pool for the resulting groupinitialSize- A value>=0or a negative value for implementation specific default- Returns:
- A new asynchronous channel group
- Throws:
IOException- If an I/O error occurs- See Also:
Executors.newCachedThreadPool()
-
withThreadPool
public static AsynchronousChannelGroup withThreadPool(ExecutorService executor) throws IOException
Creates an asynchronous channel group with a given thread pool.The
executorparameter is anExecutorServicethat executes tasks submitted to dispatch completion results for operations initiated on asynchronous channels in the group.Care should be taken when configuring the executor service. It should support direct handoff or unbounded queuing of submitted tasks, and the thread that invokes the
executemethod should never invoke the task directly. An implementation may mandate additional constraints.The executor is intended to be used exclusively by the resulting asynchronous channel group. Termination of the group results in the orderly
shutdownof the executor service. Shutting down the executor service by other means results in unspecified behavior.The group is created by invoking the
openAsynchronousChannelGroup(ExecutorService,int)method of the system-wide defaultAsynchronousChannelProviderobject with aninitialSizeof0.- Parameters:
executor- The thread pool for the resulting group- 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:
trueif this asynchronous channel group is shutdown or has been marked for shutdown.
-
isTerminated
public abstract boolean isTerminated()
Tells whether or not this group has terminated.Where this method returns
true, then the associated thread pool has alsoterminated.- Returns:
trueif this group has terminated
-
shutdown
public abstract void shutdown()
Initiates an orderly shutdown of the group.This method marks the group as shutdown. Further attempts to construct channel that binds to this group will throw
ShutdownChannelGroupException. The group terminates when all asynchronous channels in the group are closed, all actively executing completion handlers have run to completion, and all resources have been released. This method has no effect if the group is already shutdown.
-
shutdownNow
public abstract void shutdownNow() throws IOExceptionShuts down the group and closes all open channels in the group.In addition to the actions performed by the
shutdownmethod, this method invokes theclosemethod on all open channels in the group. This method does not attempt to stop or interrupt threads that are executing completion handlers. The group terminates when all actively executing completion handlers have run to completion and all resources have been released. This method may be invoked at any time. If some other thread has already invoked it, then another invocation will block until the first invocation is complete, after which it will return without effect.- Throws:
IOException- If an I/O error occurs
-
awaitTermination
public abstract boolean awaitTermination(long timeout, TimeUnit unit) throws InterruptedExceptionAwaits termination of the group.This method blocks until the group has terminated, or the timeout occurs, or the current thread is interrupted, whichever happens first.
- Parameters:
timeout- The maximum time to wait, or zero or less to not waitunit- The time unit of the timeout argument- Returns:
trueif the group has terminated;falseif the timeout elapsed before termination- Throws:
InterruptedException- If interrupted while waiting
-
-