Scheduling

Copy Markdown View Source

Scheduling is really three questions, and Tempo answers each with a different part of the library:

  1. "When does this recur?" — generate the occurrences of a repeating rule, bounded and zone-correct (sections 1–4).

  2. "When are we free to meet?" — turn busy calendars into open, bookable time with set operations (section 5).

  3. "When can these dependent tasks run?" — order constrained work to a deadline and find the critical path (section 6).

The first question has the sharpest edges — future dates, wall-clock vs UTC, and time zones that change rules out from under you — so it gets the most space. Sections 1–4 each give the principle, the Tempo idiom, and the pitfall to avoid:

  • You can't materialise an infinite stream. Bounded scheduling is a design decision.

  • Wall-clock time is authoritative; UTC is a projection. Tempo stores the user's wall time and derives the UTC instant on demand.

  • "Floating" events vs zoned events — Tempo distinguishes them through what's on the value, not a flag.

  • Future dates survive zone-rule changes — because Tempo never caches a UTC value, re-reading a future event automatically uses the current Tzdata.

Setup — required for every example

Every code example in this guide uses the ~o sigil from Tempo.Sigils. Before running any of them — in iex, a script, or a module — you must bring the sigil into scope:

import Tempo.Sigils

The import adds only sigil_o/2 and sigil_TEMPO/2 to the caller's namespace; no helper functions leak in.

1. Bounded enumeration

An RRULE like FREQ=MONTHLY;BYDAY=2MO ("the second Monday of every month") is infinite — occurrences continue forever. You cannot call Enum.to_list/1 on an infinite sequence.

Tempo splits the two operations: parsing the rule into a recurring interval is cheap and always bounded-free, but materialising it into a concrete %Tempo.IntervalSet{} requires a bound.

recurrence = Tempo.RRule.parse!("FREQ=MONTHLY;BYDAY=2MO", from: ~o"2025-01-01")

# `recurrence` is a %Tempo.Interval{recurrence: :infinity, ...} — not an error.
# Materialising it requires a bound:

{:ok, set} = Tempo.to_interval(recurrence, bound: ~o"2025-07-01")
Tempo.IntervalSet.count(set)
#=> 7

The recurring interval is the recurrence rule; the IntervalSet is its occurrences inside a window. :bound is always supplied at materialisation, never at the rule. Tempo's default member-preserving semantics keep each occurrence as a distinct member of the IntervalSet — which is what you want for scheduling. For the covered-instant form (individual occurrences merged into contiguous spans), pipe through Tempo.IntervalSet.coalesce/1 — useful for free/busy questions but not for "list the events."

For ad-hoc use, Stream.take/2 and Enum.take/2 work directly on the recurring interval — it's enumerable, lazily:

recurrence |> Stream.take(10) |> Enum.to_list()

Pitfall

Forgetting the bound and calling Tempo.to_interval(recurrence):

{:error,
 "Cannot materialise an unbounded recurrence (recurrence: :infinity, no UNTIL). Supply a :bound option — any Tempo value whose upper endpoint limits the expansion."}

Tempo refuses rather than hanging — forgotten bounds are a design error, not a runtime surprise.

2. Wall-clock time is authoritative

When a user schedules "08:00 on 1 March 2030 in Paris", the real scheduling intent is the wall-clock reading on that morning — not a specific UTC instant. If Paris changes its DST rules between now and 2030, the UTC instant should shift; the wall-clock event should not.

Tempo stores exactly what the user wrote:

t = ~o"2030-03-01T08:00:00[Europe/Paris]"
t.time
#=> [year: 2030, month: 3, day: 1, hour: 8, minute: 0, second: 0]

t.extended.zone_id
#=> "Europe/Paris"

No UTC seconds are cached on the struct. When you ask for the UTC projection, Tempo consults Tzdata at the time of the call, and the result reflects whatever zone rules Tzdata currently knows about 2030. Re-run the same call after Tzdata updates and the number may change — that's the correct behaviour for future dates.

Principle

Store what the user said. Compute UTC when you need it. This is the same discipline Apple Calendar and Google Calendar enforce: the canonical form of a future event is wall-clock + zone, not UTC.

Pitfall

Serialising a Tempo value as "the UTC seconds" and rehydrating from that:

# Do NOT do this for future events:
cached_utc = Tempo.Compare.to_utc_seconds(event)
store_in_database(cached_utc)

When Tzdata ships a DST rule change for 2030, your cached number is now wrong — but you've lost the wall-clock information needed to recompute. Serialise the Tempo value itself (Tempo.to_iso8601/1 round-trips faithfully) and project to UTC only at display or comparison time.

3. Floating vs zoned events

Apple Calendar's "floating" events (they call them "All-day" in the UI, but the concept applies to timed events too in iCal RFC 5545) stay at the same wall-clock reading regardless of the viewer's zone — a "6am workout" on holiday is still 6am local.

