Package org.agrona.concurrent

Class BackoffIdleStrategy

java.lang.Object
org.agrona.concurrent.BackoffIdleStrategy
All Implemented Interfaces:
IdleStrategy
public final class BackoffIdleStrategy extends Object implements IdleStrategy
Idling strategy for threads when they have no work to do.

Spin for maxSpins, then Thread.yield() for maxYields, then LockSupport.parkNanos(long) on an exponential backoff to maxParkPeriodNs.

Under Linux, multiple timer events will be coalesced in a 50 us window to minimize the timer overhead on the CPU. E.g. if you want to wait 10 us, it could be you need to wait 50us. This situation can be improved by changing the value of the timerslack_ns property which defaults to 50000. This can be done like this: echo 10000 > /proc/PID/timerslack_ns This will set the timer slack to 10 microseconds for the given PID of the thread. This property can't be set at the process level, so needs to be set for each thread specifically. Also, it isn't guaranteed that after setting the property, the waiting time will be respected.

  • Field Details

    • ALIAS

      public static final String ALIAS
      Name to be returned from alias().
      See Also:

    • DEFAULT_MAX_SPINS

      public static final long DEFAULT_MAX_SPINS
      Default number of times the strategy will spin without work before going to next state.
      See Also:

    • DEFAULT_MAX_YIELDS

      public static final long DEFAULT_MAX_YIELDS
      Default number of times the strategy will yield without work before going to next state.
      See Also:

    • DEFAULT_MIN_PARK_PERIOD_NS

      public static final long DEFAULT_MIN_PARK_PERIOD_NS
      Default minimum interval the strategy will park a thread.
      See Also:

    • DEFAULT_MAX_PARK_PERIOD_NS

      public static final long DEFAULT_MAX_PARK_PERIOD_NS
      Default maximum interval the strategy will park a thread.
      See Also:

    • NOT_IDLE

      protected static final int NOT_IDLE
      Denotes a non-idle state.
      See Also:

    • SPINNING

      protected static final int SPINNING
      Denotes a spinning state.
      See Also:

    • YIELDING

      protected static final int YIELDING
      Denotes a yielding state.
      See Also:

    • PARKING

      protected static final int PARKING
      Denotes a parking state.
      See Also:

    • maxSpins

      protected final long maxSpins
      Max number of spins.

    • maxYields

      protected final long maxYields
      Max number of yields.

    • minParkPeriodNs

      protected final long minParkPeriodNs
      Min park period in nanoseconds.

    • maxParkPeriodNs

      protected final long maxParkPeriodNs
      Max park period in nanoseconds.

    • state

      protected int state
      Current state.

    • spins

      protected long spins
      Number of spins.

    • yields

      protected long yields
      Number of yields.

    • parkPeriodNs

      protected long parkPeriodNs
      Park period in nanoseconds.

  • Constructor Details

  • Method Details

    • idle

      public void idle(int workCount)
      Perform current idle action (e.g. nothing/yield/sleep). This method signature expects users to call into it on every work 'cycle'. The implementations may use the indication "workCount > 0" to reset internal backoff state. This method works well with 'work' APIs which follow the following rules:
      • 'work' returns a value larger than 0 when some work has been done
      • 'work' returns 0 when no work has been done
      • 'work' may return error codes which are less than 0, but which amount to no work has been done

      Callers are expected to follow this pattern: 

       
 while (isRunning)
 {
     idleStrategy.idle(doWork());
 }
      Specified by:
      idle in interface IdleStrategy
      Parameters:
      workCount - performed in last duty cycle.

    • idle

      public void idle()
      Perform current idle action (e.g. nothing/yield/sleep). To be used in conjunction with IdleStrategy.reset() to clear internal state when idle period is over (or before it begins). Callers are expected to follow this pattern: 
       
 while (isRunning)
 {
   if (!hasWork())
   {
     idleStrategy.reset();
     while (!hasWork())
     {
       if (!isRunning)
       {
         return;
       }
       idleStrategy.idle();
     }
   }
   doWork();
 }
      Specified by:
      idle in interface IdleStrategy

    • reset

      public void reset()
      Reset the internal state in preparation for entering an idle state again.
      Specified by:
      reset in interface IdleStrategy

    • alias

      public String alias()
      Simple name by which the strategy can be identified.
      Specified by:
      alias in interface IdleStrategy
      Returns:
      simple name by which the strategy can be identified.

    • toString

      public String toString()
      Overrides:
      toString in class Object