Vela Events

⚡ What an event is

An event is a body of code, much like a task or a method. The difference is that the program never calls it. Instead the event is bound to a trigger, and it runs each time the trigger happens. The closest ideas elsewhere are state and signals in React, Svelte and Solid, database triggers, and constructors and destructors. Vela's version is meant to be cheaper than all of them, because the compiler can see every place a trigger can happen.

• Author The program can't call an event by hand.
• Author An event takes no parameters, since nothing calls it and so nothing could pass them.
• Author An event is bound to a trigger and runs whenever the trigger happens: a field or variable changes, a bound value is read, a task or method is called, or one of the special occasions below comes.
• Author Apart from that, events follow the rules of tasks and methods. They can be declared inside a task or inside a shape. In a shape they can be shared (they belong to the shape and reach its shared members) or ordinary members (they happen on each value).
• Author Special events (oninit, ondrop, onchange, onstart, onend) cost nothing unless a program uses them. Vela has no default constructor that always runs.

One problem led to this idea. Shared fields can count how often X.new(…) is called, but not how many values of X exist. A literal skips new, a copy makes a second value without calling anything, and nothing runs when a value goes away. Events on a shape's own life, oninit and ondrop, answer that problem (below).

📍 Where an event can be declared

Open A kind has only shared methods and no fields, so it has nothing to watch for changes. Its events could only be call triggers on its shared methods. It is not settled whether that is worth allowing.

✏️ Changing things: the alters rule

This is the central rule of the design, and it is stricter than the rule for tasks on purpose.

Why events are stricter than tasks

Author A task runs only where the program calls it, so its author knows a call can change things there. An event can run where nobody expects it, in the middle of an unrelated assignment. Writing alters is the author's way of saying "this runs by surprise and changes things", and it tells a reader to be careful around it. Tasks may need the same strictness once Vela has concurrency, when a task can also run at an unexpected time.

Examples of the rule

shape Counter
    shared flex made: int = 0
    shared event counted on init        ; no alters: made is this shape's own shared field
        Counter.made = Counter.made + 1
    fi
fi

shape Audit
    shared flex seen: int = 0
    shared alters event noted on init   ; alters: seen is its own, but Counter.made is another shape's
        Audit.seen = Audit.seen + 1
        Counter.made = Counter.made + 1
    fi
fi

task main()
    flex changes = 0
    flex total = 0
    alters event tally on total         ; alters: changes belongs to main, not to the event
        changes = changes + 1
    fi
    total = 5                           ; tally runs here, and changes becomes 1
fi

shape Player
    hp: int
    shield: int
    alive: bool = true

    ; Directly modifies .shield; indirectly alters .alive (via check_death)
    alters(.shield, .alive) event absorb on .hp when .hp < 50 auto
        .shield = .shield - 10
    fi

    ; Directly modifies .alive
    alters(.alive) event check_death on .shield when .shield <= 0 auto
        .alive = false
    fi
fi

error: event 'absorb' indirectly alters 'Player.alive' (via event 'check_death' on '.shield');
add 'Player.alive' to its alters list: 'alters(.shield, .alive)'

🎯 Triggers

These are the kinds of trigger the author named. The words used for each are in the next section.

1. A field or variable changes

Author The event runs whenever a particular field, or one of a set of fields, changes. This is the "state" of React, but with the compiler knowing every place that can change the field, so nothing has to be tracked while the program runs.

Suggestion It can watch more than one field at a time, on .x, .y. It could also have a condition, on .hp when .hp < 10, which is checked where the change happens, so the event runs only when the condition holds.

2. A value is read

Author A separate trigger runs when a bound value is read rather than changed. A word or modifier marks it, so it can't be mistaken for a change event.

Open Is a read done by the event itself a trigger? It must not be, or the event triggers itself. And may a read event change the value being read? If it may, it becomes a lazy or computed field, which is the property idea from another angle. That is powerful, but it hides work behind what looks like a plain read, and the property idea already had to guard against exactly that.

3. A task or method is called

Author The event runs whenever a task or method is called. It can run before the task starts, or after it finishes. An "after" event may even read what the task sent back.

Suggestion A call event could read the call's arguments by name, read-only, the same way a method reads .this. It takes no parameters, but it can see what was passed. A "before" event should not be able to cancel the call or change its arguments: that would make calls unpredictable, and a program that wants that has a wrapper task for it.

Open Can a program watch a task from another module, or from std? Can it watch a priv task from outside its file? It should not. And does an "after" event run when the task sends a failure (fail)? If it does, it needs a way to tell a result from a failure.

4. The special events of a shape

This is how counting looks with them, the case that led to the idea:

shape Player
    name: text
    shared read alive: int = 0

    shared event born on init
        Player.alive = Player.alive + 1
    fi
    shared event gone on drop
        Player.alive = Player.alive - 1
    fi
fi

5. The program's own events

✍️ A proposed syntax Suggestion

The author has not chosen a syntax. What follows is one proposal, built from words and shapes Vela already uses. It needs one new word, event. The word on introduces the trigger. It is only a keyword in that position, so it could stay usable as a name elsewhere.

[priv] [shared] [alters(<targets>)] event <name> (on <trigger> | before <task> | after <task>) [when <condition>] [auto]
    …
fi

Event Scope, Registration & the auto keyword:

• shared events are globally active for the lifetime of the program.
• Non-shared member events inside a shape require explicit activation per instance via .listen() to avoid unwanted listener overhead on idle instances:
  • player.listen() registers all non-shared member events on that instance.
  • player.listen("on_damage", "on_heal") registers only the specified events.