Tempo distinguishes floating and zoned through presence of the zone tag:

floating = ~o"2030-03-01T08:00:00"
floating.extended
#=> nil

paris = ~o"2030-03-01T08:00:00[Europe/Paris]"
paris.extended.zone_id
#=> "Europe/Paris"

utc = ~o"2030-03-01T08:00:00Z"
utc.shift
#=> [hour: 0]

fixed = ~o"2030-03-01T08:00:00+05:30"
fixed.shift
#=> [hour: 5, minute: 30]
FormMeaning
~o"2030-03-01T08:00:00"Floating — 8am in whatever zone the reader is in
~o"2030-03-01T08:00:00[Europe/Paris]"Zoned — 8am Paris wall time, UTC derived on demand
~o"2030-03-01T08:00:00Z"UTC-anchored — a specific UTC instant, wall times vary by zone
~o"2030-03-01T08:00:00+05:30"Fixed-offset — UTC+05:30 regardless of zone-rule changes

The right choice depends on what the user said:

  • "Morning workout at 6am" when travelling — floating.

  • "Meeting at 2pm Paris" — zoned ([Europe/Paris]).

  • "Server job at 03:00 UTC" — UTC-anchored (Z).

  • "Event at UTC+05:30" (fixed-offset calendar system) — fixed-offset.

Principle

The interpretation of a wall-clock reading is metadata, not an afterthought. Tempo forces you to make that choice at parse time and preserves it through every operation.

4. Future dates survive zone-rule changes

When Paris last moved its DST rules in 1996, any calendar entry stored as a frozen UTC instant for a post-1996 date had to be rewritten. Modern calendars (Google, Apple, Outlook) avoid this by storing wall-clock + zone and deriving UTC on demand — which is exactly what Tempo does.

Concretely: a Paris event stored today for 2030 will be re-evaluated with whatever Tzdata knows about Paris's rules in 2030 at the time of the computation:

event = ~o"2030-03-01T08:00:00[Europe/Paris]"

# Today, Tzdata thinks this is UTC+1 (standard time in March).
Tempo.Compare.to_utc_seconds(event)
#=> 64052726400

# If Tzdata 2028a ships saying France abolished DST in 2027,
# the next call to to_utc_seconds returns a different number
# — the event is "still 8am Paris wall time, but the UTC shifts."

Tempo.Interval.duration/2 likewise re-evaluates each endpoint's UTC projection on every call. Comparisons and set operations do the same. Nothing is frozen.

When to freeze

There are cases where you want the UTC instant frozen — a CI build that must run "at exactly 03:00 UTC on 15 March 2030" regardless of how zones shift. Store those as UTC (~o"2030-03-15T03:00:00Z"). The Z suffix is the explicit promise: "this is a UTC instant, don't recompute."

Principle

Don't cache UTC. Don't cache DST. Tempo doesn't, and the reason you trust this library over rolling your own is exactly this discipline.

5. Free-busy and availability

The recurrence sections generate when things happen. The opposite question — when is nobody busy — is set algebra over those occurrences. Free time is the workday minus the busy periods; mutual free time is the intersection of each person's free time.

work = ~o"2026-06-15T09:00:00/2026-06-15T17:00:00"

alice_busy =
  Tempo.IntervalSet.new!([
    ~o"2026-06-15T10:00:00/2026-06-15T11:00:00",
    ~o"2026-06-15T14:00:00/2026-06-15T15:00:00"
  ])

bob_busy =
  Tempo.IntervalSet.new!([
    ~o"2026-06-15T09:30:00/2026-06-15T10:30:00",
    ~o"2026-06-15T16:00:00/2026-06-15T17:00:00"
  ])

{:ok, alice_free} = Tempo.difference(work, alice_busy)
{:ok, bob_free}   = Tempo.difference(work, bob_busy)
{:ok, mutual}     = Tempo.intersection(alice_free, bob_free)
#=> 09:00–09:30, 11:00–14:00, 15:00–16:00

"Alice's free time is the workday minus her meetings; Bob's is the same. Mutual free time is the intersection of theirs."

Free time gives you the regions where a meeting could go. Turn them into the discrete slots a booking page actually offers with Tempo.IntervalSet.slots/3:

mutual
|> Tempo.IntervalSet.slots(~o"PT1H")    # cut into back-to-back 1-hour slots
|> Tempo.IntervalSet.to_list()
#=> 11:00–12:00, 12:00–13:00, 13:00–14:00, 15:00–16:00

"The bookable hour-long slots are the mutual windows cut into one-hour pieces." The 09:00–09:30 opening is too short to hold an hour, so it drops out. Pass every: ~o"PT30M" to offer a start on every half-hour instead (overlapping slots), or a larger :every to leave gaps between offered times.

