public interface ClientThreadingStrategy
Threading strategy for a ChannelAccessClient
. The threading strategy
defines how threads are created and whether components share the same thread
or have individual threads. It also chooses how listeners that are registered
by the user are notified (in the calling thread or by a separate notification
thread).
When the client creates a component, it registers it with the threading strategy. The threading strategy can then decide which thread will process the I/O for this component. For example, it can create a new thread, or it can add the component to an existing thread.
Components are passed in the form of CommunicationProcessor
s. The
threading strategy then calls the communication processor's
CommunicationProcessor.setCommunicationController(CommunicationController)
method, so that the component can register its channels and tasks that have
to be executed at a certain point in time. The
CommunicationController
passed to the communication processor
typically is a wrapper around the Selector
and timer queue for the
respective thread.
When the treading strategy detects that a channel registered by a
communication processor has become ready, it calls the processor's
processIO()
method. If a timer
registered by the processor has expired, it calls the processor's
TimerProcessor.processTimer()
method. A threading strategy has to
assume that a communication processor is not thread safe and thus has to call
both methods from the same thread or ensure through other means that only one
thread at a time calls one of the communication processor's methods. The only
exception to this rule is the
setCommunicationController(CommunicationController)
method so that the
threading strategy does not have to wait for the processor to return from
this method before it may call one of the other methods.
A threading strategy can choose how listeners that have been registered by the user are notified: Typically, they will be called right in the thread triggering the notification. However, a threading strategy might alternatively choose to use a separate thread (or a pool of threads) for such notifications so that a listener that blocks does not block the whole thread that triggered the notification. Typically, listeners should be designed to operate without blocking, but there might be applications where this property cannot be guaranteed.
When a client is destroyed, it calls the threading strategy's
destroy()
method, so that the threading strategy can destroy all
threads. The threading strategy does not have to destroy the individual
communication processors as this will be done by the client.
Implementations of this interface must be safe for concurrent use by multiple threads.
Modifier and Type | Method and Description |
---|---|
void |
addServerConnection(InetSocketAddress serverAddress,
CommunicationProcessor communicationProcessor)
Registers a communication processor that handles a connection with a
specific server.
|
void |
destroy()
Destroys the threading strategy.
|
void |
notifyConnectionListener(ChannelAccessChannel channel,
ChannelAccessConnectionListener listener,
boolean nowConnected)
Submits a notification request for a connection listener.
|
<T> void |
notifyFutureCompletionListener(ListenableFuture<T> future,
FutureCompletionListener<? super T> listener)
Submits a notification request for a future completion listener.
|
<T extends ChannelAccessGettableValue<?>> |
notifyMonitorListenerError(ChannelAccessMonitor<? extends T> monitor,
ChannelAccessMonitorListener<? super T> listener,
ChannelAccessStatus status,
String message)
Submits an error notification request for a monitor listener.
|
<T extends ChannelAccessGettableValue<?>> |
notifyMonitorListenerEvent(ChannelAccessMonitor<? extends T> monitor,
ChannelAccessMonitorListener<? super T> listener,
T value)
Submits an event notification request for a monitor listener.
|
void |
removeServerConnection(InetSocketAddress serverAddress,
CommunicationProcessor communicationProcessor)
Unregisters a communication processor that handles a connection with a
specific server.
|
void |
setBeaconDetector(CommunicationProcessor communicationProcessor)
Sets the communication processor for the
BeaconDetector . |
void |
setChannelNameResolver(CommunicationProcessor communicationProcessor)
Sets the communication processor used for the
ChannelNameResolver
. |
void addServerConnection(InetSocketAddress serverAddress, CommunicationProcessor communicationProcessor)
serverAddress
- IP address and port of the server. A threading strategy might
use this information to decide which thread should be used.communicationProcessor
- communication processor handling the connection with the
specified server.void removeServerConnection(InetSocketAddress serverAddress, CommunicationProcessor communicationProcessor)
serverAddress
- IP address and port of the server. A threading strategy might
use this information to decide which thread is used by the
communication processor.communicationProcessor
- communication processor handling the connection with the
specified server.void notifyConnectionListener(ChannelAccessChannel channel, ChannelAccessConnectionListener listener, boolean nowConnected)
Submits a notification request for a connection listener.
An implementation may choose to notify the listener in the calling thread
(before returning) or it may choose to queue the notification request for
processing by a different thread. In any case, each call of this method
must result in exactly one corresponding call of
listener.connectionStateChanged(channel, nowConnected)
.
When an implementation chooses to notify the listener asynchronously, it
still has to ensure that the listener receives notifications in the
correct order. This means that for every call of this method using the
same channel
-listener
pair, the calls of
listener.connectionStateChanged(...)
must be made in the
same order in which this method was called. Calls specifying different
listeners or channels may be reordered arbitrarily.
For deciding whether a channel is the same channel as specified in another request and whether a listener is the same listener as specified in another request, object identity should be used instead of object equality. used.
channel
- channel that is the source of the event.listener
- listener that shall be notified.nowConnected
- new connection state of which the listener shall be notified.RuntimeException
- if the listener
is notified synchronously and
throws such an exception.<T extends ChannelAccessGettableValue<?>> void notifyMonitorListenerError(ChannelAccessMonitor<? extends T> monitor, ChannelAccessMonitorListener<? super T> listener, ChannelAccessStatus status, String message)
Submits an error notification request for a monitor listener.
An implementation may choose to notify the listener in the calling thread
(before returning) or it may choose to queue the notification request for
processing by a different thread. In any case, each call of this method
must result in exactly one corresponding call of
listener.monitorError(monitor, status, message)
.
When an implementation chooses to notify the listener asynchronously, it
still has to ensure that the listener receives notifications in the
correct order. This means that for every call of this method using the
same monitor
-listener
pair, the calls of
listener.monitorError(...)
must be made in the same order in
which this method was called. Calls specifying different listeners or
monitors may be reordered arbitrarily.
For deciding whether a monitor is the same monitor as specified in another request and whether a listener is the same listener as specified in another request, object identity should be used instead of object equality. used.
T
- value type of the monitor and listener.monitor
- monitor that is the source of the event.listener
- listener that shall be notified.status
- status code that is associated with the event.message
- message that is associated with the event (may be
null
).RuntimeException
- if the listener
is notified synchronously and
throws such an exception.<T extends ChannelAccessGettableValue<?>> void notifyMonitorListenerEvent(ChannelAccessMonitor<? extends T> monitor, ChannelAccessMonitorListener<? super T> listener, T value)
Submits an event notification request for a monitor listener.
An implementation may choose to notify the listener in the calling thread
(before returning) or it may choose to queue the notification request for
processing by a different thread. In any case, each call of this method
must result in exactly one corresponding call of
listener.monitorEvent(monitor, value)
.
When an implementation chooses to notify the listener asynchronously, it
still has to ensure that the listener receives notifications in the
correct order. This means that for every call of this method using the
same monitor
-listener
pair, the calls of
listener.monitorValue(...)
must be made in the same order in
which this method was called. Calls specifying different listeners or
monitors may be reordered arbitrarily.
For deciding whether a monitor is the same monitor as specified in another request and whether a listener is the same listener as specified in another request, object identity should be used instead of object equality. used.
T
- value type of the monitor and listener. This the type of value
which is passed as the event value.monitor
- monitor that is the source of the event.listener
- listener that shall be notified.value
- event value. Typically, this is a value update for the
monitor's channel.RuntimeException
- if the listener
is notified synchronously and
throws such an exception.<T> void notifyFutureCompletionListener(ListenableFuture<T> future, FutureCompletionListener<? super T> listener)
Submits a notification request for a future completion listener.
An implementation may choose to notify the listener in the calling thread
(before returning) or it may choose to queue the notification request for
processing by a different thread. In any case, each call of this method
must result in exactly one corresponding call of
listener.completed(future)
.
An implementation may choose to reorder notification requests arbitrarily.
T
- type of the future's value.future
- future that completed and is the source of the event.listener
- listener that shall be notified.void setBeaconDetector(CommunicationProcessor communicationProcessor)
BeaconDetector
. As there
is only one beacon detector for each client, the threading strategy does
not have to maintain a list, but can simply assume that this method is
only called once.communicationProcessor
- communication processor used by the beacon detector.void setChannelNameResolver(CommunicationProcessor communicationProcessor)
ChannelNameResolver
. As there is only one channel name resolver for each client, the
threading strategy does not have to maintain a list, but can simply
assume that this method is only called once.communicationProcessor
- communication processor used by the channel name resolver.void destroy()
Copyright © 2014–2017 aquenos GmbH. All rights reserved.