Package com.hazelcast.scheduledexecutor

Interface IScheduledExecutorService

  • All Superinterfaces:
    DistributedObject
    public interface IScheduledExecutorService
extends DistributedObject
    Distributed & durable implementation similar to, but not directly inherited ScheduledExecutorService. IScheduledExecutorService provides similar API to the ScheduledExecutorService with some exceptions but also additional methods like scheduling tasks on a specific member, on a member who is owner of a specific key, executing a tasks on multiple members etc.

    Tasks (Runnable and/or Callable) scheduled on any partition through an IScheduledExecutorService, yield some durability characteristics.

    • When a node goes down (up to durability config), the scheduled task will get re-scheduled on a replica node.
    • In the event of a partition migration, the task will be re-scheduled on the destination node.
    Note: The above characteristics don't apply when scheduled on a Member.

    Upon scheduling, a task acquires a resource handler, see ScheduledTaskHandler. The handler is generated before the actual scheduling of the task on the node, which allows for a way to access the future in an event of a node failure, immediately after scheduling, and also guarantees no duplicates in the cluster by utilising a unique name per task. A name can also be defined by the user by having the Runnable or Callable implement the NamedTask. Alternatively, one can wrap any task using the TaskUtils.named(String, Callable) or TaskUtils.named(String, Runnable) for simplicity.

    One difference of this service in comparison to ScheduledExecutorService is the scheduleAtFixedRate(Runnable, long, long, TimeUnit) which has similar semantic to ScheduledExecutorService.scheduleAtFixedRate(Runnable, long, long, TimeUnit). It guarantees a task won't be executed by multiple threads concurrently. The difference is that this service will skip a scheduled execution if another thread is still running the same task, instead of postponing its execution.

    The other difference is this service does not offer an equivalent of ScheduledExecutorService.scheduleWithFixedDelay(Runnable, long, long, TimeUnit)

    Tasks that are holding state that needs to be also durable across partitions, will need to implement the StatefulTask interface.

    Supports split brain protection SplitBrainProtectionConfig since 3.10 in cluster versions 3.10 and higher.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      <V> java.util.Map<Member,​java.util.List<IScheduledFuture<V>>> getAllScheduledFutures()
      Fetches and returns all scheduled (not disposed yet) futures from all members in the cluster.
      <V> IScheduledFuture<V> getScheduledFuture​(ScheduledTaskHandler handler)
      Creates a new IScheduledFuture from the given handler.
      <V> IScheduledFuture<V> schedule​(java.lang.Runnable command, long delay, java.util.concurrent.TimeUnit unit)
      Creates and executes a one-shot action that becomes enabled after the given delay.
      <V> IScheduledFuture<V> schedule​(java.util.concurrent.Callable<V> command, long delay, java.util.concurrent.TimeUnit unit)
      Creates and executes a one-shot action that becomes enabled after the given delay.
      <V> IScheduledFuture<V> scheduleAtFixedRate​(java.lang.Runnable command, long initialDelay, long period, java.util.concurrent.TimeUnit unit)
      Creates and executes a periodic action that becomes enabled first after the given initial delay, and subsequently with the given period.
      <V> java.util.Map<Member,​IScheduledFuture<V>> scheduleOnAllMembers​(java.lang.Runnable command, long delay, java.util.concurrent.TimeUnit unit)
      Creates and executes a one-shot action that becomes enabled after the given delay on all cluster Members.
      <V> java.util.Map<Member,​IScheduledFuture<V>> scheduleOnAllMembers​(java.util.concurrent.Callable<V> command, long delay, java.util.concurrent.TimeUnit unit)
      Creates and executes a one-shot action that becomes enabled after the given delay on all cluster Members.
      <V> java.util.Map<Member,​IScheduledFuture<V>> scheduleOnAllMembersAtFixedRate​(java.lang.Runnable command, long initialDelay, long period, java.util.concurrent.TimeUnit unit)
      Creates and executes a periodic action that becomes enabled first after the given initial delay, and subsequently with the given period on all cluster Members.
      <V> IScheduledFuture<V> scheduleOnKeyOwner​(java.lang.Runnable command, java.lang.Object key, long delay, java.util.concurrent.TimeUnit unit)
      Creates and executes a one-shot action that becomes enabled after the given delay on the partition owner of the given key.
      <V> IScheduledFuture<V> scheduleOnKeyOwner​(java.util.concurrent.Callable<V> command, java.lang.Object key, long delay, java.util.concurrent.TimeUnit unit)
      Creates and executes a one-shot action that becomes enabled after the given delay on the partition owner of the given key.
      <V> IScheduledFuture<V> scheduleOnKeyOwnerAtFixedRate​(java.lang.Runnable command, java.lang.Object key, long initialDelay, long period, java.util.concurrent.TimeUnit unit)
      Creates and executes a periodic action that becomes enabled first after the given initial delay, and subsequently with the given period on the partition owner of the given key.
      <V> IScheduledFuture<V> scheduleOnMember​(java.lang.Runnable command, Member member, long delay, java.util.concurrent.TimeUnit unit)
      Creates and executes a one-shot action that becomes enabled after the given delay at the given Member.
      <V> IScheduledFuture<V> scheduleOnMember​(java.util.concurrent.Callable<V> command, Member member, long delay, java.util.concurrent.TimeUnit unit)
      Creates and executes a one-shot action that becomes enabled after the given delay at the given Member.
      <V> IScheduledFuture<V> scheduleOnMemberAtFixedRate​(java.lang.Runnable command, Member member, long initialDelay, long period, java.util.concurrent.TimeUnit unit)
      Creates and executes a periodic action that becomes enabled first after the given initial delay, and subsequently with the given period at the given Member.
      <V> java.util.Map<Member,​IScheduledFuture<V>> scheduleOnMembers​(java.lang.Runnable command, java.util.Collection<Member> members, long delay, java.util.concurrent.TimeUnit unit)
      Creates and executes a one-shot action that becomes enabled after the given delay on all Members given.
      <V> java.util.Map<Member,​IScheduledFuture<V>> scheduleOnMembers​(java.util.concurrent.Callable<V> command, java.util.Collection<Member> members, long delay, java.util.concurrent.TimeUnit unit)
      Creates and executes a one-shot action that becomes enabled after the given delay on all Members given.
      <V> java.util.Map<Member,​IScheduledFuture<V>> scheduleOnMembersAtFixedRate​(java.lang.Runnable command, java.util.Collection<Member> members, long initialDelay, long period, java.util.concurrent.TimeUnit unit)
      Creates and executes a periodic action that becomes enabled first after the given initial delay, and subsequently with the given period on all Members given.
      void shutdown()
      Initiates an orderly shutdown in which previously submitted tasks are executed, but no new tasks will be accepted.

    • Method Detail

      • schedule

        @Nonnull