• The auto keyword: When placed at the end of an in-shape member event declaration (e.g. event on_damage on .hp auto), the event is automatically active on every instance upon construction without requiring .listen(). Using auto on a shared event or outside a shape is a compile-time error.

Spelling the special events as on init rather than oninit keeps them to one pattern: every event is event name on something. Only event becomes a reserved word, and init, drop, change, start and end stay free for programs to use as names. The author's words (oninit, ondrop, and so on) work just as well as reserved words, and are shorter to search for. It is a matter of taste.

Every event has a name. The name is needed to pause it, to name it in an error ("event tally changes changes without alters"), and for Studio to show it where it runs.

A larger example, in a task:

task main()
    flex score = 0
    flex best = 0
    alters(best) event record on score when score > best
        best = score
    fi
    score = 3        ; record runs: best is 3
    score = 1        ; the condition is false: record does not run
    score = 7        ; record runs: best is 7
    show(best)       ; 7
fi

🏎️ Paying only for events that exist

Author No special event runs by default, the way a default constructor would. A trigger starts being watched only once an event for it is registered, in the program or in the shape. When every event for it is stopped, it stops being watched.

A sketch of the C this could produce for the record example above:

int64_t score = 0, best = 0;
score = 3;
if (score > best) { best = score; }   /* record, inlined where score changes */
score = 1;
if (score > best) { best = score; }

⏸️ Pausing and resuming an event

Author A program needs a way to stop an event at some point, and perhaps to start it again. When every event on a trigger is stopped, the trigger stops being watched.

Suggestion Treat an event's name like a value with a few built-in members, the same way a slice has .len and .add:

record.pause()      ; stop running it
record.resume()     ; run it again
record.paused       ; true or false

That needs no new keyword. (stop is already one, for loops, and reusing it for events would read oddly inside a loop.) An event nobody ever pauses doesn't need the flag, as above. Only a program that pauses an event pays for it.

Suggestion A once event pauses itself after running the first time: event first on score once. This is common with web events and is cheap here.

Open Who may pause an event? Only the code that declared it (its task, or its shape's methods), or any code that can see it? A priv event is clear. For a public event of a shape, another file pausing the shape's ondrop could break the count the shape is keeping. It is safer to let only the shape's own code pause a shape's events.

🧩 The hard parts: when exactly an event runs

These are the questions that decide whether events feel predictable. Each has a suggested answer, and each still needs the author's decision.

When does a change event run: after each change, or once for several?

An alters method that sets three fields would run onchange three times, and the first two times the value is half-updated. Suggestion Changes made inside the shape's own alters methods are gathered, and the events run once when the method returns, the way React gathers updates. An event then only sees a value its methods left in a whole state. Outside the shape, an event runs after the statement that made the change.

Events that trigger themselves, or each other (Cycle Rejection Policy)

An event that changes what it watches, or triggers another event that cycles back, risks infinite recursion. Specification By default, the compiler strictly refuses any static event cycle at compile time, tracing the exact causal loop: "record changes best, which runs cap, which changes score, which runs record".

Cycle Exception Rule: Cycles are permitted only when every link in the cycle is explicitly guarded by a terminating when <condition> guard (such as when .hp < 50 or when .shield > 0), ensuring the loop terminates deterministically. Furthermore, in accordance with the Indirect Alters Rule, every event participating in the cycle must list the full set of altered fields in its alters(…) declaration (e.g. alters(X, Y) on both). Any unguarded or unproven cycle is rejected at compile time.

Several events on one trigger

Open In what order do they run? Within a file, declaration order is natural. Across files there is no obvious order, and a program that depends on one is fragile. One answer is that events on the same trigger may not depend on each other's changes, which the alters lists would let the compiler check.

Changes the compiler can't see at the place they happen

A watched local can be changed in ways that don't look like an assignment to it: given to a task as &total for a flex& parameter, changed through a flex& ref = &total reference, or changed by an alters method called on it. The task changing it doesn't know an event is watching. Suggestion Treat the call, or the statement that uses the reference, as the change: the event runs once, after it. That keeps every change site in the watching code, and costs nothing in the task that was called. The other choice, refusing &total while something watches total, is simpler but more restrictive.

When does a value go away?

This is the hardest question in the design, because Vela copies values instead of moving them. Open

• A variable goes away at the fi of its block. The compiler knows the place, just as it knows where a region closes.
• A value in a region goes away when the region closes. The region then has to walk through the values that have an ondrop. That costs something, but only for shapes that have one. It is what already happens to a File, which closes when its region ends. The existing mechanism for closing files could become the way ondrop is built.
• An item in a slice goes away at xs.del(…), or when the slice's region closes.
• A value a task sends back leaves the task without going away. The copy in the task doesn't drop, and the caller now has the value.
• A copy (fixed b = a) is a second value. If it drops, but nothing ran for it when it was made, then a count kept with on init and on drop ends up lower than the true number. Suggestion A copy also runs on init, or has an event of its own, on copy. Otherwise the count is never exact, and exact counting was the reason for these events.

Can an event fail?

Suggestion No. Nothing called the event, so there is nowhere to send a failure. An event sends nothing, so fail and <- with a value are refused in it. Something that would stop the program inside an event (an overflow, a bad index) still stops it, and the message says which event it was in.

Memory inside an event

Suggestion Each run of an event is its own block, so it gets a default region that is freed at its fi, like any block. An event can't keep anything it allocates unless it stores it in something that lives longer (a shared field in a static region, if Vela ever has one).

💡 More ideas Idea

🔍 Compared with other languages

🤔 Decisions still to make