Interface IdleStrategy

  • All Known Implementing Classes:
    BackoffIdleStrategy, BusySpinIdleStrategy, ControllableIdleStrategy, NoOpIdleStrategy, SleepingIdleStrategy, SleepingMillisIdleStrategy, YieldingIdleStrategy

    public interface IdleStrategy
    Idle strategy for use by threads when they do not have work to do.

    Note regarding implementor state

    Some implementations are known to be stateful, please note that you cannot safely assume implementations to be stateless. Where implementations are stateful it is recommended that implementation state is padded to avoid false sharing.

    Note regarding potential for TTSP(Time To Safe Point) issues

    If the caller spins in a 'counted' loop, and the implementation does not include a safepoint poll this may cause a TTSP (Time To SafePoint) problem. If this is the case for your application you can solve it by preventing the idle method from being inlined by using a Hotspot compiler command as a JVM argument e.g: -XX:CompileCommand=dontinline,org.agrona.concurrent.NoOpIdleStrategy::idle

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default java.lang.String alias()
      Simple name by which the strategy can be identified.
      void idle()
      Perform current idle action (e.g.
      void idle​(int workCount)
      Perform current idle action (e.g.
      void reset()
      Reset the internal state in preparation for entering an idle state again.
    • Method Detail

      • idle

        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());
         }
         
         
        Parameters:
        workCount - performed in last duty cycle.
      • idle

        void idle()
        Perform current idle action (e.g. nothing/yield/sleep). To be used in conjunction with 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();
         }
         
         
      • reset

        void reset()
        Reset the internal state in preparation for entering an idle state again.
      • alias

        default java.lang.String alias()
        Simple name by which the strategy can be identified.
        Returns:
        simple name by which the strategy can be identified.