<V> IScheduledFuture<V> schedule​(@Nonnull
                                 java.lang.Runnable command,
                                 long delay,
                                 @Nonnull
                                 java.util.concurrent.TimeUnit unit)
        Creates and executes a one-shot action that becomes enabled after the given delay.
        Type Parameters:
        V - the result type of the returned ScheduledFuture
        Parameters:
        command - the task to execute
        delay - the time from now to delay execution
        unit - the time unit of the delay parameter
        Returns:
        a ScheduledFuture representing pending completion of the task and whose get() method will return null upon completion
        Throws:
        java.util.concurrent.RejectedExecutionException - if the task cannot be scheduled for execution
        java.lang.NullPointerException - if command is null

      • schedule

        @Nonnull
<V> IScheduledFuture<V> schedule​(@Nonnull
                                 java.util.concurrent.Callable<V> command,
                                 long delay,
                                 @Nonnull
                                 java.util.concurrent.TimeUnit unit)
        Creates and executes a one-shot action that becomes enabled after the given delay.
        Type Parameters:
        V - the return type of callable tasks
        Parameters:
        command - the task to execute
        delay - the time from now to delay execution
        unit - the time unit of the delay parameter
        Returns:
        a ScheduledFuture representing pending completion of the task and whose get() method will return null upon completion
        Throws:
        java.util.concurrent.RejectedExecutionException - if the task cannot be scheduled for execution
        java.lang.NullPointerException - if command is null

      • scheduleAtFixedRate

        @Nonnull
