ARCHIVED from builddistributedsystem.com on 2026-04-28 — URL: https://builddistributedsystem.com/tracks/timekeeper/tasks/task-4-1-1-clock-read
TASK

Implementation

System clocks can go backward due to NTP adjustments. Your task is to read the clock repeatedly and detect backward jumps.

Implement a clock_sample handler that reads the clock N times:

Request:  {"type": "clock_sample", "msg_id": 1, "count": 100, "offset_ms": 0}
Response: {"type": "clock_sample_ok", "in_reply_to": 1, "samples": 100, "backward_jumps": 0, "max_delta_us": 15, "min_delta_us": 1}

Also implement simulate_ntp to inject a backward offset:

Request:  {"type": "simulate_ntp", "msg_id": 2, "offset_ms": -50}
Response: {"type": "simulate_ntp_ok", "in_reply_to": 2}

Sample Test Cases

Clock sample returns statsTimeout: 5000ms
Input
{"src":"c0","dest":"n1","body":{"type":"init","msg_id":1,"node_id":"n1","node_ids":["n1"]}}
{"src":"c1","dest":"n1","body":{"type":"clock_sample","msg_id":2,"count":10}}
Expected Output
{"src": "n1", "dest": "c0", "body": {"type": "init_ok", "in_reply_to": 1, "msg_id": 0}}
Simulate NTP responds okTimeout: 5000ms
Input
{"src":"c0","dest":"n1","body":{"type":"init","msg_id":1,"node_id":"n1","node_ids":["n1"]}}
{"src":"c1","dest":"n1","body":{"type":"simulate_ntp","msg_id":2,"offset_ms":-50}}
Expected Output
{"src": "n1", "dest": "c0", "body": {"type": "init_ok", "in_reply_to": 1, "msg_id": 0}}
{"src": "n1", "dest": "c1", "body": {"type": "simulate_ntp_ok", "in_reply_to": 2, "msg_id": 1}}

Hints

Hint 1
Use time.time() for wall clock and time.monotonic() for monotonic clock
Hint 2
Compare consecutive readings to detect backward jumps
Hint 3
NTP adjustments can cause the wall clock to jump backward
Hint 4
Track minimum and maximum deltas between readings
Hint 5
Store readings in a buffer for analysis
OVERVIEW

Theoretical Hub

Concept overview coming soon

Key Concepts

system clockclock monotonicityNTPbackward jump
main.py
python
Read System Clock and Detect Backward Jumps - The Timekeeper | Build Distributed Systems