org.eclipse.wst.jsdt.chromium

## Class CallbackSemaphore

- java.lang.Object
- - org.eclipse.wst.jsdt.chromium.CallbackSemaphore

All Implemented Interfaces:
  SyncCallback

    public class CallbackSemaphore
    extends java.lang.Object
    implements SyncCallback

Convenient implementation of `SyncCallback`. Client may create one, then call asynchronous command, and finally wait on blocking method `#tryAcquire()` or `acquireDefault(org.eclipse.wst.jsdt.chromium.RelayOk)`.

Class uses symbolic parameter `RelayOk` in its methods that suggests that user should first call some asynchronous method, then pass it to the acquire method.

### Field Summary

Fields
`static long` `OPERATION_TIMEOUT_MS`

### Constructor Summary

Constructors
Constructor and Description
`CallbackSemaphore()`

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `acquireDefault(RelayOk relayOk)`
`void` `callbackDone(java.lang.RuntimeException e)` Implementation of `SyncCallback#callbackDone(RuntimeException)`.
`boolean` `tryAcquire(long timeout, java.util.concurrent.TimeUnit unit)` Tries to acquire the semaphore.
`boolean` `tryAcquireDefault(RelayOk relayOk)` Tries to acquire semaphore with some reasonable default timeout.

### Methods inherited from class java.lang.Object

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

### Field Detail

#### OPERATION_TIMEOUT_MS

    public static final long OPERATION_TIMEOUT_MS

See Also:
  Constant Field Values

### Constructor Detail

#### CallbackSemaphore

    public CallbackSemaphore()

### Method Detail

#### tryAcquireDefault

    public boolean tryAcquireDefault(RelayOk relayOk)
                              throws MethodIsBlockingException

Tries to acquire semaphore with some reasonable default timeout.

Parameters:
  `relayOk` - symbolic return value from the asynchronous operation that we are waiting for
Returns:
  false if `#OPERATION_TIMEOUT_MS` was exceeded and we gave up
Throws:
  `MethodIsBlockingException` - if called from a callback

#### acquireDefault

    public void acquireDefault(RelayOk relayOk)
                        throws MethodIsBlockingException

Parameters:
  `relayOk` - symbolic return value from the asynchronous operation that we are waiting for
Throws:
  `MethodIsBlockingException`

#### tryAcquire

    public boolean tryAcquire(long timeout,
                              java.util.concurrent.TimeUnit unit)
                       throws MethodIsBlockingException

Tries to acquire the semaphore. This method blocks until the semaphore is released; typically release call comes from a worker thread of org.eclipse.wst.jsdt.chromium, the same thread that may call all other callbacks. It is vital not to call this method from any callback of org.eclipse.wst.jsdt.chromium, because it's a sure deadlock. To prevent, this the method declares throwing `MethodIsBlockingException` which is symbolically thrown whenever someone violates this rule (i.e. invokes this method from a callback). Though currently nobody actually throws it, such declarations help to track blocking methods.

Returns:
  false if `timeout` was exceeded and we gave up
Throws:
  `MethodIsBlockingException` - if called from a callback

#### callbackDone

    public void callbackDone(java.lang.RuntimeException e)

Implementation of `SyncCallback#callbackDone(RuntimeException)`.

Specified by:
  `callbackDone` in interface `SyncCallback`
Parameters:
  `e` - an exception main callback raised or null if none is reported