<V> IScheduledFuture<V> scheduleAtFixedRate​(@Nonnull
                                            java.lang.Runnable command,
                                            long initialDelay,
                                            long period,
                                            @Nonnull
                                            java.util.concurrent.TimeUnit unit)
        Creates and executes a periodic action that becomes enabled first after the given initial delay, and subsequently with the given period. Executions will commence after initialDelay then initialDelay+period, then initialDelay + 2 * period, and so on. If any execution of this task takes longer than its period, then subsequent execution will be skipped. If any execution of the task encounters an exception, subsequent executions are suppressed. Otherwise, the task will only terminate via cancellation or termination of the executor.
        Type Parameters:
        V - the result type of the returned ScheduledFuture
        Parameters:
        command - the task to execute
        initialDelay - the time to delay first execution
        period - the period between successive executions
        unit - the time unit of the initialDelay and period parameters
        Returns:
        a ScheduledFuture representing pending completion of the task, and whose get() method will throw an exception upon cancellation
        Throws:
        java.util.concurrent.RejectedExecutionException - if the task cannot be scheduled for execution
        java.lang.NullPointerException - if command is null

      • scheduleOnMember

        @Nonnull
<V> IScheduledFuture<V> scheduleOnMember​(@Nonnull
                                         java.lang.Runnable command,
                                         @Nonnull
                                         Member member,
                                         long delay,
                                         @Nonnull
                                         java.util.concurrent.TimeUnit unit)
        Creates and executes a one-shot action that becomes enabled after the given delay at the given Member.
        Type Parameters:
        V - the result type of the returned ScheduledFuture
        Parameters:
        command - the task to execute
        member - the member to execute the task
        delay - the time from now to delay execution
        unit - the time unit of the delay parameter
        Returns:
        a ScheduledFuture representing pending completion of the task and whose get() method will return null upon completion
        Throws:
        java.util.concurrent.RejectedExecutionException - if the task cannot be scheduled for execution
        java.lang.NullPointerException - if command is null

      • scheduleOnMember

        @Nonnull
<V> IScheduledFuture<V> scheduleOnMember​(@Nonnull
                                         java.util.concurrent.Callable<V> command,
                                         @Nonnull
                                         Member member,
                                         long delay,
                                         @Nonnull
                                         java.util.concurrent.TimeUnit unit)
        Creates and executes a one-shot action that becomes enabled after the given delay at the given Member.
        Type Parameters:
        V - the return type of callable tasks
        Parameters:
        command - the task to execute
        member - the member to execute the task
        delay - the time from now to delay execution
        unit - the time unit of the delay parameter
        Returns:
        a ScheduledFuture representing pending completion of the task and whose get() method will return null upon completion
        Throws:
        java.util.concurrent.RejectedExecutionException - if the task cannot be scheduled for execution
        java.lang.NullPointerException - if command is null

      • scheduleOnMemberAtFixedRate

        @Nonnull
<V> IScheduledFuture<V> scheduleOnMemberAtFixedRate​(@Nonnull
                                                    java.lang.Runnable command,
                                                    @Nonnull
                                                    Member member,
                                                    long initialDelay,
                                                    long period,
                                                    @Nonnull
                                                    java.util.concurrent.TimeUnit unit)
        Creates and executes a periodic action that becomes enabled first after the given initial delay, and subsequently with the given period at the given Member. Executions will commence after initialDelay then initialDelay+period, then initialDelay + 2 * period, and so on. If any execution of this task takes longer than its period, then subsequent execution will be skipped. If any execution of the task encounters an exception, subsequent executions are suppressed. Otherwise, the task will only terminate via cancellation or termination of the executor.
        Type Parameters:
        V - the result type of the returned ScheduledFuture
        Parameters:
        command - the task to execute
        member - the member to execute the task
        initialDelay - the time to delay first execution
        period - the period between successive executions
        unit - the time unit of the initialDelay and period parameters
        Returns:
        a ScheduledFuture representing pending completion of the task, and whose get() method will throw an exception upon cancellation
        Throws:
        java.util.concurrent.RejectedExecutionException - if the task cannot be scheduled for execution
        java.lang.NullPointerException - if command is null

      • scheduleOnKeyOwner

        @Nonnull
