cc-libs/docs/adrs/adr-0002-use-eventloop-for-async-code.md

ADR 0002: Use Eventloop For Async Code

Status

Accepted

Date

2026-06-07

Context

ComputerCraft is event-driven. Direct os.pullEvent loops are easy to write, but they are hard to compose when multiple things need to happen at the same time.

This matters for servers, network listeners, timers, peripheral events, and future UI code. UI code especially will need to handle input, redraws, network replies, and timers together.

Decision

New async code should use /apis/eventloop.

Event handlers, timers, server listeners, and future UI behavior should compose through the event loop instead of each feature owning its own blocking event loop.

Consequences

• Prefer eventloop.register, setTimeout, onStart, onStop, and startLoop for async behavior.
• APIs that listen for events should accept an existing event loop as a constructor argument, the way /apis/net already takes one. Do not create a private loop inside a module.
• Direct os.pullEvent loops should be rare and justified.
• Existing code can stay as-is for now, but future async, server, and UI code should move toward eventloop composition.