org.apache.flink.runtime.rpc

Class RpcEndpoint

java.lang.Object

org.apache.flink.runtime.rpc.RpcEndpoint

All Implemented Interfaces:

AutoCloseable, RpcGateway, AutoCloseableAsync

Direct Known Subclasses:

FencedRpcEndpoint, MetricQueryService, TaskExecutor

public abstract class RpcEndpoint
extends Object
implements RpcGateway, AutoCloseableAsync

Base class for RPC endpoints. Distributed components which offer remote procedure calls have to extend the RPC endpoint base class. An RPC endpoint is backed by an RpcService.

Endpoint and Gateway

To be done...

Single Threaded Endpoint Execution

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.

Lifecycle

The RPC endpoint has the following stages:

• The RPC endpoint is created in a non-running state and does not serve any RPC requests.
• Calling the start() method triggers the start of the RPC endpoint and schedules overridable onStart() method call to the main thread.
• When the start operation ends the RPC endpoint is moved to the running state and starts to serve and complete RPC requests.
• Calling the closeAsync() method triggers the termination of the RPC endpoint and schedules overridable onStop() method call to the main thread.
• When 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.
• When the asynchronous stop operation ends, the RPC endpoint terminates completely and does not serve RPC requests anymore.

The running state can be queried in a RPC method handler or in the main thread by calling isRunning() method.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	RpcEndpoint.MainThreadExecutor Executor which executes runnables in the main thread context.

Field Summary

Fields

Modifier and Type	Field and Description
protected org.slf4j.Logger	log
protected RpcServer	rpcServer Interface to access the underlying rpc server.

Constructor Summary

Constructors

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.
protected	RpcEndpoint(RpcService rpcService, String endpointId, Map<String,String> loggingContext) Initializes the RPC endpoint.

Method Summary

Modifier and Type	Method and Description
protected <V> CompletableFuture<V>	callAsync(Callable<V> callable, 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.
protected Executor	getMainThreadExecutor(JobID jobID) Gets the main thread execution context.
RpcService	getRpcService() Gets the endpoint's RPC service.
<C extends RpcGateway> C	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, 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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.apache.flink.util.AutoCloseableAsync

close

Field Detail

log

protected final org.slf4j.Logger log

rpcServer

protected final RpcServer rpcServer

Interface to access the underlying rpc server.

Constructor Detail

RpcEndpoint

protected RpcEndpoint(RpcService rpcService,
                      String endpointId,
                      Map<String,String> loggingContext)

Initializes the RPC endpoint.

Parameters:

rpcService - The RPC server that dispatches calls to this RPC endpoint.

endpointId - Unique identifier for this endpoint

RpcEndpoint

protected RpcEndpoint(RpcService rpcService,
                      String endpointId)

Initializes the RPC endpoint.

Parameters:

rpcService - The RPC server that dispatches calls to this RPC endpoint.

endpointId - Unique identifier for this endpoint

RpcEndpoint

protected RpcEndpoint(RpcService rpcService)

Initializes the RPC endpoint with a random endpoint id.

Parameters:

rpcService - The RPC server that dispatches calls to this RPC endpoint.

Method Detail

getEndpointId

public String getEndpointId()

Returns the rpc endpoint's identifier.

Returns:

Rpc endpoint's identifier.

isRunning

protected boolean isRunning()

Returns whether the RPC endpoint is started and not stopped or being stopped.

Returns:

whether the RPC endpoint is started and not stopped or being stopped.

start

public final void start()

Triggers start of the rpc endpoint. This tells the underlying rpc server that the rpc endpoint is ready to process remote procedure calls.

internalCallOnStart

public final void internalCallOnStart()
                               throws Exception

Internal method which is called by the RpcService implementation to start the RpcEndpoint.

Throws:

Exception - indicating that the rpc endpoint could not be started. If an exception occurs, then the rpc endpoint will automatically terminate.

onStart

protected void onStart()
                throws Exception

User overridable callback which is called from 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.

Throws:

Exception - indicating that the rpc endpoint could not be started. If an exception occurs, then the rpc endpoint will automatically terminate.

stop

protected final void stop()

Triggers stop of the rpc endpoint. This tells the underlying rpc server that the rpc endpoint is no longer ready to process remote procedure calls.

internalCallOnStop

public final CompletableFuture<Void> internalCallOnStop()

Internal method which is called by the RpcService implementation to stop the RpcEndpoint.

Returns:

Future which is completed once all post stop actions are completed. If an error occurs this future is completed exceptionally

registerResource

protected void registerResource(Closeable closeableResource)

Register the given closeable resource to CloseableRegistry.

Parameters:

closeableResource - the given closeable resource

unregisterResource

protected boolean unregisterResource(Closeable closeableResource)

Unregister the given closeable resource from CloseableRegistry.

Parameters:

closeableResource - the given closeable resource

Returns:

true if the given resource unregister successful, otherwise false

onStop

protected CompletableFuture<Void> onStop()

User overridable callback which is called from 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.

Returns:

Future which is completed once all post stop actions are completed. If an error occurs this future is completed exceptionally

closeAsync

public final CompletableFuture<Void> closeAsync()

Triggers the shut down of the rpc endpoint. The shut down is executed asynchronously.

In order to wait on the completion of the shut down, obtain the termination future via getTerminationFuture()} and wait on its completion.

