uka.karmi.rmi
Class CallHandler

java.lang.Object
  uka.karmi.rmi.CallHandler

All Implemented Interfaces:

java.lang.Runnable

public class CallHandler

extends java.lang.Object

implements java.lang.Runnable

A call handler manages the control flow at the client-side of a remote method invocation.

1. If a remote callback invocation enters, while a thread is waiting for the return of a remote method, the call handler dispatches this callback invocation to the waiting thread. This makes sure that all segments of a distributed thread that are located on the same machine are executed by the same Java thread.
2. If a thread is interrupted while waiting for a remote method invocation to return, the call handler sends this interrupt in an out-of-order invocation along the remote call to interrupt the thread executing the remote method implementation on the server-side.

Nested Class Summary

static interface	CallHandler.BlockingOperation
static interface	CallHandler.CallbackOperation

Field Summary

protected CallHandler.BlockingOperation	blockingOperation The blocking operation, which is delegated to the handler thread.
static int	CALLBACK This value in state signals a callback remote method invocation from another server thread.
protected CallHandler.CallbackOperation	callbackOperation The current callback that is processed while the blockingOperation waits for completion.
protected static Long2ObjectHashtable	callHandlers
static int	COMPLETED This value in state signals the completion of the blockingOperation delivered in handleCall(uka.karmi.rmi.CallHandler.BlockingOperation).
static int	IDLE This call handler is currently unused, or the requesting thread is still waiting for a signal.
protected boolean	interrupted Flag to keep track of interrupts received at the client-side.
private boolean	isTail Tracks the registration state of this call handler.
protected CallHandler	parent The parent call handler.
java.lang.Thread	receiveThread The thread that is currently responsible for receiving the method call return code.
protected int	state The internal state of this call handler.
private boolean	stopped

Constructor Summary

CallHandler()
Constructs a new client-side connection handler.

Method Summary

void	awaitCompletion()
protected void	callback(CallHandler.CallbackOperation callbackOperation) Announces a callback remote method invocation.
static void	dispatch(CallHandler.CallbackOperation callbackOperation) Main entry point for the remote method dispatch (for application methods) on the server-side.
static int	getRemoteRecursionDepth()
void	handleCall(CallHandler.BlockingOperation blockingOperation) Main entry-point for a client thread that has sent a remote method invocation and is now waiting for the result code (represented as CallHandler.BlockingOperation).
boolean	isInterrupted()
private void	processCallbacks(CallHandler.BlockingOperation blockingOperation)
void	register(long tid) Registers a handler for a given thread ID.
void	run() The main loop of the thread responsible for receiving the result code from the remote method invocation.
void	stop()
java.lang.String	toString()
java.lang.String	toStringMembers()
static java.lang.String	toStringState(int state)
void	unregister(long tid)

Methods inherited from class java.lang.Object

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

Field Detail

IDLE

public static final int IDLE

This call handler is currently unused, or the requesting thread is still waiting for a signal. This signal may be CALLBACK, or COMPLETED. The CALLBACK signal is assiciated with a callbackOperation.

See Also:

state, CALLBACK, callbackOperation, COMPLETED, Constant Field Values

CALLBACK

public static final int CALLBACK

This value in state signals a callback remote method invocation from another server thread. The callback associated with this signal is stored in callbackOperation.

See Also:

state, callbackOperation, Constant Field Values

COMPLETED

public static final int COMPLETED

This value in state signals the completion of the blockingOperation delivered in handleCall(uka.karmi.rmi.CallHandler.BlockingOperation).

See Also:

state, Constant Field Values

state

protected int state

The internal state of this call handler.

See Also:

IDLE, CALLBACK, COMPLETED

parent

protected CallHandler parent

The parent call handler. All call handlers for remote method invocations that belong to the same thread ID are linked together through the parent reference. The remote invocation represented by this call handler occurred within a callback remote invocation to an earlier remote method invocation represented by the parent call handler.

The call handler at the head of the parent list represents the most recent segment of the distributed thread.

isTail

private boolean isTail

Tracks the registration state of this call handler. If this call handler is not on top of the call handler stack, it cannot be unregistered. This flag was introduced to detect illegal call handler registration/unregistration sequences described in BUG/I0189.

callHandlers

protected static Long2ObjectHashtable callHandlers

interrupted

protected boolean interrupted

Flag to keep track of interrupts received at the client-side. Since interrupts are forwarded out-of-order to the server-side, the interrupt may be lost, if the remote method returns, before the interrupt signal has reached the server-side. If that happens, the interrupt is handled like a deferred interrupt returned from the server-side.

