summaryrefslogtreecommitdiff
path: root/chapter32/src/main/smp/sys/time
diff options
context:
space:
mode:
Diffstat (limited to 'chapter32/src/main/smp/sys/time')
-rw-r--r--chapter32/src/main/smp/sys/time/DateTime.smp13
-rw-r--r--chapter32/src/main/smp/sys/time/README.md133
-rw-r--r--chapter32/src/main/smp/sys/time/Timers.smp80
3 files changed, 226 insertions, 0 deletions
diff --git a/chapter32/src/main/smp/sys/time/DateTime.smp b/chapter32/src/main/smp/sys/time/DateTime.smp
new file mode 100644
index 00000000..53b6688e
--- /dev/null
+++ b/chapter32/src/main/smp/sys/time/DateTime.smp
@@ -0,0 +1,13 @@
+// Calendar view of an instant. Month/day start at 1; weekday is Sunday=0.
+// year==0 means out of the supported calendar range (years 1 through 9999).
+
+// All values default zero/false
+struct DateTime {
+ int year, month, day;
+ int hour, minute, second, millisecond;
+ int weekday, offsetSeconds;
+ bool daylight;
+};
+
+// Factory in the defining unit, so callers need no forward instance type.
+val empty = { -> new DateTime(); };
diff --git a/chapter32/src/main/smp/sys/time/README.md b/chapter32/src/main/smp/sys/time/README.md
new file mode 100644
index 00000000..602015e9
--- /dev/null
+++ b/chapter32/src/main/smp/sys/time/README.md
@@ -0,0 +1,133 @@
+# Time and single-threaded animation
+
+[Chapter 31](../../../../../../chapter31/README.md#time-library) introduces the library.
+The implementation is in [time.smp](../time.smp), [DateTime.smp](DateTime.smp),
+and [Timers.smp](Timers.smp).
+
+`sys.time` uses bare `i64` values: absolute instants are milliseconds since
+the Unix epoch in UTC; durations are milliseconds. Monotonic readings belong
+to a separate clock domain. Never subtract a wall-clock reading from a
+monotonic deadline.
+
+## Clocks and waits
+
+| Call | Result |
+| --- | --- |
+| `time.now()` | Unix-epoch milliseconds; may jump when the system clock changes. |
+| `time.monotonic()` | Monotonic milliseconds for elapsed time and deadlines. |
+| `time.nanoTime()` | Monotonic nanoseconds, with the clock's available resolution. |
+| `time.sleep(duration_ms)` | Sleep for a nonnegative duration. |
+| `time.sleepUntil(deadline_ms)` | Wait for a monotonic millisecond deadline; returns immediately if past. |
+| `time.remaining(deadline_ms, current_ms)` | Nonnegative difference, saturating on overflow. |
+
+Clock errors return `-1`; sleeps return zero on success or `-1` on error,
+with `sys.libc.errno()` available. Interrupted sleeps resume rather than
+returning early. Wakeup times are approximate, and these calls do not wake a
+suspended laptop. Sleeping blocks the one Simple execution thread; use
+`gfx.wait` when window input must remain responsive.
+
+`seconds(n)`, `minutes(n)`, `hours(n)`, and `days(n)` convert signed counts
+to milliseconds. `toSeconds(ms)`, `toMinutes(ms)`, `toHours(ms)`, and
+`toDays(ms)` truncate toward zero. A duration day is exactly 24 hours,
+independent of daylight saving. `toNanos(ms)` and `fromNanos(ns)` convert
+between millisecond and nanosecond units. Multiplication overflow returns
+`-1`. Constants `SECOND`, `MINUTE`, `HOUR`, and `DAY` are also available,
+defined as `1000`, `60*SECOND`, `60*MINUTE`, and `24*HOUR` respectively.
+`NANOS_PER_MS` is `1000*1000`. Overflow checks use the shared
+`sys.integer.MIN_I64` and `MAX_I64` bounds; `MAX_I32` and `MAX_U32` in that
+module also describe the library's array and timer-ID limits.
+
+## String interpolation
+
+Time formatting is built into the existing string interpolation syntax:
+
+| Format | Example | Named style |
+| --- | --- | --- |
+| `%t(instant)` or `%tF(instant)` | `2026-11-12T00:34:05.123Z` | `time.ISO` |
+| `%tr(instant)` | `12:34am` | `time.CLOCK12` |
+| `%tR(instant)` | `00:34` | `time.CLOCK24` |
+| `%tT(instant)` | `00:34:05` | `time.CLOCK24_SECONDS` |
+| `%tD(instant)` | `12/11/26` | `time.DATE` |
+| `%tM(duration)` | `02:03.456` | `time.ELAPSED` |
+
+For example, `"UTC %tR(sys.time.now())"`. Width and left alignment work as
+for strings: `%30t(instant)` and `%-30t(instant)`. Precision and numeric flags
+are rejected. `%tM` formats a duration, with total minutes rather than wrapping
+at an hour; negative durations keep their sign.
+
+Interpolation uses UTC, making its output stable across machines.
+`time.format(instant, style)` is the equivalent library call;
+`time.formatLocal(instant, style)` uses the system's local zone. Local ISO
+output includes a numeric offset instead of `Z` when nonzero, retaining
+offset seconds for historical zones. Invalid calendar values/styles produce
+`<invalid time>`. The ISO form retains all millisecond bits within the supported
+calendar range; short formats intentionally omit information.
+
+## Calendar values and absolute parsing
+
+`time.utc(instant)` and `time.local(instant)` return a `DateTime` with fields
+`year`, `month`, `day`, `hour`, `minute`, `second`, `millisecond`, `weekday`
+(Sunday = 0), `offsetSeconds` (east of UTC), and `daylight`. A zero year means
+conversion failed. `time.zoneName(instant)` returns the local abbreviation or
+an empty string on error. Local conversion uses the operating system's zone
+rules, including DST at that instant; no time-zone database is downloaded.
+
+`time.makeUTC(year, month, day, hour, minute, second, millisecond)` validates
+and constructs an instant, returning `-1` on invalid fields. `time.valid(...)`,
+`time.leap(year)`, and `time.monthDays(year, month)` support calendar checks.
+Calendar conversion supports Gregorian years 1 through 9999, bounded by
+`time.MIN` and `time.MAX`, and rejects leap seconds.
+
+`time.parse(text)` accepts strict absolute ISO text:
+`YYYY-MM-DDTHH:mm:ss[.SSS]Z` or the same with an explicit `+HH:MM`/`-HH:MM`
+offset (optionally with `:SS`). Fractions have exactly three digits. No relative
+time parsing, implicit local zone, locale-dependent parsing, or named-zone
+conversion is provided. Offsets must have hours 00–23 and minutes/seconds 00–59.
+Invalid text or an out-of-range result returns `-1`. By design, this sentinel
+is indistinguishable from the valid instant `1969-12-31T23:59:59.999Z`;
+formatting and calendar conversion still support that instant.
+
+## Cooperative timers
+
+Create `val timers = new sys.time.Timers();` on the game thread:
+
+Timer IDs are `u32`, with `0` reserved for registration failure or no timer due.
+Deadlines, delays, and periods remain `i64` milliseconds; their parameter,
+field, and local names end in `_ms` to distinguish them from IDs.
+
+| Operation | Meaning |
+| --- | --- |
+| `after(delay_ms)` | Register a one-shot timer; return its positive `u32` ID, or `0`. |
+| `every(period_ms)` | Register a repeating timer; period must be positive. Returns a `u32` ID, or `0`. |
+| `afterAt(current_ms, delay_ms)`, `everyAt(current_ms, period_ms)` | Supply a monotonic reading explicitly, useful for deterministic tests. |
+| `cancel(id)` | Remove a timer; return whether it was present. |
+| `nextDeadline()` | Earliest monotonic deadline, or `-1` if empty. |
+| `poll(current_ms)` | Return the next due `u32` ID, or `0` if none. |
+
+Poll repeatedly to drain due timers. Deadlines order delivery, then registration
+ID breaks ties. Repeating timers advance from their previous deadline, skipping
+missed ticks to the first future deadline rather than drifting or replaying a
+backlog. Deadline overflow rejects registration or cancels a repeating timer.
+IDs are never reused within a collection; registration fails once all nonzero
+`u32` IDs have been issued.
+There are no callbacks or timer threads: the caller handles each returned ID.
+
+`gfx.wait(timeout_ms)` processes events after waiting for input or a timeout:
+zero polls, `-1` waits indefinitely, values below `-1` fail. It returns the same
+`OK`, `CLOSED`, or `ERROR` statuses as `gfx.poll`, and may wake early. Re-read the
+monotonic clock after each wake. This allows one thread to handle timers,
+input, simulation, and drawing without busy waiting.
+
+The [digital and analog clock example](../../../../../docs/examples/Clock.smp) combines these pieces. From
+the repository root, with graphics dependencies already cached:
+
+```sh
+make -C chapter32 clock-example # Build without opening a window.
+make -C chapter32 run-clock # Build the backend and run.
+```
+
+Click the button or press Space to switch between green seven-segment digits
+and an analog dial with smoothly moving hands. Both display system-local time;
+Q/Escape exits. Passing any argument directly to the executable closes it after
+ten frames, switching faces halfway through. Hands are computed from the current
+time, so delayed frames do not create a simulation catch-up backlog.
diff --git a/chapter32/src/main/smp/sys/time/Timers.smp b/chapter32/src/main/smp/sys/time/Timers.smp
new file mode 100644
index 00000000..7cca2e9c
--- /dev/null
+++ b/chapter32/src/main/smp/sys/time/Timers.smp
@@ -0,0 +1,80 @@
+// Cooperative timers. poll returns IDs; callbacks never run on another thread.
+// IDs are u32; 0 means failure or no timer due. Millisecond values use _ms.
+
+// The
+
+
+struct Timers {
+ // Collection of timers (as struct-of-arrays)
+ u32[] !_ids = new u32[8]; // Which timer id for this slot
+ i64[] !_due_ms = new i64[8]; // Monotonic deadline in milliseconds
+ i64[] !_period_ms = new i64[8]; // When does it repeat
+ // Next available timer ID; 0 means all IDs have been used.
+ u32 !_next = 1;
+
+ // Add a new timer
+ { i64 i64 i64 -> u32 } _add = { i64 current_ms, i64 delay_ms, i64 period_ms ->
+ if( current_ms < 0 || delay_ms < 0 || current_ms > sys.integer.MAX_I64-delay_ms || _next == 0 ) return 0;
+ // Ugly linear scan for an available slot
+ int slot = 0;
+ while( slot < _ids# && _ids[slot] != 0 ) slot++;
+ // Double size for lots of timers
+ if( slot == _ids# ) {
+ if( _ids# > sys.integer.MAX_I32/2 ) return 0;
+ val ids = new u32[_ids#*2];
+ val due_ms = new i64[_ids#*2], periods_ms = new i64[_ids#*2];
+ for( int i = 0; i < _ids#; i++ ) { ids[i] = _ids[i]; due_ms[i] = _due_ms[i]; periods_ms[i] = _period_ms[i]; }
+ _ids = ids; _due_ms = due_ms; _period_ms = periods_ms;
+ // Retry against the newly published arrays after growing.
+ return _add(current_ms,delay_ms,period_ms);
+ }
+ // Next available timer id
+ u32 id = _next;
+ _next = id == sys.integer.MAX_U32 ? 0 : id+1;
+ _ids[slot] = id; _due_ms[slot] = current_ms+delay_ms; _period_ms[slot] = period_ms;
+ return id;
+ };
+
+ // Explicit-clock versions make game logic and tests deterministic.
+ { i64 i64 -> u32 } afterAt = { i64 current_ms, i64 delay_ms -> _add(current_ms,delay_ms,0); };
+ { i64 i64 -> u32 } everyAt = { i64 current_ms, i64 period_ms -> period_ms <= 0 ? 0 : _add(current_ms,period_ms,period_ms); };
+ { i64 -> u32 } after = { i64 delay_ms -> afterAt(time.monotonic(),delay_ms ); };
+ { i64 -> u32 } every = { i64 period_ms -> everyAt(time.monotonic(),period_ms); };
+
+ // Remove a timer
+ val cancel = { u32 id ->
+ if( id == 0 ) return false;
+ for( int i = 0; i < _ids#; i++ ) if( _ids[i] == id ) { _ids[i] = 0; return true; }
+ return false;
+ };
+
+ // Earliest absolute monotonic deadline in milliseconds, or -1 when empty.
+ val nextDeadline = { ->
+ i64 next_ms = -1;
+ // Ugly linear scan again, but short
+ for( int i = 0; i < _ids#; i++ )
+ if( _ids[i] != 0 && (next_ms < 0 || _due_ms[i] < next_ms) ) next_ms = _due_ms[i];
+ return next_ms;
+ };
+
+ // Next firing timer.
+
+ // Earliest deadline first; equal deadlines use registration order.
+ // Repeats skip missed ticks and retain their phase, avoiding bursts/drift.
+ { i64 -> u32 } poll = { i64 current_ms ->
+ int slot = -1;
+ for( int i = 0; i < _ids#; i++ )
+ if( _ids[i] != 0 && _due_ms[i] <= current_ms && (slot < 0 || _due_ms[i] < _due_ms[slot] ||
+ (_due_ms[i] == _due_ms[slot] && _ids[i] < _ids[slot])) ) slot = i;
+ if( slot < 0 ) return 0;
+ u32 id = _ids[slot];
+ i64 period_ms = _period_ms[slot];
+ if( period_ms == 0 ) _ids[slot] = 0;
+ else {
+ i64 steps = (current_ms-_due_ms[slot])/period_ms;
+ if( steps >= (sys.integer.MAX_I64-_due_ms[slot])/period_ms ) _ids[slot] = 0;
+ else _due_ms[slot] += (steps+1)*period_ms;
+ }
+ return id;
+ };
+};