Specified by:

closeAsync in interface AutoCloseableAsync

Returns:

Future which is completed once the resource has been closed

getSelfGateway

public <C extends RpcGateway> C getSelfGateway(Class<C> selfGatewayType)

Returns a self gateway of the specified type which can be used to issue asynchronous calls against the RpcEndpoint.

IMPORTANT: The self gateway type must be implemented by the RpcEndpoint. Otherwise the method will fail.

Type Parameters:

C - type of the self gateway to create

Parameters:

selfGatewayType - class of the self gateway type

Returns:

Self gateway of the specified type which can be used to issue asynchronous rpcs

getAddress

public String getAddress()

Gets the address of the underlying RPC endpoint. The address should be fully qualified so that a remote system can connect to this RPC endpoint via this address.

Specified by:

getAddress in interface RpcGateway

Returns:

Fully qualified address of the underlying RPC endpoint

getHostname

public String getHostname()

Gets the hostname of the underlying RPC endpoint.

Specified by:

getHostname in interface RpcGateway

Returns:

Hostname on which the RPC endpoint is running

getMainThreadExecutor

protected RpcEndpoint.MainThreadExecutor getMainThreadExecutor()

Gets the main thread execution context. The main thread execution context can be used to execute tasks in the main thread of the underlying RPC endpoint.

Returns:

Main thread execution context

getMainThreadExecutor

protected Executor getMainThreadExecutor(JobID jobID)

Gets the main thread execution context. The main thread execution context can be used to execute tasks in the main thread of the underlying RPC endpoint.

Parameters:

jobID - the JobID to scope the returned ComponentMainThreadExecutor to, i.e. add/remove before/after the invocations using the returned executor

Returns:

Main thread execution context

getRpcService

public RpcService getRpcService()

Gets the endpoint's RPC service.

Returns:

The endpoint's RPC service

getTerminationFuture

public CompletableFuture<Void> getTerminationFuture()

Return a future which is completed with true when the rpc endpoint has been terminated. In case of a failure, this future is completed with the occurring exception.

Returns:

Future which is completed when the rpc endpoint has been terminated.

runAsync

protected void runAsync(Runnable runnable)

Execute the runnable in the main thread of the underlying RPC endpoint.

Parameters:

runnable - Runnable to be executed in the main thread of the underlying RPC endpoint

scheduleRunAsync

protected void scheduleRunAsync(Runnable runnable,
                                Duration delay)

Execute the runnable in the main thread of the underlying RPC endpoint, with a delay of the given number of milliseconds.

Parameters:

runnable - Runnable to be executed

delay - The delay after which the runnable will be executed

scheduleRunAsync

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.

Parameters:

runnable - Runnable to be executed

delay - The delay after which the runnable will be executed

callAsync

protected <V> CompletableFuture<V> callAsync(Callable<V> callable,
                                             Duration timeout)

Execute the callable in the main thread of the underlying RPC service, returning a future for the result of the callable. If the callable is not completed within the given timeout, then the future will be failed with a TimeoutException.

Type Parameters:

V - Return type of the callable

Parameters:

callable - Callable to be executed in the main thread of the underlying rpc server

timeout - Timeout for the callable to be completed

Returns:

Future for the result of the callable.

validateRunsInMainThread

public void validateRunsInMainThread()

Validates that the method call happens in the RPC endpoint's main thread.

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
 }