Home /Modules/api/LOOP_TIMING_API.md

LOOP_TIMING_API.md

api/sleela/3.0/LOOP_TIMING_API.md · 97 line(s) · markdown

SLeeLa Loop-Timing API (syntax 3.0)

Normative specification: SLEELA.syntax §32 Opcode: OP_SLEEP (ISA index 157) — see lib/vm/InstructionSet.sleela and the generated vm package page (SLISASleep).

Purpose

The loop-timing API lets a program pace a for, while, or do loop without hand-writing timing code: either a fixed pause per iteration, or a total wall-clock budget spread evenly over a known iteration count. It also exposes a general sleep(ms) built-in usable anywhere.

These are the first statement-level, behavioral annotations in SLeeLa. Every other annotation (@scope, @area, @next, @modium, …) is declaration-level metadata that changes nothing at runtime; @loopDelay and @loopBudget attach to a loop statement and insert a real pause into its execution.

Annotations

AnnotationFormMeaning
@loopDelay@loopDelay(<N>)sleep N milliseconds per iteration (bare number = ms)
@loopDelay@loopDelay(ms = <N>)sleep N milliseconds per iteration
@loopDelay@loopDelay(seconds = <N>)sleep N seconds per iteration
@loopBudget@loopBudget(seconds = <T>, iterations = <K>)spread K iterations over T seconds → (T*1000)/K ms each
@loopBudget@loopBudget(ms = <T>, iterations = <K>)spread K iterations over T ms → T/K ms each

Placement

The annotation sits on its own line immediately before the loop keyword it governs. It is a parse error to place it before anything other than for, while, or do.

@loopDelay(ms = 250)
while (i < n) { ... }

@loopBudget(seconds = 10, iterations = 1000)
for (int i = 0; i < 1000; i = i + 1) { ... }

Semantics

The sleep built-in

sleep(<milliseconds>);   // block the current thread; 0 or negative is a no-op

sleep(ms) takes one integer argument and returns no value. It is callable anywhere, not only in loops. Both the annotations and this built-in lower to the same opcode, OP_SLEEP, which pops an integer millisecond count and blocks the current thread via the portable sltime_sleep_millis() time primitive (POSIX nanosleep, Windows Sleep).

Worked example

A runnable reference lives at examples/loop-timing-annotation-demo.sleela:

#sleela 3.0
class LoopTimingDemo {
    void main() {
        int i = 0;
        @loopDelay(ms = 200)
        while (i < 3) { print("tick " + i); i = i + 1; }

        @loopBudget(ms = 900, iterations = 3)
        for (int k = 0; k < 3; k = k + 1) { print("budget " + k); }

        sleep(250);
        print("done");
    }
}

Run it:

sleela run examples/loop-timing-annotation-demo.sleela

Safety

sleep and the loop-timing annotations only pause the current thread; they grant no capability, perform no I/O, and do not bypass the memory manager, security supervisor, or any routing policy. A delay is wall-clock pacing only.