This is instant-level set algebra — you are asking about time regions, not preserving individual calendar events — so difference/intersection are the right operators rather than their member-preserving companions. The set operations guide explains that distinction in full; to load real calendars from .ics files instead of inline busy sets, see the free-busy recipe in the cookbook.

6. Dependency scheduling (the critical path)

The sections above schedule recurrences — a rule repeated over a window. A different question is scheduling a plan of dependent tasks: "design takes 2 days, then build (3 days) and docs (1 day) can run, then ship (2 days) needs both — when does each run, and what's due by the deadline?" That's the critical path method, and Tempo.Schedule solves it directly (it's the same Simple Temporal Problem Tempo.Network already solves — tasks are periods, dependencies are boundary relations).

{:ok, plan} =
  Tempo.Schedule.new()
  |> Tempo.Schedule.task(:design, duration: ~o"P2D", start: ~o"2026-06-01")
  |> Tempo.Schedule.task(:build, duration: ~o"P3D", after: :design)
  |> Tempo.Schedule.task(:docs, duration: ~o"P1D", after: :design)
  |> Tempo.Schedule.task(:ship, duration: ~o"P2D", after: [:build, :docs], deadline: ~o"2026-06-08")
  |> Tempo.Schedule.solve()

plan[:ship].start                 #=> ~o"2026Y6M6D"
plan[:docs].critical?             #=> false   (docs has slack)
Tempo.Schedule.critical_path(plan) #=> [:design, :build, :ship]
Tempo.Schedule.span(plan)          #=> the project interval, 06-01 .. 06-08

"Design, then build and docs in parallel, then ship — due the 8th. Ship starts on the 6th; docs has slack and isn't on the critical path; the project runs design → build → ship."

Each task carries a :duration (exact or a {min, max} range) and optional :after dependencies (finish-to-start — a successor starts no earlier than its predecessors finish). Bounds come from :start (a fixed anchor), :earliest, :deadline, or a :within window. solve/1 returns a %Tempo.Schedule.Slot{} per task with its early and late positions; critical? is true when a task has zero slack. An over-tight deadline or a dependency cycle returns {:error, :infeasible}.

What this is not

Scheduling around a busy calendar — "drop this task into the first free gap" — is a disjunctive problem (before or after each existing meeting) that the Simple Temporal Problem can't express. For that, subtract the busy periods to find the free regions (Tempo.difference/2), then cut those regions into fixed-length bookable slots with Tempo.IntervalSet.slots/3 (see set operations and the cookbook). Tempo.Schedule is for dependency scheduling, where constraints compose by conjunction.

Putting it together

A practical scheduling layer built on Tempo looks like:

defmodule Schedule do
  def weekly_meeting(name, %Date{} = date, %Time{} = time, zone) do
    {:ok, datetime} = DateTime.new(date, time, zone)
    # A meeting is a to-the-minute thing, so drop the source's seconds.
    dtstart = Tempo.from_elixir(datetime, resolution: :minute)

    # "Every week from `dtstart`, forever" is just a recurring interval.
    recurrence = Tempo.Interval.new!(from: dtstart, duration: ~o"P1W", recurrence: :infinity)
    %{name: name, recurrence: recurrence}
  end

  def occurrences_in(%{recurrence: recurrence}, from, to) do
    bound = Tempo.Interval.new!(from: from, to: to)
    {:ok, set} = Tempo.to_interval(recurrence, bound: bound)
    Tempo.IntervalSet.to_list(set)
  end
end

retrospective =
  Schedule.weekly_meeting("Retro", ~D[2025-06-01], ~T[14:00:00], "Europe/London")

# Occurrences for Q3:
Schedule.occurrences_in(retrospective, ~o"2025-07-01", ~o"2025-10-01")
# 18 weekly occurrences, each with wall time 14:00 in Europe/London

Tempo.from_elixir/2 converts native Elixir date/time structs. When a value arrives as a Date, Time, NaiveDateTime, or DateTime — from a database row, an API payload, a form — convert it with from_elixir/2 rather than picking its fields apart by hand or re-formatting it to an ISO 8601 string and parsing it back. The time zone carries across faithfully, and the :resolution option lets you say how precise the value really is: a DateTime is second-precise, but a weekly meeting is a to-the-minute thing, so resolution: :minute makes the value — and every occurrence derived from it — a one-minute span rather than a one-second one. (For a value you are assembling from loose components rather than a struct, Tempo.new/1 is the runtime companion to the ~o sigil.)

Store the recurrence as a value — a zoned repeating interval, ~o"R/2025Y6M1DT14H0MZ+1H[Europe/London]/P1W". Materialise into an IntervalSet only when you need concrete occurrences, bounded to the query window. Display by projecting each endpoint's wall time through the viewer's preferred zone. Nothing about the stored value changes when Tzdata does.