Interface Scheduler

  • All Known Implementing Classes:
    AbstractScheduler, AbstractSchedulerBase, ExplicitlyTriggeredScheduler, LightArrayRevolverScheduler

    public interface Scheduler
    An Apache Pekko scheduler service.

    For scheduling within actors with Timers should be preferred.

    Please note that this scheduler implementation is highly optimised for high-throughput and high-frequency events. It is not to be confused with long-term schedulers such as Quartz. The scheduler will throw an exception if attempts are made to schedule too far into the future (which by default is around 8 months (Int.MaxValue seconds).

    It's possible to implement a custom Scheduler, although that should rarely be needed.

    A Scheduler implementation needs one special behavior: if Closeable, it MUST execute all outstanding tasks that implement Scheduler.TaskRunOnClose upon .close() in order to properly shutdown all dispatchers.

    Furthermore, this timer service MUST throw IllegalStateException if it cannot schedule a task. Once scheduled, the task MUST be executed. If executed upon close(), the task may execute before its timeout.

    Scheduler implementation are loaded reflectively at ActorSystem start-up with the following constructor arguments: 1) the system’s com.typesafe.config.Config (from system.settings.config) 2) a org.apache.pekko.event.LoggingAdapter 3) a java.util.concurrent.ThreadFactory

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Interface Description
      static class  Scheduler.AtomicCancellable
      INTERNAL API
      static interface  Scheduler.TaskRunOnClose
      If a TaskRunOnClose is used in scheduleOnce it will be run when the Scheduler is closed (ActorSystem shutdown).
    • Method Summary

      All Methods Instance Methods Abstract Methods Deprecated Methods 
      Modifier and Type Method Description
      double maxFrequency()
      The maximum supported task frequency of this scheduler, i.e.
      Cancellable schedule​(java.time.Duration initialDelay, java.time.Duration interval, java.lang.Runnable runnable, scala.concurrent.ExecutionContext executor)
      Deprecated.
      Use scheduleWithFixedDelay or scheduleAtFixedRate instead.
      Cancellable schedule​(java.time.Duration initialDelay, java.time.Duration interval, ActorRef receiver, java.lang.Object message, scala.concurrent.ExecutionContext executor, ActorRef sender)
      Deprecated.
      Use scheduleWithFixedDelay or scheduleAtFixedRate instead.
      Cancellable schedule​(scala.concurrent.duration.FiniteDuration initialDelay, scala.concurrent.duration.FiniteDuration interval, java.lang.Runnable runnable, scala.concurrent.ExecutionContext executor)
      Deprecated.
      Use scheduleWithFixedDelay or scheduleAtFixedRate instead.
      Cancellable schedule​(scala.concurrent.duration.FiniteDuration initialDelay, scala.concurrent.duration.FiniteDuration interval, ActorRef receiver, java.lang.Object message, scala.concurrent.ExecutionContext executor, ActorRef sender)
      Deprecated.
      Use scheduleWithFixedDelay or scheduleAtFixedRate instead.
      Cancellable schedule​(scala.concurrent.duration.FiniteDuration initialDelay, scala.concurrent.duration.FiniteDuration interval, scala.Function0<scala.runtime.BoxedUnit> f, scala.concurrent.ExecutionContext executor)
      Deprecated.
      Use scheduleWithFixedDelay or scheduleAtFixedRate instead.
      ActorRef schedule$default$6​(scala.concurrent.duration.FiniteDuration initialDelay, scala.concurrent.duration.FiniteDuration interval, ActorRef receiver, java.lang.Object message)
      Cancellable scheduleAtFixedRate​(java.time.Duration initialDelay, java.time.Duration interval, java.lang.Runnable runnable, scala.concurrent.ExecutionContext executor)
      Java API: Schedules a Runnable to be run repeatedly with an initial delay and a frequency.
      Cancellable scheduleAtFixedRate​(java.time.Duration initialDelay, java.time.Duration interval, ActorRef receiver, java.lang.Object message, scala.concurrent.ExecutionContext executor, ActorRef sender)
      Java API: Schedules a message to be sent repeatedly with an initial delay and frequency.
      Cancellable scheduleAtFixedRate​(scala.concurrent.duration.FiniteDuration initialDelay, scala.concurrent.duration.FiniteDuration interval, java.lang.Runnable runnable, scala.concurrent.ExecutionContext executor)
      Scala API: Schedules a Runnable to be run repeatedly with an initial delay and a frequency.
      Cancellable scheduleAtFixedRate​(scala.concurrent.duration.FiniteDuration initialDelay, scala.concurrent.duration.FiniteDuration interval, ActorRef receiver, java.lang.Object message, scala.concurrent.ExecutionContext executor, ActorRef sender)
      Scala API: Schedules a message to be sent repeatedly with an initial delay and frequency.
      ActorRef scheduleAtFixedRate$default$6​(scala.concurrent.duration.FiniteDuration initialDelay, scala.concurrent.duration.FiniteDuration interval, ActorRef receiver, java.lang.Object message)
      Scala API: Schedules a message to be sent repeatedly with an initial delay and frequency.
      Cancellable scheduleOnce​(java.time.Duration delay, java.lang.Runnable runnable, scala.concurrent.ExecutionContext executor)
      Java API: Schedules a Runnable to be run once with a delay, i.e.
      Cancellable scheduleOnce​(java.time.Duration delay, ActorRef receiver, java.lang.Object message, scala.concurrent.ExecutionContext executor, ActorRef sender)
      Java API: Schedules a message to be sent once with a delay, i.e.
      Cancellable scheduleOnce​(scala.concurrent.duration.FiniteDuration delay, java.lang.Runnable runnable, scala.concurrent.ExecutionContext executor)
      Scala API: Schedules a Runnable to be run once with a delay, i.e.
      Cancellable scheduleOnce​(scala.concurrent.duration.FiniteDuration delay, ActorRef receiver, java.lang.Object message, scala.concurrent.ExecutionContext executor, ActorRef sender)
      Scala API: Schedules a message to be sent once with a delay, i.e.
      Cancellable scheduleOnce​(scala.concurrent.duration.FiniteDuration delay, scala.Function0<scala.runtime.BoxedUnit> f, scala.concurrent.ExecutionContext executor)
      Scala API: Schedules a function to be run once with a delay, i.e.
      ActorRef scheduleOnce$default$5​(scala.concurrent.duration.FiniteDuration delay, ActorRef receiver, java.lang.Object message)  
      Cancellable scheduleWithFixedDelay​(java.time.Duration initialDelay, java.time.Duration delay, java.lang.Runnable runnable, scala.concurrent.ExecutionContext executor)
      Java API: Schedules a Runnable to be run repeatedly with an initial delay and a fixed delay between subsequent executions.
      Cancellable scheduleWithFixedDelay​(java.time.Duration initialDelay, java.time.Duration delay, ActorRef receiver, java.lang.Object message, scala.concurrent.ExecutionContext executor, ActorRef sender)
      Java API: Schedules a message to be sent repeatedly with an initial delay and a fixed delay between messages.
      Cancellable scheduleWithFixedDelay​(scala.concurrent.duration.FiniteDuration initialDelay, scala.concurrent.duration.FiniteDuration delay, java.lang.Runnable runnable, scala.concurrent.ExecutionContext executor)
      Scala API: Schedules a Runnable to be run repeatedly with an initial delay and a fixed delay between subsequent executions.
      Cancellable scheduleWithFixedDelay​(scala.concurrent.duration.FiniteDuration initialDelay, scala.concurrent.duration.FiniteDuration delay, ActorRef receiver, java.lang.Object message, scala.concurrent.ExecutionContext executor, ActorRef sender)
      Scala API: Schedules a message to be sent repeatedly with an initial delay and a fixed delay between messages.
      ActorRef scheduleWithFixedDelay$default$6​(scala.concurrent.duration.FiniteDuration initialDelay, scala.concurrent.duration.FiniteDuration delay, ActorRef receiver, java.lang.Object message)  
    • Method Detail

      • scheduleWithFixedDelay

        Cancellable scheduleWithFixedDelay​(scala.concurrent.duration.FiniteDuration initialDelay,
                                           scala.concurrent.duration.FiniteDuration delay,
                                           java.lang.Runnable runnable,
                                           scala.concurrent.ExecutionContext executor)
        Scala API: Schedules a Runnable to be run repeatedly with an initial delay and a fixed delay between subsequent executions. E.g. if you would like the function to be run after 2 seconds and thereafter every 100ms you would set delay=Duration(2, TimeUnit.SECONDS) and interval=Duration(100, TimeUnit.MILLISECONDS).

        It will not compensate the delay between tasks if the execution takes a long time or if scheduling is delayed longer than specified for some reason. The delay between subsequent execution will always be (at least) the given delay. In the long run, the frequency of execution will generally be slightly lower than the reciprocal of the specified delay.

        If the Runnable throws an exception the repeated scheduling is aborted, i.e. the function will not be invoked any more.

        Throws:
        java.lang.IllegalArgumentException - if the given delays is zero, negative or exceed the maximum reach (calculated as: delay / tickNanos > Int.MaxValue).

        Note: For scheduling within actors with Timers should be preferred.

      • scheduleWithFixedDelay

        Cancellable scheduleWithFixedDelay​(java.time.Duration initialDelay,
                                           java.time.Duration delay,
                                           java.lang.Runnable runnable,
                                           scala.concurrent.ExecutionContext executor)
        Java API: Schedules a Runnable to be run repeatedly with an initial delay and a fixed delay between subsequent executions. E.g. if you would like the function to be run after 2 seconds and thereafter every 100ms you would set delay to Duration.ofSeconds(2), and interval to Duration.ofMillis(100).

        It will not compensate the delay between tasks if the execution takes a long time or if scheduling is delayed longer than specified for some reason. The delay between subsequent execution will always be (at least) the given delay.

        In the long run, the frequency of tasks will generally be slightly lower than the reciprocal of the specified delay.

        If the Runnable throws an exception the repeated scheduling is aborted, i.e. the function will not be invoked any more.

        Throws:
        java.lang.IllegalArgumentException - if the given delays is zero, negative or exceed the maximum reach (calculated as: delay / tickNanos > Int.MaxValue).

        Note: For scheduling within actors AbstractActorWithTimers should be preferred.

      • scheduleWithFixedDelay

        Cancellable scheduleWithFixedDelay​(scala.concurrent.duration.FiniteDuration initialDelay,
                                           scala.concurrent.duration.FiniteDuration delay,
                                           ActorRef receiver,
                                           java.lang.Object message,
                                           scala.concurrent.ExecutionContext executor,
                                           ActorRef sender)
        Scala API: Schedules a message to be sent repeatedly with an initial delay and a fixed delay between messages. E.g. if you would like a message to be sent immediately and thereafter every 500ms you would set delay=Duration.Zero and interval=Duration(500, TimeUnit.MILLISECONDS).

        It will not compensate the delay between messages if scheduling is delayed longer than specified for some reason. The delay between sending of subsequent messages will always be (at least) the given delay.

        In the long run, the frequency of messages will generally be slightly lower than the reciprocal of the specified delay.

        Note: For scheduling within actors with Timers should be preferred.

      • scheduleWithFixedDelay

        Cancellable scheduleWithFixedDelay​(java.time.Duration initialDelay,
                                           java.time.Duration delay,
                                           ActorRef receiver,
                                           java.lang.Object message,
                                           scala.concurrent.ExecutionContext executor,
                                           ActorRef sender)
        Java API: Schedules a message to be sent repeatedly with an initial delay and a fixed delay between messages. E.g. if you would like a message to be sent immediately and thereafter every 500ms you would set delay=Duration.ZERO and interval=Duration.ofMillis(500).

        It will not compensate the delay between messages if scheduling is delayed longer than specified for some reason. The delay between sending of subsequent messages will always be (at least) the given delay.

        In the long run, the frequency of messages will generally be slightly lower than the reciprocal of the specified delay.

        Note: For scheduling within actors AbstractActorWithTimers should be preferred.

      • scheduleAtFixedRate

        Cancellable scheduleAtFixedRate​(scala.concurrent.duration.FiniteDuration initialDelay,
                                        scala.concurrent.duration.FiniteDuration interval,
                                        java.lang.Runnable runnable,
                                        scala.concurrent.ExecutionContext executor)
        Scala API: Schedules a Runnable to be run repeatedly with an initial delay and a frequency. E.g. if you would like the function to be run after 2 seconds and thereafter every 100ms you would set delay=Duration(2, TimeUnit.SECONDS) and interval=Duration(100, TimeUnit.MILLISECONDS).

        It will compensate the delay for a subsequent task if the previous tasks took too long to execute. In such cases, the actual execution interval will differ from the interval passed to the method.

        If the execution of the tasks takes longer than the interval, the subsequent execution will start immediately after the prior one completes (there will be no overlap of executions). This also has the consequence that after long garbage collection pauses or other reasons when the JVM was suspended all "missed" tasks will execute when the process wakes up again.

        In the long run, the frequency of execution will be exactly the reciprocal of the specified interval.

        Warning: scheduleAtFixedRate can result in bursts of scheduled tasks after long garbage collection pauses, which may in worst case cause undesired load on the system. Therefore scheduleWithFixedDelay is often preferred.

        If the Runnable throws an exception the repeated scheduling is aborted, i.e. the function will not be invoked any more.

        Throws:
        java.lang.IllegalArgumentException - if the given delays is zero, negative or exceed the maximum reach (calculated as: delay / tickNanos > Int.MaxValue).

        Note: For scheduling within actors with Timers should be preferred.

      • scheduleAtFixedRate

        Cancellable scheduleAtFixedRate​(java.time.Duration initialDelay,
                                        java.time.Duration interval,
                                        java.lang.Runnable runnable,
                                        scala.concurrent.ExecutionContext executor)
        Java API: Schedules a Runnable to be run repeatedly with an initial delay and a frequency. E.g. if you would like the function to be run after 2 seconds and thereafter every 100ms you would set delay to Duration.ofSeconds(2), and interval to Duration.ofMillis(100).

        It will compensate the delay for a subsequent task if the previous tasks took too long to execute. In such cases, the actual execution interval will differ from the interval passed to the method.

        If the execution of the tasks takes longer than the interval, the subsequent execution will start immediately after the prior one completes (there will be no overlap of executions). This also has the consequence that after long garbage collection pauses or other reasons when the JVM was suspended all "missed" tasks will execute when the process wakes up again.

        In the long run, the frequency of execution will be exactly the reciprocal of the specified interval.

        Warning: scheduleAtFixedRate can result in bursts of scheduled tasks after long garbage collection pauses, which may in worst case cause undesired load on the system. Therefore scheduleWithFixedDelay is often preferred.

        If the Runnable throws an exception the repeated scheduling is aborted, i.e. the function will not be invoked any more.

        Throws:
        java.lang.IllegalArgumentException - if the given delays is zero, negative or exceed the maximum reach (calculated as: delay / tickNanos > Int.MaxValue).

        Note: For scheduling within actors AbstractActorWithTimers should be preferred.

      • scheduleAtFixedRate

        Cancellable scheduleAtFixedRate​(scala.concurrent.duration.FiniteDuration initialDelay,
                                        scala.concurrent.duration.FiniteDuration interval,
                                        ActorRef receiver,
                                        java.lang.Object message,
                                        scala.concurrent.ExecutionContext executor,
                                        ActorRef sender)
        Scala API: Schedules a message to be sent repeatedly with an initial delay and frequency. E.g. if you would like a message to be sent immediately and thereafter every 500ms you would set delay=Duration.Zero and interval=Duration(500, TimeUnit.MILLISECONDS)

        It will compensate the delay for a subsequent message if the sending of previous message was delayed more than specified. In such cases, the actual message interval will differ from the interval passed to the method.

        If the execution is delayed longer than the interval, the subsequent message will be sent immediately after the prior one. This also has the consequence that after long garbage collection pauses or other reasons when the JVM was suspended all "missed" messages will be sent when the process wakes up again.

        In the long run, the frequency of messages will be exactly the reciprocal of the specified interval.

        Warning: scheduleAtFixedRate can result in bursts of scheduled messages after long garbage collection pauses, which may in worst case cause undesired load on the system. Therefore scheduleWithFixedDelay is often preferred.

        Note: For scheduling within actors with Timers should be preferred.

      • scheduleAtFixedRate

        Cancellable scheduleAtFixedRate​(java.time.Duration initialDelay,
                                        java.time.Duration interval,
                                        ActorRef receiver,
                                        java.lang.Object message,
                                        scala.concurrent.ExecutionContext executor,
                                        ActorRef sender)
        Java API: Schedules a message to be sent repeatedly with an initial delay and frequency. E.g. if you would like a message to be sent immediately and thereafter every 500ms you would set delay=Duration.ZERO and interval=Duration.ofMillis(500)

        It will compensate the delay for a subsequent message if the sending of previous message was delayed more than specified. In such cases, the actual message interval will differ from the interval passed to the method.

        If the execution is delayed longer than the interval, the subsequent message will be sent immediately after the prior one. This also has the consequence that after long garbage collection pauses or other reasons when the JVM was suspended all "missed" messages will be sent when the process wakes up again.

        In the long run, the frequency of messages will be exactly the reciprocal of the specified interval.

        Warning: scheduleAtFixedRate can result in bursts of scheduled messages after long garbage collection pauses, which may in worst case cause undesired load on the system. Therefore scheduleWithFixedDelay is often preferred.

        Note: For scheduling within actors AbstractActorWithTimers should be preferred.

      • scheduleWithFixedDelay$default$6

        ActorRef scheduleWithFixedDelay$default$6​(scala.concurrent.duration.FiniteDuration initialDelay,
                                                  scala.concurrent.duration.FiniteDuration delay,
                                                  ActorRef receiver,
                                                  java.lang.Object message)
      • scheduleAtFixedRate$default$6

        ActorRef scheduleAtFixedRate$default$6​(scala.concurrent.duration.FiniteDuration initialDelay,
                                               scala.concurrent.duration.FiniteDuration interval,
                                               ActorRef receiver,
                                               java.lang.Object message)
        Scala API: Schedules a message to be sent repeatedly with an initial delay and frequency. E.g. if you would like a message to be sent immediately and thereafter every 500ms you would set delay=Duration.Zero and interval=Duration(500, TimeUnit.MILLISECONDS)

        It will compensate the delay for a subsequent message if the sending of previous message was delayed more than specified. In such cases, the actual message interval will differ from the interval passed to the method.

        If the execution is delayed longer than the interval, the subsequent message will be sent immediately after the prior one. This also has the consequence that after long garbage collection pauses or other reasons when the JVM was suspended all "missed" messages will be sent when the process wakes up again.

        In the long run, the frequency of messages will be exactly the reciprocal of the specified interval.

        Warning: scheduleAtFixedRate can result in bursts of scheduled messages after long garbage collection pauses, which may in worst case cause undesired load on the system. Therefore scheduleWithFixedDelay is often preferred.

        Note: For scheduling within actors with Timers should be preferred.

      • scheduleOnce

        Cancellable scheduleOnce​(scala.concurrent.duration.FiniteDuration delay,
                                 ActorRef receiver,
                                 java.lang.Object message,
                                 scala.concurrent.ExecutionContext executor,
                                 ActorRef sender)
        Scala API: Schedules a message to be sent once with a delay, i.e. a time period that has to pass before the message is sent.

        Throws:
        java.lang.IllegalArgumentException - if the given delays is zero, negative or exceed the maximum reach (calculated as: delay / tickNanos > Int.MaxValue).

        Note: For scheduling within actors with Timers should be preferred.

      • scheduleOnce

        Cancellable scheduleOnce​(java.time.Duration delay,
                                 ActorRef receiver,
                                 java.lang.Object message,
                                 scala.concurrent.ExecutionContext executor,
                                 ActorRef sender)
        Java API: Schedules a message to be sent once with a delay, i.e. a time period that has to pass before the message is sent.

        Throws:
        java.lang.IllegalArgumentException - if the given delays is zero, negative or exceed the maximum reach (calculated as: delay / tickNanos > Int.MaxValue).

        Note: For scheduling within actors AbstractActorWithTimers should be preferred.

      • scheduleOnce

        Cancellable scheduleOnce​(scala.concurrent.duration.FiniteDuration delay,
                                 scala.Function0<scala.runtime.BoxedUnit> f,
                                 scala.concurrent.ExecutionContext executor)
        Scala API: Schedules a function to be run once with a delay, i.e. a time period that has to pass before the function is run.

        Throws:
        java.lang.IllegalArgumentException - if the given delays is zero, negative or exceed the maximum reach (calculated as: delay / tickNanos > Int.MaxValue).

        Note: For scheduling within actors with Timers should be preferred.

      • scheduleOnce

        Cancellable scheduleOnce​(scala.concurrent.duration.FiniteDuration delay,
                                 java.lang.Runnable runnable,
                                 scala.concurrent.ExecutionContext executor)
        Scala API: Schedules a Runnable to be run once with a delay, i.e. a time period that has to pass before the runnable is executed.

        Throws:
        java.lang.IllegalArgumentException - if the given delays is zero, negative or exceed the maximum reach (calculated as: delay / tickNanos > Int.MaxValue).

        Note: For scheduling within actors with Timers should be preferred.

      • scheduleOnce

        Cancellable scheduleOnce​(java.time.Duration delay,
                                 java.lang.Runnable runnable,
                                 scala.concurrent.ExecutionContext executor)
        Java API: Schedules a Runnable to be run once with a delay, i.e. a time period that has to pass before the runnable is executed.

        Throws:
        java.lang.IllegalArgumentException - if the given delays is zero, negative or exceed the maximum reach (calculated as: delay / tickNanos > Int.MaxValue).

        Note: For scheduling within actors AbstractActorWithTimers should be preferred.

      • scheduleOnce$default$5

        ActorRef scheduleOnce$default$5​(scala.concurrent.duration.FiniteDuration delay,
                                        ActorRef receiver,
                                        java.lang.Object message)
      • maxFrequency

        double maxFrequency()
        The maximum supported task frequency of this scheduler, i.e. the inverse of the minimum time interval between executions of a recurring task, in Hz.