org.apache.hadoop.hbase.procedure

Class Procedure

java.lang.Object

org.apache.hadoop.hbase.procedure.Procedure

All Implemented Interfaces:

Callable<Void>, ForeignExceptionListener

@InterfaceAudience.Private
public class Procedure
extends Object
implements Callable<Void>, ForeignExceptionListener

A globally-barriered distributed procedure. This class encapsulates state and methods for tracking and managing a distributed procedure, as well as aborting if any member encounters a problem or if a cancellation is requested.

All procedures first attempt to reach a barrier point with the sendGlobalBarrierStart() method. The procedure contacts all members and waits for all subprocedures to execute Subprocedure.acquireBarrier() to acquire its local piece of the global barrier and then send acquisition info back to the coordinator. If all acquisitions at subprocedures succeed, the coordinator then will call sendGlobalBarrierReached(). This notifies members to execute the Subprocedure.insideBarrier() method. The procedure is blocked until all Subprocedure.insideBarrier() executions complete at the members. When Subprocedure.insideBarrier() completes at each member, the member sends notification to the coordinator. Once all members complete, the coordinator calls sendGlobalBarrierComplete().

If errors are encountered remotely, they are forwarded to the coordinator, and Subprocedure.cleanup(Exception) is called.

Each Procedure and each Subprocedure enforces a time limit on the execution time. If the time limit expires before the procedure completes the TimeoutExceptionInjector will trigger an ForeignException to abort the procedure. This is particularly useful for situations when running a distributed Subprocedure so participants can avoid blocking for extreme amounts of time if one of the participants fails or takes a really long time (e.g. GC pause).

Users should generally not directly create or subclass instances of this. They are created for them implicitly via ProcedureCoordinator.startProcedure(ForeignExceptionDispatcher, String, byte[], List)}

Field Summary

Fields

Modifier and Type	Field and Description
protected TimeoutExceptionInjector	timeoutInjector
protected long	wakeFrequency frequency to check for errors (ms)

Constructor Summary

Constructors

Constructor and Description
Procedure(ProcedureCoordinator coord, ForeignExceptionDispatcher monitor, long wakeFreq, long timeout, String procName, byte[] args, List<String> expectedMembers) Creates a procedure.
Procedure(ProcedureCoordinator coord, long wakeFreq, long timeout, String procName, byte[] args, List<String> expectedMembers) Create a procedure.

Method Summary

Modifier and Type	Method and Description
void	barrierAcquiredByMember(String member) Call back triggered by an individual member upon successful local barrier acquisition
void	barrierReleasedByMember(String member, byte[] dataFromMember) Call back triggered by a individual member upon successful local in-barrier execution and release
Void	call() This call is the main execution thread of the barriered procedure.
ForeignExceptionDispatcher	getErrorMonitor() Get the ForeignExceptionDispatcher
String	getName()
String	getStatus()
boolean	isCompleted() Check if the entire procedure has globally completed, or has been aborted.
void	receive(ForeignException e) A callback that handles incoming ForeignExceptions.
void	sendGlobalBarrierComplete() Sends a message to members that all Subprocedure.insideBarrier() calls have completed.
void	sendGlobalBarrierReached() Sends a message to all members that the global barrier condition has been satisfied.
void	sendGlobalBarrierStart() Sends a message to Members to create a new Subprocedure for this Procedure and execute the Subprocedure.acquireBarrier() step.
void	waitForCompleted() Waits until the entire procedure has globally completed, or has been aborted.
HashMap<String,byte[]>	waitForCompletedWithRet() Waits until the entire procedure has globally completed, or has been aborted.
static void	waitForLatch(CountDownLatch latch, ForeignExceptionSnare monitor, long wakeFrequency, String latchDescription) Wait for latch to count to zero, ignoring any spurious wake-ups, but waking periodically to check for errors

Methods inherited from class java.lang.Object

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

Field Detail

wakeFrequency

protected final long wakeFrequency

frequency to check for errors (ms)

timeoutInjector

protected final TimeoutExceptionInjector timeoutInjector

Constructor Detail

Procedure

public Procedure(ProcedureCoordinator coord,
                 ForeignExceptionDispatcher monitor,
                 long wakeFreq,
                 long timeout,
                 String procName,
                 byte[] args,
                 List<String> expectedMembers)

Creates a procedure. (FOR TESTING) Procedure state to be run by a ProcedureCoordinator.

Parameters:

coord - coordinator to call back to for general errors (e.g. ProcedureCoordinator.rpcConnectionFailure(String, IOException)).

monitor - error monitor to check for external errors

wakeFreq - frequency to check for errors while waiting

timeout - amount of time to allow the procedure to run before cancelling

procName - name of the procedure instance

args - argument data associated with the procedure instance

expectedMembers - names of the expected members

Procedure

public Procedure(ProcedureCoordinator coord,
                 long wakeFreq,
                 long timeout,
                 String procName,
                 byte[] args,
                 List<String> expectedMembers)

Create a procedure. Users should generally not directly create instances of this. They are created them implicitly via ProcedureCoordinator.createProcedure(ForeignExceptionDispatcher, String, byte[], List)}

Parameters:

coord - coordinator to call back to for general errors (e.g. ProcedureCoordinator.rpcConnectionFailure(String, IOException)).

wakeFreq - frequency to check for errors while waiting

timeout - amount of time to allow the procedure to run before cancelling

procName - name of the procedure instance

args - argument data associated with the procedure instance

expectedMembers - names of the expected members

Method Detail

getName

public String getName()

getStatus

public String getStatus()

Returns:

String of the procedure members both trying to enter the barrier and already in barrier

getErrorMonitor

public ForeignExceptionDispatcher getErrorMonitor()

Get the ForeignExceptionDispatcher

Returns:

the Procedure's monitor.

call

public final Void call()

This call is the main execution thread of the barriered procedure. It sends messages and essentially blocks until all procedure members acquire or later complete but periodically checks for foreign exceptions.

Specified by:

call in interface Callable<Void>

sendGlobalBarrierStart

public void sendGlobalBarrierStart()
                            throws ForeignException

Sends a message to Members to create a new Subprocedure for this Procedure and execute the Subprocedure.acquireBarrier() step.

Throws:

ForeignException

sendGlobalBarrierReached

public void sendGlobalBarrierReached()
                              throws ForeignException

Sends a message to all members that the global barrier condition has been satisfied. This should only be executed after all members have completed its Subprocedure.acquireBarrier() call successfully. This triggers the member Subprocedure.insideBarrier() method.

Throws:

ForeignException

sendGlobalBarrierComplete

public void sendGlobalBarrierComplete()

Sends a message to members that all Subprocedure.insideBarrier() calls have completed. After this executes, the coordinator can assume that any state resources about this barrier procedure state has been released.

barrierAcquiredByMember

public void barrierAcquiredByMember(String member)

Call back triggered by an individual member upon successful local barrier acquisition

Parameters:

member -

barrierReleasedByMember

public void barrierReleasedByMember(String member,
                                    byte[] dataFromMember)

Call back triggered by a individual member upon successful local in-barrier execution and release

Parameters:

member -

dataFromMember -

waitForCompleted

public void waitForCompleted()
                      throws ForeignException,
                             InterruptedException

Waits until the entire procedure has globally completed, or has been aborted. If an exception is thrown the procedure may or not have run cleanup to trigger the completion latch yet.

Throws:

ForeignException

InterruptedException

waitForCompletedWithRet

public HashMap<String,byte[]> waitForCompletedWithRet()
                                               throws ForeignException,
                                                      InterruptedException

Waits until the entire procedure has globally completed, or has been aborted. If an exception is thrown the procedure may or not have run cleanup to trigger the completion latch yet.

Returns:

data returned from procedure members upon successfully completing subprocedure.

Throws:

ForeignException

InterruptedException

isCompleted

public boolean isCompleted()
                    throws ForeignException

Check if the entire procedure has globally completed, or has been aborted.

Throws:

ForeignException

receive

public void receive(ForeignException e)

A callback that handles incoming ForeignExceptions.

Specified by:

receive in interface ForeignExceptionListener

Parameters:

e - exception causing the error. Implementations must accept and handle null here.

waitForLatch

public static void waitForLatch(CountDownLatch latch,
                                ForeignExceptionSnare monitor,
                                long wakeFrequency,
                                String latchDescription)
                         throws ForeignException,
                                InterruptedException

Wait for latch to count to zero, ignoring any spurious wake-ups, but waking periodically to check for errors

Parameters:

latch - latch to wait on

monitor - monitor to check for errors while waiting

wakeFrequency - frequency to wake up and check for errors (in TimeUnit.MILLISECONDS)

latchDescription - description of the latch, for logging

Throws:

ForeignException - type of error the monitor can throw, if the task fails

InterruptedException - if we are interrupted while waiting on latch