If this flag is set when handleCall(uka.karmi.rmi.CallHandler.BlockingOperation) returns, the server did not get the interrupt that was sent out-of-order to the remote machine. Now, the current thread is the head of the distributed thread, but the interrupt can not be re-thrown here:

• InterruptedException is a declared exception, therefore it can only occur at methods that declare InterruptedException to be thrown. The wait() method above is introduced by the communication subsystem, it is not a program location, the application expects InterruptedException to occur at.
• Additionally, InterruptedException can only be thrown from the stub method, if the application declared it to be thrown for the invoked remote method. Even if this was the case, the application does not expect to receive an InterruptedException from within the communication layer (with an stack trace that points to a location between the caller and the callee).
• For transparency, the interrupt must be propagated back to the invoking thread. On the client side, the invoking thread must be interrupted again to trigger a new InterruptedException at the next application specific program location that declares it.

See Also:

Connection.RETURN_INTERRUPT

callbackOperation

protected CallHandler.CallbackOperation callbackOperation

The current callback that is processed while the blockingOperation waits for completion. A callback is announced by setting this value. The completion of the announced callback is signaled by changing this value either to null or any other callback object.

See Also:

callback(CallHandler.CallbackOperation)

blockingOperation

protected CallHandler.BlockingOperation blockingOperation

The blocking operation, which is delegated to the handler thread. A new blocking operation is announced by setting this value. The handler thread immediately fetches this value and resets the state of this variable back to null.

See Also:

handleCall(uka.karmi.rmi.CallHandler.BlockingOperation)

receiveThread

public java.lang.Thread receiveThread

The thread that is currently responsible for receiving the method call return code. This variable is set when this thread enters the run() method.

stopped

private boolean stopped

Constructor Detail

CallHandler

public CallHandler()

Constructs a new client-side connection handler.

Method Detail

getRemoteRecursionDepth

public static int getRemoteRecursionDepth()

dispatch

public static void dispatch(CallHandler.CallbackOperation callbackOperation)
                     throws java.lang.Throwable

Main entry point for the remote method dispatch (for application methods) on the server-side. Called by the technology dependent server thread after unmarshaling the method invocation header.

Throws:

java.lang.Throwable

See Also:

StreamServer.service(uka.karmi.stream.StreamServerConnection)

register

public void register(long tid)

Registers a handler for a given thread ID. If a remote callback is received, it is redirected to the this handler. The registration should happen during openSendCall(). Registering during closeSendCall() is to late, because the call could already be on the way and the callback could be received before the registration of the handler is completed.

If another handler is already registered for the given thread ID, it is replaced by this handler. The parent handler is stored at this handler and re-registered at the time this handler is unregistered.

See Also:

unregister(long)

unregister

public void unregister(long tid)

See Also:

register(long)

isInterrupted

public boolean isInterrupted()

See Also:

interrupted

callback

protected void callback(CallHandler.CallbackOperation callbackOperation)
                 throws java.lang.Throwable

Announces a callback remote method invocation. This method may be called from another server thread that receives a callback remote method invocation for the thread ID this call handler is registered for. This invocation must be processed in the thread currently waiting in handleCall(uka.karmi.rmi.CallHandler.BlockingOperation) for the completion of the registered blockingOperation. This method blocks until the callback invocation has completed.

Throws:

java.lang.Throwable

See Also:

handleCall(uka.karmi.rmi.CallHandler.BlockingOperation)

stop

public void stop()

run

public void run()

The main loop of the thread responsible for receiving the result code from the remote method invocation.

Specified by:

run in interface java.lang.Runnable

awaitCompletion

public void awaitCompletion()
                     throws java.lang.InterruptedException

Throws:

java.lang.InterruptedException

handleCall

public void handleCall(CallHandler.BlockingOperation blockingOperation)

Main entry-point for a client thread that has sent a remote method invocation and is now waiting for the result code (represented as CallHandler.BlockingOperation).

This method handles incoming callback method invocations (represented as CallHandler.CallbackOperation and interrupts sent to the waiting thread. Callback invocations are executed in the thread that called this method, interrupts are forwarded out-of-order to the server-side.

See Also:

callback(CallHandler.CallbackOperation), run(), ClientConnection.openReceiveResult()

processCallbacks

private void processCallbacks(CallHandler.BlockingOperation blockingOperation)

toString

public java.lang.String toString()

toStringMembers

public java.lang.String toStringMembers()

toStringState

public static java.lang.String toStringState(int state)