Package com.fishlib.io.sched

Class JobScheduler

java.lang.Object
com.fishlib.io.sched.JobScheduler
All Implemented Interfaces:
com.fishlib.io.sched.Scheduler
Direct Known Subclasses:
ConnectionScheduler
public class JobScheduler extends Object implements com.fishlib.io.sched.Scheduler
Yet Another implementation of the Scheduler interface -- the best one yet.

This class provides a singleton wrapper for scheduling invocations of multiple Job instances from a single thread. Job are scheduled in accordance with an interest set on a java.nio.Channel, deadline based time scheduling, and/or custom criteria defined by the Jobs' implementation of the ready() method.

Jobs are instantiated by the application and made known to the scheduler by one of the installJob() methods. A previously installed job can be removed from the scheduler with the cancelJob() method. The installJob() and cancelJob() methods are thread-safe. It is allowed to call installJob() on a job that is already installed, or cancelJob() on a job that is not current in the scheduler. In the former case, the channel and/or deadline will be updated accordingly; in the latter, the call will be ignored.

Once the job is installed, the scheduler promises to call exactly one of its invoke(), timedOut() or cancelled() methods exactly once. The invoke() method will be called only if the job was (last) installed with a channel and non-zero interest set. The timedOut() method can be called for any job, since all jobs have an associated deadline (although the timeout value can be set to Integer.MAX_VALUE to make if effectively infinite). The cancelled() method is called only if the job is removed by a cancelJob() call before either the channe is ready or the deadline expires.

After the job is called back, the scheduler forgets about the job completely, unless the application installs it again. That is, from the scheduler's point of view *all* jobs are one-shots. This design is based on the observation that it is easier to reschedule jobs on every invocation in the style of a tail-recursive loop, as opposed to maintaining persistent state in the scheduler.

The application must drive the scheduler by calling the work() method in a loop. The work() method is *not* thread-safe; the application must either call it from a single thread or synchronize calls accordingly.

