Class RunStateTally

java.lang.Object
io.nosqlbench.engine.api.activityimpl.motor.RunStateTally
public class RunStateTally extends Object

Synopsis

Event-oriented tally of the runtime states of all motor threads. This is meant to be used as the definitive aggregate scorecard for an activity's thread states.

Purpose

This limits inter-thread signaling requirements by constraining the cases for which blockers are notified. This is because the meaningful scenarios for which a blocker would want to be notified do not include changes of positive values to other positive values. This allows an explicit optimization around scenarios for which a state count increments to 1 or decrements to 0, as in "some" or "none". This is an effective optimization for scenarios with many active threads.

Calling Semantics

Callers of the await functions will block for the required condition or, if specified, the timeout to occur without the condition. These callers are unblocked atomically, after any state add, state remove, or state change events are fully completed.

RunStateImage is returned from blocking methods so that callers can know consistently what the current run states were at the time their condition was met or timed out. Any callers of such methods must check for whether the condition was successfully met via RunStateImage.isTimeout()

Invariants

  • Under consistent usage patterns, all counts should be zero or positive at all times.
  • The current count for each state should be equal to the visible RunState on each motor thread, as all transitions are made through the motor threads directly.

  • Field Details

    • DEFAULT_TIMEOUT_MS

      public final long DEFAULT_TIMEOUT_MS
      If no timeout is given for any of the await methods, then the default is to wait for approximately many eons. Some tests run until told to stop.
      See Also:

  • Constructor Details

    • RunStateTally

      public RunStateTally()

  • Method Details

    • tallyFor

      public int tallyFor(RunState runState)
      Parameters:
      runState - The RunState to count
      Returns:
      the current count for the specified state

    • change

      public void change(RunState from, RunState to)
      Signal that a motor thread has left one RunState and entered another, atomically. After both counts are updated, if any RunState counts changed to or from zero, then all potential observers are notified to re-evaluate their await conditions.
      Parameters:
      from - the prior RunState
      to - the next RunState

    • add

      public void add(RunState state)
      Add a previously untracked motor thread to state tracking with the provided RunState. If the given state's count becomes non-zero, then all potential observers are notified to re-evaluate their await conditions.
      Parameters:
      state - The initial tracking state for the related motor thread

    • remove

      public void remove(RunState state)
      Remove a previously tracked motor thread from state tracking with the provided RunState. If the given state's count becomes zero, then all potential observers are notified to re-evaluate their await conditions.
      Parameters:
      state - The final tracking state for the related motor thread

    • awaitNoneOther

      public RunStateImage awaitNoneOther(RunState... runStates)
      Await until all states but the provided RunStates have zero counts. This condition matches if the provided states have zero or positive counts if and only if all other states have zero counts. Thus, if there are no positive values at all, this condition will still match.
      Parameters:
      runStates - The states which may have zero counts and still match the condition
      Returns:
      A RunStateImage, indicating success or failure, and the view of states at the time of evaluation

    • awaitNoneOther

      public RunStateImage awaitNoneOther(long timeoutMillis, RunState... runStates)
      Exactly like awaitNoneOther(long, RunState...), except that it allows for a timeout, after which the method will unblock and signal an error if the await condition is still false.
      Parameters:
      runStates - RunStates which are the only valid states before unblocking
      Returns:
      A RunStateImage, indicating success or failure, and the view of states at the time of evaluation

    • awaitNoneOf

      public RunStateImage awaitNoneOf(RunState... runStates)
      Await until there are zero counts for all of the specified RunStates.
      Parameters:
      runStates - all RunStates which must be zeroed before unblocking
      Returns:
      A RunStateImage, indicating success or failure, and the view of states at the time of evaluation

    • awaitNoneOf

      public RunStateImage awaitNoneOf(long timeoutMillis, RunState... runStates)
      Exactly like awaitNoneOf(RunState...), except that it allows for a timeout, after which the method will unblock and signal a timeout if the await condition is still not met.
      Parameters:
      runStates - all RunStates which must be zeroed before unblocking
      Returns:
      A RunStateImage, indicating success or failure, and the view of states at the time of evaluation

    • awaitAny

      public RunStateImage awaitAny(RunState... runStates)
      Await until at least one of the provided runStates has a positive value.
      Parameters:
      runStates - RunStates any of which allow unblocking
      Returns:
      A RunStateImage, indicating success or failure, and the view of states at the time of evaluation

    • awaitAny

      public RunStateImage awaitAny(long timeoutMillis, RunState... runStates)
      Exactly like awaitAny(RunState...), except that it allows for a timeout, after which the method will unblock and signal a timeout if the await condition is still not met.
      Parameters:
      timeoutMillis - Milliseconds to wait for any of the runstates before giving up
      runStates - RunStates any of which allow unblocking
      Returns:
      A RunStateImage, indicating success or failure, and the view of states at the time of evaluation

    • toString

      public String toString(RunState... runStates)

    • toString

      public String toString()
      Overrides:
      toString in class Object