org.apache.hadoop.hbase.procedure
Class Procedure

java.lang.Object
  extended by 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
protected  TimeoutExceptionInjector timeoutInjector
           
protected  long wakeFrequency
          frequency to check for errors (ms)
 
Constructor Summary
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
 void barrierAcquiredByMember(String member)
          Call back triggered by an individual member upon successful local barrier acquisition
 void barrierReleasedByMember(String member)
          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()
           
 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.
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)
Call back triggered by a individual member upon successful local in-barrier execution and release

Parameters:
member -

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

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


Copyright © 2007–2015 The Apache Software Foundation. All rights reserved.