<V> IScheduledFuture<V> scheduleOnKeyOwner​(@Nonnull
                                           java.lang.Runnable command,
                                           @Nonnull
                                           java.lang.Object key,
                                           long delay,
                                           @Nonnull
                                           java.util.concurrent.TimeUnit unit)
        Creates and executes a one-shot action that becomes enabled after the given delay on the partition owner of the given key.
        Type Parameters:
        V - the result type of the returned ScheduledFuture
        Parameters:
        command - the task to execute
        key - the key to identify the partition owner, which will execute the task
        delay - the time from now to delay execution
        unit - the time unit of the delay parameter
        Returns:
        a ScheduledFuture representing pending completion of the task and whose get() method will return null upon completion
        Throws:
        java.util.concurrent.RejectedExecutionException - if the task cannot be scheduled for execution
        java.lang.NullPointerException - if command is null

      • scheduleOnKeyOwner

        @Nonnull
<V> IScheduledFuture<V> scheduleOnKeyOwner​(@Nonnull
                                           java.util.concurrent.Callable<V> command,
                                           @Nonnull
                                           java.lang.Object key,
                                           long delay,
                                           @Nonnull
                                           java.util.concurrent.TimeUnit unit)
        Creates and executes a one-shot action that becomes enabled after the given delay on the partition owner of the given key.
        Type Parameters:
        V - the return type of callable tasks
        Parameters:
        command - the task to execute
        key - the key to identify the partition owner, which will execute the task
        delay - the time from now to delay execution
        unit - the time unit of the delay parameter
        Returns:
        a ScheduledFuture representing pending completion of the task and whose get() method will return null upon completion
        Throws:
        java.util.concurrent.RejectedExecutionException - if the task cannot be scheduled for execution
        java.lang.NullPointerException - if command is null

      • scheduleOnKeyOwnerAtFixedRate

        @Nonnull
<V> IScheduledFuture<V> scheduleOnKeyOwnerAtFixedRate​(@Nonnull
                                                      java.lang.Runnable command,
                                                      @Nonnull
                                                      java.lang.Object key,
                                                      long initialDelay,
                                                      long period,
                                                      @Nonnull
                                                      java.util.concurrent.TimeUnit unit)
        Creates and executes a periodic action that becomes enabled first after the given initial delay, and subsequently with the given period on the partition owner of the given key. Executions will commence after initialDelay then initialDelay+period, then initialDelay + 2 * period, and so on. If any execution of this task takes longer than its period, then subsequent execution will be skipped. If any execution of the task encounters an exception, subsequent executions are suppressed. Otherwise, the task will only terminate via cancellation or termination of the executor.
        Type Parameters:
        V - the result type of the returned ScheduledFuture
        Parameters:
        command - the task to execute
        key - the key to identify the partition owner, which will execute the task
        initialDelay - the time to delay first execution
        period - the period between successive executions
        unit - the time unit of the initialDelay and period parameters
        Returns:
        a ScheduledFuture representing pending completion of the task, and whose get() method will throw an exception upon cancellation
        Throws:
        java.util.concurrent.RejectedExecutionException - if the task cannot be scheduled for execution
        java.lang.NullPointerException - if command is null

      • scheduleOnAllMembers

        @Nonnull
