Tin

Learn · The language · 12 of 34

Durations and frequencies

Goal. Use durations and frequencies as real types, and wait or measure time with them.

"Wait 250". Milliseconds? Seconds? Mixing up units is an old bug, and in robot code it's a dangerous one. In Tin, time and rate carry their unit in the type, so the compiler can catch it.

Durations

Write a number followed by us, ms, s, min or h and you get a Duration. Durations add up correctly whatever their units, and print in a readable unit:

durations.tintin run durations.tin
fn main() {
  let tick = 250ms              // a number with a unit is a Duration
  print(tick)
  print(tick + 1s)              // durations add up, whatever the unit
  print(tick * 4)
  print(90s)                    // printed in a readable unit
  print(1.5h)
}
250ms
1.25s
1s
1.5min
1.5h

A bare number has no unit, so it can't be added to a duration. The error suggests the fix:

mix.tintin check mix.tin
fn main() {
  let timeout = 250ms
  print(timeout + 3)            // 3 what? seconds? milliseconds?
}
error: '+' cannot combine Duration and int
 --> mix.tin:3:9
  |
3 |   print(timeout + 3)            // 3 what? seconds? milliseconds?
  |         ^^^^^^^^^^^
  = note: a bare number has no unit: write 3ms or 3s, or `3 * 1ms` to convert a number

Going between numbers and durations

Divide a duration by a duration and you get a plain number: "how many of these fit in that". Multiply a number by a unit and you get a duration.

convert.tintin run convert.tin
fn main() {
  let timeout = 2s
  print(timeout / 1ms)          // Duration / Duration is a plain number: how many ms fit
  print(timeout / 250ms)
  let retries = 3
  print(retries * 500ms)        // a number times a unit is a Duration
}
2000.0
8.0
1.5s

Frequencies

Hz and kHz make a Frequency: how often something happens. One divided by a frequency is the time between ticks, and one divided by a duration is a frequency.

frequency.tintin run frequency.tin
fn main() {
  let rate = 50Hz               // a Frequency
  print(rate)
  print(1 / rate)               // the time between two ticks: a Duration
  print(1 / 20ms)               // and back: a Frequency
  print(2s * rate)              // Duration × Frequency is a plain number of ticks
}
50Hz
20ms
50Hz
100.0

A frequency is not a duration, even though they're closely related:

freq-mix.tintin check freq-mix.tin
fn main() {
  let rate = 135Hz
  sleep(rate)
}
error: expected Duration, found Frequency
 --> freq-mix.tin:3:9
  |
3 |   sleep(rate)
  |         ^^^^
  = note: the period of a frequency is `1 / f`

Waiting and measuring

sleep takes a Duration, and now() returns the time since the program started, also a Duration.

sleep.tintin run sleep.tin
fn main() {
  let start = now()             // time since the program started, a Duration
  sleep(20ms)
  let took = now() - start
  print(took >= 20ms)
}
true

Agents use the same type. In Part 2, task |> within(2s) gives a running task a deadline, and the deadline is a Duration like these.

Tasks

Task 1: Total time

Add up the steps [1.5s, 300ms, 2min, 45s] and print the total.

Checking needs JavaScript; the solution below works without it.

Solution
task-1.solution.tintin run task-1.solution.tin
fn main() {
  let steps = [1.5s, 300ms, 2min, 45s]
  var total = 0s
  for s in steps {
    total += s
  }
  print(total)
}
2.78min

Task 2: Control loops

For a balance loop at 135Hz and a camera at 30Hz, print the time between ticks and how many ticks fit in a minute. Hint: int(floor(x)) turns a float into an int.

Checking needs JavaScript; the solution below works without it.

Solution
task-2.solution.tintin run task-2.solution.tin
type Loop = { name: string, rate: Frequency }

fn main() {
  let loops = [Loop { name: "balance", rate: 135Hz }, Loop { name: "camera", rate: 30Hz }]
  for l in loops {
    print("{l.name}: every {1 / l.rate}, {int(floor(1min * l.rate))} ticks a minute")
  }
}
balance: every 7.407ms, 8100 ticks a minute
camera: every 33.333ms, 1800 ticks a minute

Task 3: Back off

Write backoff(attempt: int): Duration: 100ms for attempt 0, doubling each time, but never more than 1s.

Checking needs JavaScript; the solution below works without it.

Solution
task-3.solution.tintin run task-3.solution.tin
// Waits 100ms, then 200ms, then 400ms ... but never more than 1s.
fn backoff(attempt: int): Duration {
  var wait = 100ms
  for i in 0..attempt {
    wait = wait * 2
  }
  if wait > 1s { 1s } else { wait }
}

fn main() {
  for attempt in 0..6 {
    print("attempt {attempt}: wait {backoff(attempt)}")
  }
}
attempt 0: wait 100ms
attempt 1: wait 200ms
attempt 2: wait 400ms
attempt 3: wait 800ms
attempt 4: wait 1s
attempt 5: wait 1s

Recap

  • 250ms and 2s are durations; 250ms + 3 does not compile.
  • Convert explicitly: n * 1ms.
  • sleep and time measurements take and give durations.

In the reference: Durations