Module org.hsqldb
Package org.hsqldb.lib

## Class CountUpDownLatch

- java.lang.Object
- - org.hsqldb.lib.CountUpDownLatch

-     public class CountUpDownLatch
      extends java.lang.Object

  A variation on `CountDownLatch` to allow counting up as well as down.
  Author:
    Campbell Burnet (campbell-burnet@users dot sourceforge.net)

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `CountUpDownLatch()` | Default constructor.
    `CountUpDownLatch​(int initialCount)` | Constructs a new `CountUpDownLatch` initialized with the given `initialCount`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `await()` | Causes the current thread to wait until `count` reaches zero, unless the thread is interrupted.
    `boolean` | `await​(long timeout, java.util.concurrent.TimeUnit unit)` | Causes the current thread to wait until `count` reaches zero, unless the thread is interrupted, or the specified waiting time elapses.
    `boolean` | `countDown()` | Decrements the count of the latch, releasing all waiting threads if the count transitions to zero.
    `boolean` | `countDown​(int amount)` | Decrements the `count` of the latch by the given `amount`, releasing all waiting threads if `count` transitions to zero.
    `boolean` | `countUp()` | Increments the count of the latch.
    `boolean` | `countUp​(int amount)` | Increments the count of the latch by the given `amount`.
    `boolean` | `equals​(java.lang.Object obj)` | Returns true if and only if `this` and `obj` refer to the same object (`this == obj` has the value `true`).
    `boolean` | `equals​(CountUpDownLatch other)` | Returns true if and only if `this` and `obj` refer to the same object (`this == obj` has the value `true`).
    `int` | `getCount()` | Returns the current count.
    `int` | `hashCode()` | As much as is reasonably practical, returns distinct integers for distinct objects.
    `boolean` | `setCount​(int newCount)` | Updates `count` to the requested `newCount`, returning `true` on transition to zero.
    `java.lang.String` | `toString()` | Returns a string representation of this object.

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

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### CountUpDownLatch

          public CountUpDownLatch()

      Default constructor.

      Equivalent to `new` `CountUpDownLatch``(0)`

    - #### CountUpDownLatch

          public CountUpDownLatch​(int initialCount)

      Constructs a new `CountUpDownLatch` initialized with the given `initialCount`.
      Parameters:
        `initialCount` - the initial `count`
      Throws:
        `java.lang.IllegalArgumentException` - if `initialCount` is negative

  - ### Method Detail

    - #### await

          public void await()
                     throws java.lang.InterruptedException

      Causes the current thread to wait until `count` reaches zero, unless the thread is interrupted.

      If the current `count` is already zero, then this method returns immediately.

      If the current `count` is greater than zero, then the current thread becomes disabled for thread scheduling purposes and lies dormant until either:

      - The count reaches zero due an invocation of `countDown()`, `countDown(int`}, or `setCount(int)`.
      - Some other thread interrupts the current thread.
      If the current thread:
      - has its interrupted status set on entry to this method; or
      - is interrupted while waiting,
      then `InterruptedException` is thrown and the current thread's interrupted status is cleared.
      Throws:
        `java.lang.InterruptedException` - if the current thread is interrupted while waiting

    - #### await

          public boolean await​(long timeout,
                               java.util.concurrent.TimeUnit unit)
                        throws java.lang.InterruptedException

      Causes the current thread to wait until `count` reaches zero, unless the thread is interrupted, or the specified waiting time elapses.

      If the current `count` is zero, then this method returns immediately with the value `true`.

      If the current `count` is greater than zero, then the current thread becomes disabled for thread scheduling purposes and lies dormant until either:

      - The `count` reaches zero due to an invocation of `countDown()`, `countDown(int`}, or `setCount(int)` setCount(int)}
      - Some other thread interrupts the current thread
      - The specified waiting time elapses.
      If the count reaches zero then the method returns with the value `true`.

      If the current thread:

      - has its interrupted status set on entry to this method; or
      - is interrupted while waiting,
      then `InterruptedException` is thrown and the current thread's interrupted status is cleared.

      If the specified waiting time elapses then the value `false` is returned. If the time is less than or equal to zero, the method will not wait at all.

      Parameters:
        `timeout` - the maximum time to wait
        `unit` - the time unit of the `timeout` argument
      Returns:
        `true` if the count reached zero and `false` if the waiting time elapsed before the count reached zero
      Throws:
        `java.lang.InterruptedException` - if the current thread is interrupted while waiting

    - #### countUp

          public boolean countUp()

      Increments the count of the latch.

      Returns:
        `true` if `count` transitioned from zero to a new value
      Throws:
        `java.lang.ArithmeticException` - when the operation would otherwise cause a silent numeric overflow, resulting in a negative `count`.

    - #### countUp

          public boolean countUp​(int amount)

      Increments the count of the latch by the given `amount`.

      Parameters:
        `amount` - by which to increment `count`
      Returns:
        `true` if `count` transitioned from zero to a new value
      Throws:
        `java.lang.ArithmeticException` - when the operation would otherwise cause a silent numeric overflow, resulting in a negative `count`.
        `java.lang.IllegalArgumentException` - if `amount` is less than one.

    - #### countDown

          public boolean countDown()

      Decrements the count of the latch, releasing all waiting threads if the count transitions to zero.

      If the current count is zero, no action occurs and false is returned immediately;

      Returns:
        `true` if `count` transitions to zero

    - #### countDown

          public boolean countDown​(int amount)

      Decrements the `count` of the latch by the given `amount`, releasing all waiting threads if `count` transitions to zero.

      If the current `count` is zero, no action occurs and false is returned immediately; otherwise, `count` is decremented by the lesser of `amount` and current `count` (i.e. if `amount` is greater than current `count`, then new `count` is zero, else new `count` is current `count` minus `amount`.

      Parameters:
        `amount` - by which to decrement the `count`
      Returns:
        `true` if `count` transitions to zero
      Throws:
        `java.lang.IllegalArgumentException` - when `amount` is non-positive

    - #### getCount

          public int getCount()

      Returns the current count.

      Because another thread may update `count` at any time, typically this should not be used to compute input values for any of the @{code count} mutating methods and instead should be reserved for debugging and testing purposes (e.g. to assert that the current count is the expected count, given a set of know operations has occurred and given that it is known no other threads could be updating the count)

      Returns:
        the current count

    - #### setCount

          public boolean setCount​(int newCount)

      Updates `count` to the requested `newCount`, returning `true` on transition to zero.

      If `newCount` is zero and the current `count` is zero, no action occurs and false is returned immediately. immediately;

      Parameters:
        `newCount` - to which to update `count`; must be non-negative.
      Returns:
        `true` if `count` transitions to zero.
      Throws:
        `java.lang.IllegalArgumentException` - when `newCount` is negative

    - #### toString

          public java.lang.String toString()

      Returns a string representation of this object.

      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a string identifying this latch, as well as its current `count`.

    - #### hashCode

          public int hashCode()

      As much as is reasonably practical, returns distinct integers for distinct objects.
      Overrides:
        `hashCode` in class `java.lang.Object`
      Returns:
        a hash code value for this latch. This method is supported for the benefit of hash tables

    - #### equals

          public boolean equals​(CountUpDownLatch other)

      Returns true if and only if `this` and `obj` refer to the same object (`this == obj` has the value `true`).
      Parameters:
        `other` - to test.
      Returns:
        if and only if `this == obj`

    - #### equals

          public boolean equals​(java.lang.Object obj)

      Returns true if and only if `this` and `obj` refer to the same object (`this == obj` has the value `true`).
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `obj` - to test.
      Returns:
        if and only if `this == obj`