A selector may be created by invoking the open
method of
this class, which will use the system's default selector provider A selectable channel's registration with a selector is represented by a
SelectionKey
object. A selector maintains three sets of selection
keys:
The key set contains the keys representing the current
channel registrations of this selector. This set is returned by the
#keys() keys
method. The selected-key set is the set of keys such that each
key's channel was detected to be ready for at least one of the operations
identified in the key's interest set during a prior selection operation.
This set is returned by the #selectedKeys() selectedKeys
method.
The selected-key set is always a subset of the key set. The cancelled-key set is the set of keys that have been
cancelled but whose channels have not yet been deregistered. This set is
not directly accessible. The cancelled-key set is always a subset of the
key set. All three sets are empty in a newly-created selector.
A key is added to a selector's key set as a side effect of registering a
channel via the channel's register
method. Cancelled keys are removed from the key set during
selection operations. The key set itself is not directly modifiable.
A key is added to its selector's cancelled-key set when it is cancelled,
whether by closing its channel or by invoking its cancel
method. Cancelling a key will cause its channel to be deregistered
during the next selection operation, at which time the key will removed from
all of the selector's key sets.
Keys are added to the selected-key set by selection
operations. A key may be removed directly from the selected-key set by
invoking the set's remove
method or by invoking the remove
method
of an iterator During each selection operation, keys may be added to and removed from a
selector's selected-key set and may be removed from its key and
cancelled-key sets. Selection is performed by the #select()
, #select(long)
, and #selectNow()
methods, and involves three steps:
Each key in the cancelled-key set is removed from each key set of
which it is a member, and its channel is deregistered. This step leaves
the cancelled-key set empty. The underlying operating system is queried for an update as to the
readiness of each remaining channel to perform any of the operations
identified by its key's interest set as of the moment that the selection
operation began. For a channel that is ready for at least one such
operation, one of the following two actions is performed: If the channel's key is not already in the selected-key set then
it is added to that set and its ready-operation set is modified to
identify exactly those operations for which the channel is now reported
to be ready. Any readiness information previously recorded in the ready
set is discarded. Otherwise the channel's key is already in the selected-key set,
so its ready-operation set is modified to identify any new operations
for which the channel is reported to be ready. Any readiness
information previously recorded in the ready set is preserved; in other
words, the ready set returned by the underlying system is
bitwise-disjoined into the key's current ready set. If any keys were added to the cancelled-key set while step (2) was
in progress then they are processed as in step (1). Whether or not a selection operation blocks to wait for one or more
channels to become ready, and if so for how long, is the only essential
difference between the three selection methods. Selectors are themselves safe for use by multiple concurrent threads;
their key sets, however, are not.
The selection operations synchronize on the selector itself, on the key
set, and on the selected-key set, in that order. They also synchronize on
the cancelled-key set during steps (1) and (3) above.
Changes made to the interest sets of a selector's keys while a
selection operation is in progress have no effect upon that operation; they
will be seen by the next selection operation.
Keys may be cancelled and channels may be closed at any time. Hence the
presence of a key in one or more of a selector's key sets does not imply
that the key is valid or that its channel is open. Application code should
be careful to synchronize and check these conditions as necessary if there
is any possibility that another thread will cancel a key or close a channel.
A thread blocked in one of the #select()
or #select(long)
methods may be interrupted by some other thread in one of
three ways:
By invoking the selector's wakeup
method,
By invoking the selector's close
method, or
By invoking the blocked thread's java.lang.Thread#interrupt() interrupt
method, in which case its
interrupt status will be set and the selector's wakeup
method will be invoked. The close
method synchronizes on the selector and all
three key sets in the same order as in a selection operation.
A selector's key and selected-key sets are not, in general, safe for use
by multiple concurrent threads. If such a thread might modify one of these
sets directly then access should be controlled by synchronizing on the set
itself. The iterators returned by these sets' java.util.Set#iterator() iterator
methods are fail-fast: If the set
is modified after the iterator is created, in any way except by invoking the
iterator's own java.util.Iterator#remove() remove
method, then a
java.util.ConcurrentModificationException
will be thrown.
to
create a new selector. A selector may also be created by invoking the
openSelector
method of a custom selector provider. A selector remains open until it is
closed via its close
method.
obtained from the
set. Keys are never removed from the selected-key set in any other way;
they are not, in particular, removed as a side effect of selection
operations. Keys may not be added directly to the selected-key set. Selection
Concurrency
If a thread is currently blocked in one of this selector's selection methods then it is interrupted as if by invoking the selector's wakeup method.
Any uncancelled keys still associated with this selector are invalidated, their channels are deregistered, and any other resources associated with this selector are released.
If this selector is already closed then invoking this method has no effect.
After a selector is closed, any further attempt to use it, except by invoking this method or the wakeup method, will cause a ClosedSelectorException to be thrown.
The equals method implements an equivalence relation
on non-null object references:
x, x.equals(x) should return
true.
x and y, x.equals(y)
should return true if and only if
y.equals(x) returns true.
x, y, and z, if
x.equals(y) returns true and
y.equals(z) returns true, then
x.equals(z) should return true.
x and y, multiple invocations of
x.equals(y) consistently return true
or consistently return false, provided no
information used in equals comparisons on the
objects is modified.
x,
x.equals(null) should return false.
The equals method for class Object implements
the most discriminating possible equivalence relation on objects;
that is, for any non-null reference values x and
y, this method returns true if and only
if x and y refer to the same object
(x == y has the value true).
Note that it is generally necessary to override the hashCode method whenever this method is overridden, so as to maintain the general contract for the hashCode method, which states that equal objects must have equal hash codes.
java.util.Hashtable.
The general contract of hashCode is:
hashCode method on each of
the two objects must produce the same integer result.
As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the JavaTM programming language.)
The key set is not directly modifiable. A key is removed only after it has been cancelled and its channel has been deregistered. Any attempt to modify the key set will cause an UnsupportedOperationException to be thrown.
The key set is not thread-safe.
wait methods.
The awakened thread will not be able to proceed until the current thread relinquishes the lock on this object. The awakened thread will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened thread enjoys no reliable privilege or disadvantage in being the next thread to lock this object.
This method should only be called by a thread that is the owner of this object's monitor. A thread becomes the owner of the object's monitor in one of three ways:
synchronized statement
that synchronizes on the object.
Class, by executing a
synchronized static method of that class.
Only one thread at a time can own an object's monitor.
wait methods.
The awakened threads will not be able to proceed until the current thread relinquishes the lock on this object. The awakened threads will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened threads enjoy no reliable privilege or disadvantage in being the next thread to lock this object.
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.
The new selector is created by invoking the openSelector method of the system-wide default java.nio.channels.spi.SelectorProvider object.
This method performs a blocking selection operation. It returns only after at least one channel is selected, this selector's wakeup method is invoked, or the current thread is interrupted, whichever comes first.
This method performs a blocking selection operation. It returns only after at least one channel is selected, this selector's wakeup method is invoked, the current thread is interrupted, or the given timeout period expires, whichever comes first.
This method does not offer real-time guarantees: It schedules the timeout as if by invoking the method.
Keys may be removed from, but not directly added to, the selected-key set. Any attempt to add an object to the key set will cause an UnsupportedOperationException to be thrown.
The selected-key set is not thread-safe.
This method performs a non-blocking selection operation. If no channels have become selectable since the previous selection operation then this method immediately returns zero.
Invoking this method clears the effect of any previous invocations of the wakeup method.
toString method returns a string that
"textually represents" this object. The result should
be a concise but informative representation that is easy for a
person to read.
It is recommended that all subclasses override this method.
The toString method for class Object
returns a string consisting of the name of the class of which the
object is an instance, the at-sign character `@', and
the unsigned hexadecimal representation of the hash code of the
object. In other words, this method returns a string equal to the
value of:
getClass().getName() + '@' + Integer.toHexString(hashCode())
The current thread must own this object's monitor. The thread
releases ownership of this monitor and waits until another thread
notifies threads waiting on this object's monitor to wake up
either through a call to the notify method or the
notifyAll method. The thread then waits until it can
re-obtain ownership of the monitor and resumes execution.
As in the one argument version, interrupts and spurious wakeups are possible, and this method should always be used in a loop:
synchronized (obj) {
while (<condition does not hold>)
obj.wait();
... // Perform action appropriate to condition
}
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.The current thread must own this object's monitor.
This method causes the current thread (call it T) to place itself in the wait set for this object and then to relinquish any and all synchronization claims on this object. Thread T becomes disabled for thread scheduling purposes and lies dormant until one of four things happens:
A thread can also wake up without being notified, interrupted, or timing out, a so-called spurious wakeup. While this will rarely occur in practice, applications must guard against it by testing for the condition that should have caused the thread to be awakened, and continuing to wait if the condition is not satisfied. In other words, waits should always occur in loops, like this one:
synchronized (obj) {
while (<condition does not hold>)
obj.wait(timeout);
... // Perform action appropriate to condition
}
(For more information on this topic, see Section 3.2.3 in Doug Lea's
"Concurrent Programming in Java (Second Edition)" (Addison-Wesley,
2000), or Item 50 in Joshua Bloch's "Effective Java Programming
Language Guide" (Addison-Wesley, 2001).
If the current thread is interrupted by another thread while it is waiting, then an InterruptedException is thrown. This exception is not thrown until the lock status of this object has been restored as described above.
Note that the wait method, as it places the current thread into the wait set for this object, unlocks only this object; any other objects on which the current thread may be synchronized remain locked while the thread waits.
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.
This method is similar to the wait method of one
argument, but it allows finer control over the amount of time to
wait for a notification before giving up. The amount of real time,
measured in nanoseconds, is given by:
1000000*timeout+nanos
In all other respects, this method does the same thing as the method of one argument. In particular, wait(0, 0) means the same thing as wait(0).
The current thread must own this object's monitor. The thread releases ownership of this monitor and waits until either of the following two conditions has occurred:
notify method
or the notifyAll method.
timeout
milliseconds plus nanos nanoseconds arguments, has
elapsed.
The thread then waits until it can re-obtain ownership of the monitor and resumes execution.
As in the one argument version, interrupts and spurious wakeups are possible, and this method should always be used in a loop:
synchronized (obj) {
while (<condition does not hold>)
obj.wait(timeout, nanos);
... // Perform action appropriate to condition
}
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.If another thread is currently blocked in an invocation of the or methods then that invocation will return immediately. If no selection operation is currently in progress then the next invocation of one of these methods will return immediately unless the method is invoked in the meantime. In any case the value returned by that invocation may be non-zero. Subsequent invocations of the or methods will block as usual unless this method is invoked again in the meantime.
Invoking this method more than once between two successive selection operations has the same effect as invoking it just once.