<V> java.util.Map<Member,​IScheduledFuture<V>> scheduleOnAllMembers​(@Nonnull
                                                                         java.lang.Runnable command,
                                                                         long delay,
                                                                         @Nonnull
                                                                         java.util.concurrent.TimeUnit unit)
        Creates and executes a one-shot action that becomes enabled after the given delay on all cluster Members.

        Note: In the event of Member leaving the cluster, for whatever reason, the task is lost. If a new member is added, the task will not get scheduled there automatically.

        Type Parameters:
        V - the result type of the returned ScheduledFuture
        Parameters:
        command - the task to execute
        delay - the time from now to delay execution
        unit - the time unit of the delay parameter
        Returns:
        a ScheduledFuture representing pending completion of the task and whose get() method will return null upon completion
        Throws:
        java.util.concurrent.RejectedExecutionException - if the task cannot be scheduled for execution
        java.lang.NullPointerException - if command is null

      • scheduleOnAllMembers

        @Nonnull
<V> java.util.Map<Member,​IScheduledFuture<V>> scheduleOnAllMembers​(@Nonnull
                                                                         java.util.concurrent.Callable<V> command,
                                                                         long delay,
                                                                         @Nonnull
                                                                         java.util.concurrent.TimeUnit unit)
        Creates and executes a one-shot action that becomes enabled after the given delay on all cluster Members.

        Note: In the event of Member leaving the cluster, for whatever reason, the task is lost. If a new member is added, the task will not get scheduled there automatically.

        Type Parameters:
        V - the return type of callable tasks
        Parameters:
        command - the task to execute
        delay - the time from now to delay execution
        unit - the time unit of the delay parameter
        Returns:
        a ScheduledFuture representing pending completion of the task and whose get() method will return null upon completion
        Throws:
        java.util.concurrent.RejectedExecutionException - if the task cannot be scheduled for execution
        java.lang.NullPointerException - if command is null

      • scheduleOnAllMembersAtFixedRate

        @Nonnull
<V> java.util.Map<Member,​IScheduledFuture<V>> scheduleOnAllMembersAtFixedRate​(@Nonnull
                                                                                    java.lang.Runnable command,
                                                                                    long initialDelay,
                                                                                    long period,
                                                                                    @Nonnull
                                                                                    java.util.concurrent.TimeUnit unit)
        Creates and executes a periodic action that becomes enabled first after the given initial delay, and subsequently with the given period on all cluster Members. Executions will commence after initialDelay then initialDelay+period, then initialDelay + 2 * period, and so on. If any execution of this task takes longer than its period, then subsequent execution will be skipped. If any execution of the task encounters an exception, subsequent executions are suppressed. Otherwise, the task will only terminate via cancellation or termination of the executor.

        Note: In the event of Member leaving the cluster, for whatever reason, the task is lost. If a new member is added, the task will not get scheduled there automatically.

        Type Parameters:
        V - the result type of the returned ScheduledFuture
        Parameters:
        command - the task to execute
        initialDelay - the time to delay first execution
        period - the period between successive executions
        unit - the time unit of the initialDelay and period parameters
        Returns:
        a ScheduledFuture representing pending completion of the task, and whose get() method will throw an exception upon cancellation
        Throws:
        java.util.concurrent.RejectedExecutionException - if the task cannot be scheduled for execution
        java.lang.NullPointerException - if command is null

      • scheduleOnMembers

        @Nonnull
<V> java.util.Map<Member,​IScheduledFuture<V>> scheduleOnMembers​(@Nonnull
                                                                      java.lang.Runnable command,
                                                                      @Nonnull
                                                                      java.util.Collection<Member> members,
                                                                      long delay,
                                                                      @Nonnull
                                                                      java.util.concurrent.TimeUnit unit)
        Creates and executes a one-shot action that becomes enabled after the given delay on all Members given.

        Note: In the event of Member leaving the cluster, for whatever reason, the task is lost.

        Type Parameters:
        V - the result type of the returned ScheduledFuture
        Parameters:
        command - the task to execute
        members - the collections of members - where to execute the task
        delay - the time from now to delay execution
        unit - the time unit of the delay parameter
        Returns:
        a ScheduledFuture representing pending completion of the task and whose get() method will return null upon completion
        Throws:
        java.util.concurrent.RejectedExecutionException - if the task cannot be scheduled for execution
        java.lang.NullPointerException - if command is null

      • scheduleOnMembers

        @Nonnull
