Module swim.concurrent
Package swim.concurrent

Class Clock

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int TICK_COUNT
      Default number of ticks per clock revolution, used by the no-arg Clock() constructor.
      static int TICK_MILLIS
      Default number of milliseconds between clock ticks, used by the no-arg Clock() constructor.

    • Constructor Summary

      Constructors 
      Constructor Description
      Clock()
      Constructs a new Clock with a timer resolution of TICK_MILLIS milliseconds, and a clock period of TICK_COUNT ticks per revolution.
      Clock​(int tickMillis, int tickCount)
      Constructs a new Clock with a timer resolution of tickMillis milliseconds, and a clock period of tickCount ticks per revolution.
      Clock​(ClockDef clockDef)
      Constructs a new Clock with the timer resolution and clock period specified by the given clockDef.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void didFail​(Throwable error)
      Lifecycle callback invoked if the timer thread throws a fatal error.
      protected void didStart()
      Lifecycle callback invoked after the clock thread starts.
      protected void didStop()
      Lifecycle callback invoked after the clock thread stops.
      protected void didTick​(long tick, long waitedMillis)
      Introspection callback invoked after each tick of the clock.
      protected long nanoTime()
      Returns the current time, in nanoseconds, with arbitrary origin.
      protected void runTimer​(TimerFunction timer, Runnable runnable)
      Invokes timer.runTimer(), or arranges for the asynchronous execution of the provided runnable, which will itself invoke timer.runTimer().
      TimerRef setTimer​(long millis, TimerFunction timer)
      Schedules timer to execute after millis milliseconds have elapsed.
      protected void sleep​(long millis)
      Parks the current thread for the specified number of millis.
      void start()
      Ensures that this Clock is up and running, starting up the clock thread if it has not yet been started.
      void stop()
      Ensures that this Clock has been permanently stopped, shutting down the clock thread, if it's currently running.
      long tick()
      Returns the tick sequence number of the lowest clock tick that has yet to finish executing.
      TimerRef timer​(TimerFunction timer)
      Returns an unscheduled TimerRef bound to timer, which can later be used to schedule timer.
      protected void timerDidCancel​(TimerFunction timer)
      Introspection callback invoked after a timer has been explicitly cancelled; not invoked when a timer is implicitly cancelled, such as when rescheduling an already scheduled timer.
      protected void timerDidFail​(TimerFunction timer, Throwable error)
      Introspection callback invoked after a timer execution fails by throwing an error.
      protected void timerDidRun​(TimerFunction timer)
      Introspection callback invoked after a timer executes nominally.
      protected void timerWillRun​(TimerFunction timer)
      Introspection callback invoked before a timer is executed.
      protected void timerWillSchedule​(TimerFunction timer, long millis)
      Introspection callback invoked before a timer is scheduled for execution with a delay of millis milliseconds.
      protected void willStart()
      Lifecycle callback invoked before the clock thread starts.
      protected void willStop()
      Lifecycle callback invoked before the clock thread stops.

    • Field Detail

      • TICK_MILLIS

        public static final int TICK_MILLIS
        Default number of milliseconds between clock ticks, used by the no-arg Clock() constructor. Defaults to the value of the swim.clock.tick.millis system property, if defined; otherwise defaults to 100 milliseconds.

      • TICK_COUNT

        public static final int TICK_COUNT
        Default number of ticks per clock revolution, used by the no-arg Clock() constructor. Defaults to the value of the swim.clock.tick.count system property, if defined; otherwise defaults to 512 clock ticks per revolution.

    • Constructor Detail

      • Clock

        public Clock​(int tickMillis,
             int tickCount)
        Constructs a new Clock with a timer resolution of tickMillis milliseconds, and a clock period of tickCount ticks per revolution.

      • Clock

        public Clock​(ClockDef clockDef)
        Constructs a new Clock with the timer resolution and clock period specified by the given clockDef.

      • Clock

        public Clock()
        Constructs a new Clock with a timer resolution of TICK_MILLIS milliseconds, and a clock period of TICK_COUNT ticks per revolution.

    • Method Detail

      • tick

        public final long tick()
        Returns the tick sequence number of the lowest clock tick that has yet to finish executing.

      • start

        public final void start()
        Ensures that this Clock is up and running, starting up the clock thread if it has not yet been started.
        Throws:
        ScheduleException - if this Clock has been stopped.

      • stop

        public final void stop()
        Ensures that this Clock has been permanently stopped, shutting down the clock thread, if it's currently running. Upon return, this Clock is guaranteed to be in the stopped state.

      • timer

        public TimerRef timer​(TimerFunction timer)
        Description copied from interface: Schedule
        Returns an unscheduled TimerRef bound to timer, which can later be used to schedule timer.
        Specified by:
        timer in interface Schedule

      • setTimer

        public TimerRef setTimer​(long millis,
                         TimerFunction timer)
        Description copied from interface: Schedule
        Schedules timer to execute after millis milliseconds have elapsed. Returns a TimerRef that can be used to check the status of, reschedule, and cancel timer.
        Specified by:
        setTimer in interface Schedule

      • willStart

        protected void willStart()
        Lifecycle callback invoked before the clock thread starts.

      • didStart

        protected void didStart()
        Lifecycle callback invoked after the clock thread starts.

      • didTick

        protected void didTick​(long tick,
                       long waitedMillis)
        Introspection callback invoked after each tick of the clock. tick is the sequence number of the tick that was executed; waitedMillis is the number of milliseconds the clock thread slept before executing the tick. If waitedMillis is negative, then the clock thread didn't start executing the tick until -waitedMillis milliseconds after the scheduled tick deadline.

      • willStop

        protected void willStop()
        Lifecycle callback invoked before the clock thread stops.

      • didStop

        protected void didStop()
        Lifecycle callback invoked after the clock thread stops.

      • didFail

        protected void didFail​(Throwable error)
        Lifecycle callback invoked if the timer thread throws a fatal error. The clock thread will stop after invoking didFail.

      • timerWillSchedule

        protected void timerWillSchedule​(TimerFunction timer,
                                 long millis)
        Introspection callback invoked before a timer is scheduled for execution with a delay of millis milliseconds.

      • timerDidCancel

        protected void timerDidCancel​(TimerFunction timer)
        Introspection callback invoked after a timer has been explicitly cancelled; not invoked when a timer is implicitly cancelled, such as when rescheduling an already scheduled timer.

      • timerWillRun

        protected void timerWillRun​(TimerFunction timer)
        Introspection callback invoked before a timer is executed.

      • runTimer

        protected void runTimer​(TimerFunction timer,
                        Runnable runnable)
        Invokes timer.runTimer(), or arranges for the asynchronous execution of the provided runnable, which will itself invoke timer.runTimer().

      • timerDidRun

        protected void timerDidRun​(TimerFunction timer)
        Introspection callback invoked after a timer executes nominally.

      • timerDidFail

        protected void timerDidFail​(TimerFunction timer,
                            Throwable error)
        Introspection callback invoked after a timer execution fails by throwing an error.

      • nanoTime

        protected long nanoTime()
        Returns the current time, in nanoseconds, with arbitrary origin. Used by the clock thread to determine the current time. Defaults to System.nanoTime(). Can be overridden to substitute an alternative time source.

      • sleep

        protected void sleep​(long millis)
              throws InterruptedException
        Parks the current thread for the specified number of millis. Used by the clock thread to wait for the next clock tick. Defaults to Thread.sleep(long). Can be overridden to substitute an alternative wait mechanism.
        Throws:
        InterruptedException