Sn Tin

Learn Tin · Part 1: The language · Chapter 12

Durations and frequencies

Units are types: 250ms + 3 does not compile.

"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.

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.

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.

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

What's next

Next: Modules. Split a program across files with import.

In the reference: Durations