Forked from com.fishlib.io.sched.YASchedulerImpl.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    JobScheduler.Statistics
    Statistics reporting struct.

    Nested classes/interfaces inherited from interface com.fishlib.io.sched.Scheduler

    com.fishlib.io.sched.Scheduler.ExecutorAdaptor, com.fishlib.io.sched.Scheduler.Null

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected final com.fishlib.io.logger.Logger
    log
    the logger
    protected final String
    name
    the scheduler name, for debug and stats output

  • Constructor Summary

    Constructors
    Constructor
    Description
    JobScheduler(String name, Selector selector, com.fishlib.io.logger.Logger log)
     
    JobScheduler(String name, Selector selector, com.fishlib.io.logger.Logger log, JobScheduler.Statistics statistics)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    cancelJob(com.fishlib.io.sched.Job job)
    Cancel a job's selection key with the scheduler.
    void
    close()
    Shuts down the scheduler, calling close() on the underlying Selector instance.
    long
    currentTimeMillis()
    Return the scheduler's idea of the current time.
    protected void
    delegatedClose()
    Allow derived implementations to do additional closing work.
    void
    installJob(com.fishlib.io.sched.Job job, long deadline)
    Install a job with only an associated deadline (removing any channel association)
    void
    installJob(com.fishlib.io.sched.Job job, long deadline, SelectableChannel channel, int interest)
    Install a job in association with a channel and an interest set.
    boolean
    isClosed()
    Return true if the scheduler is closed, or in the process of closing.
    Set<com.fishlib.io.sched.Job>
    junitGetAllJobs()
    return the set of all jobs known to the scheduler, in whatever state
    ArrayList<SelectionKey>
    junitGetAllKeys()
    Return the selection keys currently known to the scheduler.
    Map<SelectableChannel,com.fishlib.io.sched.Job>
    junitGetChannelsAndJobs()
    Return a map containing all channels and the jobs to which they are associated.
    ArrayList<SelectionKey>
    junitGetReadyKeys()
    Return the selection keys currently known to the scheduler.
    Selector
    junitGetSelector()
     
    ArrayList<com.fishlib.io.sched.Job>
    junitGetTimeoutQueue()
    Return the contents of the timeout queue, in deadline order
    boolean
    junitTestTimeoutQueueInvariant()
    Return true if the timeout queue invariant holds.
    boolean
    work(long timeout, com.fishlib.base.Procedure.Nullary handoff)
    Wait for jobs to become ready, then invoke() them all.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • name

      protected final String name
      the scheduler name, for debug and stats output

    • log

      protected final com.fishlib.io.logger.Logger log
      the logger

  • Constructor Details

    • JobScheduler

      public JobScheduler(@NotNull String name, @NotNull Selector selector, @NotNull com.fishlib.io.logger.Logger log)

    • JobScheduler

      public JobScheduler(@NotNull String name, @NotNull Selector selector, @NotNull com.fishlib.io.logger.Logger log, @NotNull JobScheduler.Statistics statistics)

  • Method Details

    • currentTimeMillis

      public long currentTimeMillis()
      Return the scheduler's idea of the current time.
      Specified by:
      currentTimeMillis in interface com.fishlib.io.sched.Scheduler

    • installJob

      public void installJob(com.fishlib.io.sched.Job job, long deadline, SelectableChannel channel, int interest)
      Install a job in association with a channel and an interest set.
      Specified by:
      installJob in interface com.fishlib.io.sched.Scheduler

    • installJob

      public void installJob(com.fishlib.io.sched.Job job, long deadline)
      Install a job with only an associated deadline (removing any channel association)
      Specified by:
      installJob in interface com.fishlib.io.sched.Scheduler

    • cancelJob

      public void cancelJob(com.fishlib.io.sched.Job job)
      Cancel a job's selection key with the scheduler.
      Specified by:
      cancelJob in interface com.fishlib.io.sched.Scheduler
      Parameters:
      job - the job to be cancelled.

    • work

      public boolean work(long timeout, com.fishlib.base.Procedure.Nullary handoff)
      Wait for jobs to become ready, then invoke() them all. This method will form the core of the main loop of a scheduler-driven application. The method first waits until:

      -- the given timeout expires, -- the earliest job-specific timeout expires, or -- one or more jobs becomes ready

      Note that this method is not synchronized. The application must ensure that it is never called concurrently by more than one thread.

      Specified by:
      work in interface com.fishlib.io.sched.Scheduler
      Returns:
      true, if some work was done.

    • delegatedClose

      protected void delegatedClose()
      Allow derived implementations to do additional closing work. Will be called from close() only if closing work is done in this implementation.

    • close

      public void close()
      Shuts down the scheduler, calling close() on the underlying Selector instance.
      Specified by:
      close in interface com.fishlib.io.sched.Scheduler

    • isClosed

      public boolean isClosed()
      Return true if the scheduler is closed, or in the process of closing.
      Specified by:
      isClosed in interface com.fishlib.io.sched.Scheduler

    • junitGetSelector

      public Selector junitGetSelector()
      Specified by:
      junitGetSelector in interface com.fishlib.io.sched.Scheduler

    • junitGetAllJobs

      public Set<com.fishlib.io.sched.Job> junitGetAllJobs()
      return the set of all jobs known to the scheduler, in whatever state
      Specified by:
      junitGetAllJobs in interface com.fishlib.io.sched.Scheduler

    • junitGetTimeoutQueue

      public ArrayList<com.fishlib.io.sched.Job> junitGetTimeoutQueue()
      Return the contents of the timeout queue, in deadline order
      Specified by:
      junitGetTimeoutQueue in interface com.fishlib.io.sched.Scheduler
      Returns:
      the jobs in the timeout queue

    • junitGetAllKeys

      public ArrayList<SelectionKey> junitGetAllKeys()
      Return the selection keys currently known to the scheduler.
      Specified by:
      junitGetAllKeys in interface com.fishlib.io.sched.Scheduler

    • junitGetReadyKeys

      public ArrayList<SelectionKey> junitGetReadyKeys()
      Return the selection keys currently known to the scheduler.
      Specified by:
      junitGetReadyKeys in interface com.fishlib.io.sched.Scheduler

    • junitGetChannelsAndJobs

      public Map<SelectableChannel,com.fishlib.io.sched.Job> junitGetChannelsAndJobs()
      Return a map containing all channels and the jobs to which they are associated.
      Specified by:
      junitGetChannelsAndJobs in interface com.fishlib.io.sched.Scheduler

    • junitTestTimeoutQueueInvariant

      public boolean junitTestTimeoutQueueInvariant()
      Return true if the timeout queue invariant holds.
      Specified by:
      junitTestTimeoutQueueInvariant in interface com.fishlib.io.sched.Scheduler