public final class EClient extends java.lang.ref.WeakReference<EObject> implements java.lang.Comparable<EClient>
EClient
ties together eBus message routing and message
processing. eBus views an application instance in three ways:
1) an implementation of one or more eBus interfaces
(publisher, subscriber, requester, or replier), 2) the owner
of open feeds and 3) the target of callback
tasks
. EClient
stores the instance's
open feeds and un-executed callback tasks.
eBus has a client-oriented execution mode rather than
task-oriented. When the client's task list is not empty, the
EClient
instance is placed on a run queue where it
appears only once. RQThread
threads remove
clients from this run queue and execute the client's tasks.
The Dispatcher
continues executing the client's
tasks until the client task queue or run quantum is exhausted.
When the nanosecond run quantum reaches zero, the client is
appended to the run queue if it has pending tasks.
The run quantum reset to the configurable initial quantum
value when a dispatcher thread acquires the client. Note: when
the run quantum expires, eBus cannot preempt the client. It is
possible for the client to run indefinitely, taking over the
Dispatcher
thread.
EClient
maintains a weak reference to the application
instance. When eBus detects that the application instance is
finalized, all feeds left open by the instance are closed. If
the application instance is a replier, then all active
requests will receive an error reply. The client's un-executed
tasks are cleared.
EClient
maintains one or more RQThread
groups where each group has a separate run queue. Each client
is assigned to an executor group based on the encapsulated
application class. If the application class is not assigned to
a particular executor group, then the class is assigned to the
default executor group. The executor groups are defined via
configuration
. If no executors are defined,
then there is one Dispatcher
thread for each
core
using a single,
blocking run queue. Executors block until there is an runnable
EClient
posted to group run queue. As stated
previously, an EClient
is assigned to only one client
dispatcher thread at a time. This makes an EClient
instance effectively single-threaded if that client
is accessed only by dispatcher threads. While a client may be
accessed by different dispatcher threads over time, it will be
accessed by only one at any given moment in time.
Each EClient
is assigned a integer identifier which is
guaranteed unique for the client lifespan. When the client
is disposed, the client identifier is re-used and may be
assigned to a new, future eBus client instance. An
EClient
is disposed when the encapsulated application
instance is finalized.
The reason for EClient
is because eBus requires
application objects to implement
interfaces in order
to interface with eBus, not extend
an
eBus abstract class. This class provides the functionality
that an abstract client class would provide.
EFeed
,
ESubject
Modifier and Type | Class and Description |
---|---|
static class |
EClient.ClientLocation
An eBus client is either local to this JVM or in a remote
JVM.
|
static class |
EClient.ObjectState
An eBus object is either on a run queue thread or off.
|
static class |
EClient.RQStats
Contains the
EClient.RQThread current condition. |
static class |
EClient.RQThread
A Dispatcher run queue thread watches a given
run queue
for EClient instances ready to run, attempting to
acquire the next ready client. |
static class |
EClient.RunState
Defines the eBus client run states.
|
Modifier and Type | Method and Description |
---|---|
int |
clientId()
Returns the unique eBus client identifier.
|
int |
compareTo(EClient client)
Returns an integer value <, equal to, or > zero
based on whether
this EClient instance's
identifier is <, equal to, or > client 's
identifier. |
static void |
dispatch(java.lang.Runnable task,
EObject client)
Posts
task to client 's task queue (this is
the same task queue used for eBus message delivery). |
static EConfigure |
eBusConfig()
Returns the auto-loaded eBus configuration.
|
boolean |
equals(java.lang.Object o)
Returns
true if o is a
non-null EClient instance with the same client
identifier as this instance; otherwise, returns
false . |
static EClient |
findClient(EObject client)
Returns the eBus proxy for the given application object.
|
static EClient |
findOrCreateClient(EObject client,
EClient.ClientLocation location)
Returns the eBus proxy for the given eBus client instance.
|
static java.util.List<EClient> |
getClients()
Returns the set of all currently registered eBus clients.
|
int |
hashCode()
Returns the unique client identifier as the hash code.
|
EClient.ClientLocation |
location()
Returns the client location.
|
long |
maximumQuantum()
Returns maximum allowed time a client is allowed to
process messages.
|
long |
readyTimestamp()
Returns timestamp when eBus object entered ready state.
|
static java.util.List<EClient.RQThread> |
runQueueThreads()
Returns immutable list of run queue threads.
|
EClient.RunState |
runState()
Returns eBus object current run state.
|
static java.util.List<EBusObjectInfo> |
runTimeStats()
Returns run time statistics immutable list for extant eBus
objects.
|
EObject |
target()
Returns the target eBus object.
|
java.lang.String |
targetName()
Returns target eBus object name.
|
void |
threadDenial(AlarmCondition condition)
Sets eBus object's current thread denial condition.
|
java.lang.String |
toString() |
public int compareTo(EClient client)
this EClient
instance's
identifier is <, equal to, or > client
's
identifier.compareTo
in interface java.lang.Comparable<EClient>
client
- comparison object.public boolean equals(java.lang.Object o)
true
if o
is a
non-null EClient
instance with the same client
identifier as this
instance; otherwise, returns
false
.equals
in class java.lang.Object
o
- comparison object.true
if the client identifiers are equal.public int hashCode()
hashCode
in class java.lang.Object
public java.lang.String toString()
toString
in class java.lang.Object
@Nullable public EObject target()
null
if
the eBus object is finalized.public java.lang.String targetName()
public int clientId()
public EClient.ClientLocation location()
public long maximumQuantum()
public EClient.RunState runState()
public long readyTimestamp()
public static EConfigure eBusConfig()
null
if no eBus configuration was automatically
loaded.public static java.util.List<EBusObjectInfo> runTimeStats()
The following is an example output of the returned list:
ConnectionPublisher (id 0)
min run time: 1,364 nanos
max run time: 32,743,678 nanos
total run time: 34,189,949 nanos
run count: 4
avg run time: 8,547,487 nanos
dispatcher: general
max quantum: 100,000 nanos
quantum overruns: 3
MulticastConnectionPublisher (id 1)
min run time: 613 nanos
max run time: 751,792 nanos
total run time: 763,513 nanos
run count: 3
avg run time: 254,504 nanos
dispatcher: general
max quantum: 100,000 nanos
quantum overruns: 1
PingPong Main (id 2)
min run time: 10,541 nanos
max run time: 3,700,790 nanos
total run time: 3,711,331 nanos
run count: 2
avg run time: 1,855,665 nanos
dispatcher: general
max quantum: 100,000 nanos
quantum overruns: 1
Ping! Pong! Timer (id 3)
min run time: 1,260 nanos
max run time: 9,877,401 nanos
total run time: 10,195,402 nanos
run count: 5
avg run time: 2,039,080 nanos
dispatcher: general
max quantum: 100,000 nanos
quantum overruns: 2
Pinger (id 4)
min run time: 61 nanos
max run time: 33,913,494 nanos
total run time: 953,601,532 nanos
run count: 338,447
avg run time: 2,817 nanos
dispatcher: ping
max quantum: 100,000 nanos
quantum overruns: 179
Ponger (id 5)
min run time: 164 nanos
max run time: 4,439,180 nanos
total run time: 926,228,288 nanos
run count: 132,905
avg run time: 6,969 nanos
dispatcher: pong
max quantum: 100,000 nanos
quantum overruns: 235
public static java.util.List<EClient> getClients()
public static java.util.List<EClient.RQThread> runQueueThreads()
RQThread
state.public static EClient findClient(EObject client)
null
if client
is currently
unknown to eBus.client
- search for this client's eBus proxy.client
.public void threadDenial(AlarmCondition condition)
condition
- thread denial condition.public static EClient findOrCreateClient(EObject client, EClient.ClientLocation location)
client
- the eBus client.location
- EClient.ClientLocation.LOCAL
if the client
is local to this JVM and EClient.ClientLocation.REMOTE
if
it exists in a remote eBus application.public static void dispatch(java.lang.Runnable task, EObject client)
task
to client
's task queue (this is
the same task queue used for eBus message delivery). If
the task queue was originally empty, then the client
posted to its run queue for execution by a
RQThread
.
If client
is unknown to eBus, then a new
EClient
instance will be created with a
weak reference
to client
.
client
does not need to be an eBus
publisher/ subscriber/requestor/replier.
task
- post to the client task queue.client
- task
is for this client.java.lang.NullPointerException
- if either task
or client
is null
.Copyright © 2001 - 2024. Charles W. Rapp. All rights reserved.