Chapter 08Timers

In this section we discuss d3-timer.

We may wish to have a function that is called repeatedly, every X seconds, or after a certain amount of time. For these situations, D3.js provides d3-timer.

d3-timer is not included in https://d3js.org/d3.v5.min.js, so it has to be loaded separately:

 <script src="https://d3js.org/d3-timer.v1.min.js">

d3.now

D3.js provides d3.now to get the amount of time a page has been loaded. This time is in milliseconds and is useful if we want an event to trigger at a specific time (such as 5 seconds after the page loads). Internally, it uses performance.now to check the time elapsed, however note that some browsers randomize this timestamp and it is not 100% accurate. If performance.now is not available, d3.now uses Date.now instead.

d3.now() - Returns performance.now if available, or Date.now if not.

d3.timer

d3.timer(callback[, delay[, time]]) - Creates a new timer that calls callback repeatedly. Can pass in a delay and time that will start the timer after the delay in milliseconds after the time specified. time and delay defaults to d3.now() and 0, receptively. The callback is passed the elapsed time from when the timeout was declared and when the callback is invoked.

In Figure 1 we have a function printTime which displays in a div the string passed in. We also have a d3.timer with the callback function being set to printTime. d3.timer calls printTime repeatedly. Each time printTime is called, d3.timer passes in the time elapsed from when that timer was originally declared to when that timer calls printTime that time.

<script>
    function printTime(elapsed){
        d3.select("#demo1").text(Math.round(elapsed) + "ms")
    }
    d3.timer(printTime);
</script>
<div id="demo1"></div>

Figure 1 - A timer set to constantly call printTime, which displays how long the timer has been running.

d3.interval

d3.interval(callback[, delay[, time]]) - Like d3.timer except it runs every delay milliseconds, not constantly. If delay is not set, it is equivalent to timer. The callback is passed the elapsed time.

In Figure 2 we use the printTime function like we did in Figure 1, however now instead of using d3.timer, we use d3.interval to call the function every 100ms.

<script>
    function printTime(elapsed){
        d3.select("#demo2").text(Math.round(elapsed) + "ms")
    }
    d3.interval(printTime, 100);
</script>
<div id="demo2"></div>

Figure 2 - An interval set to call printTime every 100ms, which displays how long the interval has been running.

d3.timeout

d3.timeout(callback[, delay[, time]]) - Like d3.timer, except it only runs once. The callback is passed the elapsed time.

In Figure 3 we use the printTime function like we did in Figure 1, however now instead of using d3.timer, we use d3.timeout to call the function once after 100ms.

<script>
    function printTime(elapsed){
        d3.select("#demo3").text(Math.round(elapsed) + "ms")
    }
    d3.timeout(printTime, 100);
</script>
<div id="demo3"></div>

Figure 3 - An timeout set to call printTime after 100ms, which displays how long it took for the timeout to call printTime.

timer.stop

timer.stop() - Stops the timer from continuing to run, has no effect if a timer is already stopped.

In Figure 4 we use the printTime function and a timer like we did in Figure 1, however now we use timer.stop to stop the timer after 250ms by also using d3.timeout.

<script>
    function printTime(elapsed){
        d3.select("#demo4").text(Math.round(elapsed) + "ms")
    }
    timer = d3.timer(printTime);
    d3.timeout(() => timer.stop(), 250);
</script>
<div id="demo4"></div>

Figure 4 - A timer set to constantly call printTime, such as in Figure 1. The timer is then stopped after 250 ms using d3.timeout and timer.stop.

timer.restart

timer.restart(callback[, delay[, time]] - Equivalent to calling timer.stop on a timer and creating a new timer with the specified parameters.

<script>
    function printTime(elapsed){
        d3.select("#demo4").text(Math.round(elapsed) + "ms")
    }
    timer = d3.timer(printTime);
    d3.timeout(() => timer.stop(), 250);
</script>
<div id="demo4"></div>

Figure 4 - A timer set to constantly call printTime, such as in Figure 1. The timer is then stopped after 250 ms with a timeout.

d3.timerFlush

d3.timerFlush() - Immediately invokes the callbacks of any zero-delay timers.