public abstract class RpcEndpoint extends Object implements RpcGateway, AutoCloseableAsync
RpcService
.
To be done...
All RPC calls on the same endpoint are called by the same thread (referred to as the endpoint's main thread). Thus, by executing all state changing operations within the main thread, we don't have to reason about concurrent accesses, in the same way in the Actor Model of Erlang or Akka.
The RPC endpoint provides runAsync(Runnable)
, callAsync(Callable, Duration)
and the getMainThreadExecutor()
to execute code in the RPC endpoint's main thread.
The RPC endpoint has the following stages:
start()
method triggers the start of the RPC endpoint and schedules
overridable onStart()
method call to the main thread.
closeAsync()
method triggers the termination of the RPC endpoint and
schedules overridable onStop()
method call to the main thread.
onStop()
method is called, it triggers an asynchronous stop operation. The
RPC endpoint is not in the running state anymore but it continues to serve RPC requests.
The running state can be queried in a RPC method handler or in the main thread by calling
isRunning()
method.
Modifier and Type | Class and Description |
---|---|
protected static class |
RpcEndpoint.MainThreadExecutor
Executor which executes runnables in the main thread context.
|
Modifier and Type | Field and Description |
---|---|
protected org.slf4j.Logger |
log |
protected RpcServer |
rpcServer
Interface to access the underlying rpc server.
|
Modifier | Constructor and Description |
---|---|
protected |
RpcEndpoint(RpcService rpcService)
Initializes the RPC endpoint with a random endpoint id.
|
protected |
RpcEndpoint(RpcService rpcService,
String endpointId)
Initializes the RPC endpoint.
|
Modifier and Type | Method and Description |
---|---|
protected <V> CompletableFuture<V> |
callAsync(Callable<V> callable,
java.time.Duration timeout)
Execute the callable in the main thread of the underlying RPC service, returning a future for
the result of the callable.
|
CompletableFuture<Void> |
closeAsync()
Triggers the shut down of the rpc endpoint.
|
String |
getAddress()
Gets the address of the underlying RPC endpoint.
|
String |
getEndpointId()
Returns the rpc endpoint's identifier.
|
String |
getHostname()
Gets the hostname of the underlying RPC endpoint.
|
protected RpcEndpoint.MainThreadExecutor |
getMainThreadExecutor()
Gets the main thread execution context.
|
RpcService |
getRpcService()
Gets the endpoint's RPC service.
|
<C extends RpcGateway> |
getSelfGateway(Class<C> selfGatewayType)
Returns a self gateway of the specified type which can be used to issue asynchronous calls
against the RpcEndpoint.
|
CompletableFuture<Void> |
getTerminationFuture()
Return a future which is completed with true when the rpc endpoint has been terminated.
|
void |
internalCallOnStart()
Internal method which is called by the RpcService implementation to start the RpcEndpoint.
|
CompletableFuture<Void> |
internalCallOnStop()
Internal method which is called by the RpcService implementation to stop the RpcEndpoint.
|
protected boolean |
isRunning()
Returns whether the RPC endpoint is started and not stopped or being stopped.
|
protected void |
onStart()
User overridable callback which is called from
internalCallOnStart() . |
protected CompletableFuture<Void> |
onStop()
User overridable callback which is called from
internalCallOnStop() . |
protected void |
registerResource(Closeable closeableResource)
Register the given closeable resource to
CloseableRegistry . |
protected void |
runAsync(Runnable runnable)
Execute the runnable in the main thread of the underlying RPC endpoint.
|
protected void |
scheduleRunAsync(Runnable runnable,
java.time.Duration delay)
Execute the runnable in the main thread of the underlying RPC endpoint, with a delay of the
given number of milliseconds.
|
protected void |
scheduleRunAsync(Runnable runnable,
long delay,
TimeUnit unit)
Execute the runnable in the main thread of the underlying RPC endpoint, with a delay of the
given number of milliseconds.
|
void |
start()
Triggers start of the rpc endpoint.
|
protected void |
stop()
Triggers stop of the rpc endpoint.
|
protected boolean |
unregisterResource(Closeable closeableResource)
Unregister the given closeable resource from
CloseableRegistry . |
void |
validateRunsInMainThread()
Validates that the method call happens in the RPC endpoint's main thread.
|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
close
protected final org.slf4j.Logger log
protected final RpcServer rpcServer
protected RpcEndpoint(RpcService rpcService, String endpointId)
rpcService
- The RPC server that dispatches calls to this RPC endpoint.endpointId
- Unique identifier for this endpointprotected RpcEndpoint(RpcService rpcService)
rpcService
- The RPC server that dispatches calls to this RPC endpoint.public String getEndpointId()
protected boolean isRunning()
public final void start()
public final void internalCallOnStart() throws Exception
Exception
- indicating that the rpc endpoint could not be started. If an exception
occurs, then the rpc endpoint will automatically terminate.protected void onStart() throws Exception
internalCallOnStart()
.
This method is called when the RpcEndpoint is being started. The method is guaranteed to be executed in the main thread context and can be used to start the rpc endpoint in the context of the rpc endpoint's main thread.
IMPORTANT: This method should never be called directly by the user.
Exception
- indicating that the rpc endpoint could not be started. If an exception
occurs, then the rpc endpoint will automatically terminate.protected final void stop()
public final CompletableFuture<Void> internalCallOnStop()
protected void registerResource(Closeable closeableResource)
CloseableRegistry
.closeableResource
- the given closeable resourceprotected boolean unregisterResource(Closeable closeableResource)
CloseableRegistry
.closeableResource
- the given closeable resourceprotected CompletableFuture<Void> onStop()
internalCallOnStop()
.
This method is called when the RpcEndpoint is being shut down. The method is guaranteed to be executed in the main thread context and can be used to clean up internal state.
IMPORTANT: This method should never be called directly by the user.
public final CompletableFuture<Void> closeAsync()
In order to wait on the completion of the shut down, obtain the termination future via
getTerminationFuture()
} and wait on its completion.
closeAsync
in interface AutoCloseableAsync
public <C extends RpcGateway> C getSelfGateway(Class<C> selfGatewayType)
IMPORTANT: The self gateway type must be implemented by the RpcEndpoint. Otherwise the method will fail.
C
- type of the self gateway to createselfGatewayType
- class of the self gateway typepublic String getAddress()
getAddress
in interface RpcGateway
public String getHostname()
getHostname
in interface RpcGateway
protected RpcEndpoint.MainThreadExecutor getMainThreadExecutor()
public RpcService getRpcService()
public CompletableFuture<Void> getTerminationFuture()
protected void runAsync(Runnable runnable)
runnable
- Runnable to be executed in the main thread of the underlying RPC endpointprotected void scheduleRunAsync(Runnable runnable, java.time.Duration delay)
runnable
- Runnable to be executeddelay
- The delay after which the runnable will be executedprotected void scheduleRunAsync(Runnable runnable, long delay, TimeUnit unit)
runnable
- Runnable to be executeddelay
- The delay after which the runnable will be executedprotected <V> CompletableFuture<V> callAsync(Callable<V> callable, java.time.Duration timeout)
TimeoutException
.V
- Return type of the callablecallable
- Callable to be executed in the main thread of the underlying rpc servertimeout
- Timeout for the callable to be completedpublic void validateRunsInMainThread()
IMPORTANT: This check only happens when assertions are enabled, such as when running tests.
This can be used for additional checks, like
protected void concurrencyCriticalMethod() {
validateRunsInMainThread();
// some critical stuff
}
Copyright © 2014–2024 The Apache Software Foundation. All rights reserved.