<V> java.util.Map<Member,​IScheduledFuture<V>> scheduleOnMembers​(@Nonnull
                                                                      java.util.concurrent.Callable<V> command,
                                                                      @Nonnull
                                                                      java.util.Collection<Member> members,
                                                                      long delay,
                                                                      @Nonnull
                                                                      java.util.concurrent.TimeUnit unit)
        Creates and executes a one-shot action that becomes enabled after the given delay on all Members given.

        Note: In the event of Member leaving the cluster, for whatever reason, the task is lost.

        Type Parameters:
        V - the return type of callable tasks
        Parameters:
        command - the task to execute
        members - the collections of members - where to execute the task
        delay - the time from now to delay execution
        unit - the time unit of the delay parameter
        Returns:
        a ScheduledFuture representing pending completion of the task and whose get() method will return null upon completion
        Throws:
        java.util.concurrent.RejectedExecutionException - if the task cannot be scheduled for execution
        java.lang.NullPointerException - if command is null

      • scheduleOnMembersAtFixedRate

        @Nonnull
<V> java.util.Map<Member,​IScheduledFuture<V>> scheduleOnMembersAtFixedRate​(@Nonnull
                                                                                 java.lang.Runnable command,
                                                                                 @Nonnull
                                                                                 java.util.Collection<Member> members,
                                                                                 long initialDelay,
                                                                                 long period,
                                                                                 @Nonnull
                                                                                 java.util.concurrent.TimeUnit unit)
        Creates and executes a periodic action that becomes enabled first after the given initial delay, and subsequently with the given period on all Members given. Executions will commence after initialDelay then initialDelay+period, then initialDelay + 2 * period, and so on. If any execution of this task takes longer than its period, then subsequent execution will be skipped. If any execution of the task encounters an exception, subsequent executions are suppressed. Otherwise, the task will only terminate via cancellation or termination of the executor.

        Note: In the event of Member leaving the cluster, for whatever reason, the task is lost.

        Type Parameters:
        V - the result type of the returned ScheduledFuture
        Parameters:
        command - the task to execute
        members - the collections of members - where to execute the task
        initialDelay - the time to delay first execution
        period - the period between successive executions
        unit - the time unit of the initialDelay and period parameters
        Returns:
        a ScheduledFuture representing pending completion of the task, and whose get() method will throw an exception upon cancellation
        Throws:
        java.util.concurrent.RejectedExecutionException - if the task cannot be scheduled for execution
        java.lang.NullPointerException - if command is null

      • getScheduledFuture

        @Nonnull
<V> IScheduledFuture<V> getScheduledFuture​(@Nonnull
                                           ScheduledTaskHandler handler)
        Creates a new IScheduledFuture from the given handler. This is useful in case your member node or client from which the original scheduling happened, went down, and now you want to access the ScheduledFuture again.
        Type Parameters:
        V - the result type of the returned ScheduledFuture
        Parameters:
        handler - The handler of the task as found from IScheduledFuture.getHandler()
        Returns:
        A new IScheduledFuture from the given handler.

      • getAllScheduledFutures

        @Nonnull
<V> java.util.Map<Member,​java.util.List<IScheduledFuture<V>>> getAllScheduledFutures()
        Fetches and returns all scheduled (not disposed yet) futures from all members in the cluster. If a member has no running tasks for this scheduler, it wont be included in the returned Map.
        Type Parameters:
        V - the result type of the returned ScheduledFuture
        Returns:
        A Map with Member keys and a List of IScheduledFuture found for this scheduler.

      • shutdown

        void shutdown()
        Initiates an orderly shutdown in which previously submitted tasks are executed, but no new tasks will be accepted. Invocation has no additional effect if already shut down.

        This method does not wait for previously submitted tasks to complete execution.