org.apache.flink.runtime.rpc

Class RpcEndpoint

java.lang.Object

org.apache.flink.runtime.rpc.RpcEndpoint

All Implemented Interfaces:

RpcGateway

Direct Known Subclasses:

FencedRpcEndpoint, SlotPool, TaskExecutor

public abstract class RpcEndpoint
extends Object
implements RpcGateway

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 provides runAsync(Runnable), callAsync(Callable, Time) and the getMainThreadExecutor() to execute code in the RPC endpoint's main thread.

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.

Method Summary

Modifier and Type	Method and Description
protected <V> CompletableFuture<V>	callAsync(Callable<V> callable, Time timeout) Execute the callable in the main thread of the underlying RPC service, returning a future for the result of the callable.
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> 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.
abstract CompletableFuture<Void>	postStop() User overridable callback.
protected void	runAsync(Runnable runnable) Execute the runnable in the main thread of the underlying RPC endpoint.
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.
protected void	scheduleRunAsync(Runnable runnable, Time delay) Execute the runnable in the main thread of the underlying RPC endpoint, with a delay of the given number of milliseconds.
void	shutDown() Triggers the shut down of the rpc endpoint.
void	start() Starts the rpc endpoint.
protected void	stop() Stops the rpc endpoint.
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

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)

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.

start

public void start()
           throws Exception

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

IMPORTANT: Whenever you override this method, call the parent implementation to enable rpc processing. It is advised to make the parent call last.

Throws:

Exception - indicating that something went wrong while starting the RPC endpoint

stop

protected final void stop()

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

postStop

public abstract CompletableFuture<Void> postStop()

User overridable callback.

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

shutDown

public final void shutDown()

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.

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

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,
                                Time 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,
                                             Time 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
 }