Procedure (Apache HBase 1.2.12 API)

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
`(package private) CountDownLatch`	`acquiredBarrierLatch` latch for waiting until all members have acquire in barrier state
`private List<String>`	`acquiringMembers`
`private byte[]`	`args`
`(package private) CountDownLatch`	`completedLatch` latch for waiting until a procedure has completed
`private ProcedureCoordinator`	`coord`
`private HashMap<String,byte[]>`	`dataFromFinishedMembers`
`private List<String>`	`inBarrierMembers`
`private Object`	`joinBarrierLock` lock to prevent nodes from acquiring and then releasing before we can track them
`private static org.apache.commons.logging.Log`	`LOG`
`private ForeignExceptionDispatcher`	`monitor` monitor to check for errors
`private String`	`procName`
`(package private) CountDownLatch`	`releasedBarrierLatch` latch for waiting until all members have executed and released their in barrier state
`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

Methods
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
  - LOG
```
private static final org.apache.commons.logging.Log LOG
```
  - procName
```
private final String procName
```
  - args
```
private final byte[] args
```
  - acquiredBarrierLatch
```
final CountDownLatch acquiredBarrierLatch
```
    latch for waiting until all members have acquire in barrier state
  - releasedBarrierLatch
```
final CountDownLatch releasedBarrierLatch
```
    latch for waiting until all members have executed and released their in barrier state
  - completedLatch
```
final CountDownLatch completedLatch
```
    latch for waiting until a procedure has completed
  - monitor
```
private final ForeignExceptionDispatcher monitor
```
    monitor to check for errors
  - wakeFrequency
```
protected final long wakeFrequency
```
    frequency to check for errors (ms)
  - timeoutInjector
```
protected final TimeoutExceptionInjector timeoutInjector
```
  - joinBarrierLock
```
private Object joinBarrierLock
```
    lock to prevent nodes from acquiring and then releasing before we can track them
  - acquiringMembers
```
private final List<String> acquiringMembers
```
  - inBarrierMembers
```
private final List<String> inBarrierMembers
```
  - dataFromFinishedMembers
```
private final HashMap<String,byte[]> dataFromFinishedMembers
```
  - coord
```
private ProcedureCoordinator coord
```
- 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

Class Procedure

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

LOG

procName

args

acquiredBarrierLatch

releasedBarrierLatch

completedLatch

monitor

wakeFrequency

timeoutInjector

joinBarrierLock

acquiringMembers

inBarrierMembers

dataFromFinishedMembers

coord

Constructor Detail

Procedure

Procedure

Method Detail

getName

getStatus

getErrorMonitor

call

sendGlobalBarrierStart

sendGlobalBarrierReached

sendGlobalBarrierComplete

barrierAcquiredByMember

barrierReleasedByMember

waitForCompleted

waitForCompletedWithRet

isCompleted

receive

waitForLatch