Référence › Handlers

Référence

Handlers : TypeScript, Python, le langage d’action

Un handler est une partie du comportement d’un modèle écrite sous forme de code : le corps d’une fonction, le on-receive d’un port, le on-enter d’un état. Vous l’écrivez en TypeScript, en Python ou dans le langage d’action (```arche), qu’archec traduit. archec new écrit du TypeScript.

Un premier handler#

Enregistrez ceci sous main.arche. Le projet indique que ses handlers sont en TypeScript. Le pinger envoie un PING numéroté toutes les 20 ms, et le ponger journalise ceux qui suivent le premier.

project "Ping" {
  handlers typescript
}

message PING { n: int32 }

component Pinger "Pinger" {
  out tx:   data sends PING
  var sent: int32 = 0
  states {
    state Idle
    state Busy {
      on-enter ```ts
        self.sent += 1
        send(self.tx, PING({ n: self.sent }))
      ```
    }
    Idle -> Busy on "after 10ms"
    Busy -> Idle on "after 10ms"
  }
}

component Ponger "Ponger" {
  in rx: data receives PING {
    on-receive ```ts
      if (msg.n > 1) log("got", msg.n)
    ```
  }
}

system Desk {
  part pinger: Pinger
  part ponger: Ponger
  pinger.tx -> ponger.rx
}
Diagramme : Desk
Ce qu’archec dessine depuis ce code : Desk
Essayer

Lancez-le dans le simulateur du navigateur :

$ archec sim main.arche --for 30ms
Ping — system Desk, 30.000 ms simulated
    0.000 ms  pinger: Idle
   10.000 ms  pinger: Idle → Busy
   10.000 ms  pinger.tx → ponger.rx  PING {"n":1}
   20.000 ms  pinger: Busy → Idle
   30.000 ms  pinger: Idle → Busy
   30.000 ms  pinger.tx → ponger.rx  PING {"n":2}
   30.000 ms  ponger: got 2

2 message(s), 4 state change(s)
at 30.000 ms: pinger Busy

Pour avoir les mêmes handlers en Python, convertissez-les :

$ archec convert-handlers main.arche --to python
2 bodies, 3 statements translated, 0 left as TODO(convert)
✓ main.arche

Le projet indique désormais handlers python, et le corps du ponger devient :

if n > 1:
    log("got", n)

La suite de cette page est le contrat entre archec et le simulateur d’Arche. Les deux côtés font ce qu’il dit. Pour tout ce qu’il ne dit pas, faites comme le runtime Python (le arche_runtime.py d’Arche), avec les mêmes noms.

1. Dans quel langage est écrit un morceau de code#

En arche-lang, le langage se choisit à quatre niveaux :

  • Le projet l’indique : project { handlers typescript }, ou python, ou arche.
  • Un composant peut indiquer le sien : component Legacy { handlers python }. Sinon, un composant prend, dans cet ordre :
    1. le langage de sa définition ;
    2. le langage du composant qui le contient ;
    3. le langage de ses fichiers code (code "ctrl.ts" est du TypeScript, code "ctrl.py" du Python) ;
    4. le langage du projet.
  • Un bloc indique le sien : ```ts, ```python, ```arche. Un bloc ``` nu est dans le langage du composant.
  • Un projet sans handlers garde le langage de son code. Du Python quelque part (un fichier .py, un bloc ```python ou un bloc nu) le met en python. Sinon, il est en typescript.

archec new écrit handlers typescript. Utilisez archec new --handlers python|arche pour les autres.

Dans le projet Arche :

  • simulation.yaml indique le langage du projet : behavioral: { language: typescript | python }. En son absence, le langage est python, si bien que tous les projets existants continuent de fonctionner. archec l’écrit quand le projet indique handlers, ou quand le projet contient du code et que ce code est du TypeScript.
  • Le fichier de code d’un fichier de modèle décide du langage du code de ce fichier : code: "rfic.ts" est du TypeScript, code: "rfic.py" du Python.
  • Le code en ligne suit le fichier de code du composant s’il en a un, sinon le langage du projet. Le code en ligne, ce sont les corps d’activation, les handlers, les actions d’état et les gardes écrites sous forme de code.

Le langage d’action est traduit :

  • pour Arche, dans le langage du projet. C’est du TypeScript, ou du Python dans un projet handlers python. handlers arche donne du TypeScript.
  • pour le firmware, en C, Rust ou Go, comme avant.

Un appel vers une autre part est traduit lui aussi. Par exemple, brake.apply(2.5) passe par un port qui requiert une interface dotée de cette opération. Il devient ce qu’un handler écrirait : await component("brk").apply(2.5), pour la part à l’autre bout du lien (la spécification).

archec copie chaque corps dans le projet Arche : Arche exécute donc un seul langage pour tout le projet. Une fonction code "x.ts" devient le corps en ligne qu’elle serait si on l’écrivait ainsi. Un bloc dans l’autre langage est signalé (handlers-language) : archec sim l’exécute, mais Arche ne le ferait pas.

2. À quoi ressemble le code TypeScript#

La source est en TypeScript. Les deux côtés retirent les types et exécutent le JavaScript. archec les retire lui-même (src/tscode.ts) : il n’y a rien à installer. Arche utilise un petit transpileur dans la page. Rien n’est vérifié par le typage avant l’exécution.

Un fichier de code reflète un fichier .py trait pour trait, avec les mêmes noms de fonctions :

import { send, reply, goto, wait, ms, warn, u8 } from "arche"   // optional: the names are global anyway
import type { Rfic, SPI_FRAME } from "arche"                     // archec stubs: the model's types

export async function rfic_on_receive_spi(self: Rfic, msg: Rfic.Msg) {
  if (msg.name !== "SPI_FRAME" || (msg.cs !== self.cs_index && msg.cs !== RFIC_BROADCAST)) return
  self.frames += 1
  if (msg.cmd === 0) reply(SPI_FRAME({ cs: msg.cs, cmd: 0, addr: msg.addr, data: await self.readRegister(msg.addr) }))
  else await self.writeRegister(msg.addr, msg.data)
}
  • self. Le premier paramètre est self, comme en Python.
    • self.x lit et écrit une variable.
    • self.STATUS.state est l’état d’un port.
    • self.mem[...] est la mémoire.
    • await self.f(a) appelle une fonction du composant.
    • Seul le propriétaire écrit ses variables. C’est la même règle qu’en Python.
  • Un message reçu est une valeur, pas des noms nus.
    • Python met les champs d’un message dans la portée sous forme de noms nus, et passe son nom dans message.
    • TypeScript passe un seul argument, msg. C’est un objet qui contient les champs par leur nom et le name du message : { name: "SPI_FRAME", cs, cmd, addr, data }.
    • Dans le code en ligne, msg est dans la portée. message l’est aussi : c’est le nom du message (une chaîne), pour le code repris de Python.
  • Le code en ligne est le corps d’une fonction async. self est dans la portée, et msg aussi quand un message l’a déclenché : self.count += 1; await goto("Run").
  • Les constructeurs de messages prennent un seul objet : SPI_FRAME({ cs: 1, cmd: 0 }). Cela remplace les arguments nommés de Python.
  • Les littéraux d’énumération et les constantes sont des noms globaux, comme en Python.

Dans un modèle, un fichier code "ctrl.ts" se relie au modèle comme un fichier .py. Chaque élément prend la fonction qui porte son nom conventionnel :

Élément Fonction dans le fichier
fn main main
un état On on_enter_On et on_exit_On
un port rx on_receive_rx
une mémoire M on_write_M
on-enter name la fonction nommée

Les paramètres d’une fonction sont self et les arguments du fn. Pour le hook d’un message, ce sont self, msg. Les autres paramètres sont signalés (py-params).

Les constantes, types et fonctions utilitaires en tête de fichier sont copiés dans chaque corps qui les utilise. Les imports ne servent qu’à l’éditeur et sont supprimés. Seuls "arche" et "./arche" peuvent être importés : les deux désignent le arche.d.ts du modèle.

3. L’API#

L’API est un ensemble de noms globaux. Ce sont les mêmes que dans arche_runtime.py.

Les attentes s’écrivent avec await, comme en Python :

wait(d), wait_until(test, timeout?), clock(n?), recv(port, timeout?), select(...ports) / select([ports], timeout), call(port, msg, to?, timeout?), goto(state), put/get/take(port, …), lock(port, timeout?), wait_bits(port, bits, { all, clear, timeout }), stream_write/stream_read, compute(d).

Les appels immédiats s’écrivent sans await :

  • messages et ports : send(port, msg, to?), reply(msg), give, unlock, set_bits, clear_bits, queued, start_timer, stop_timer, pulse(signal, width?), at(address), message(name), component(name) ;
  • sortie : log(...a), warn(...a), print(...a) (vers la trace), fail(msg?) ;
  • temps et hasard : now(), rand(), randint(lo, hi), randn(mu?, sigma?). Le moteur fixe leur graine. N’utilisez jamais Math.random ni Date ;
  • durées : ns/us/ms/sec(x), to_ms/to_us/to_s(t), fmt(t) ;
  • bits et entiers : bits(v, hi, lo?), bit(v, n), setbits(v, hi, lo, x), u8/u16/u32/u64/i8/i16/i32/i64(n).

Le with locked(p): de Python s’écrit await lock(p); try { … } finally { unlock(p) }. Math.* est autorisé, sauf Math.random.

Les règles sont les mêmes qu’en Python :

  • Déterminisme. Revenir en arrière réexécute le code, qui doit donner le même résultat.
  • Boucles infinies. Les tours de boucle sont comptés. Au-delà de la même limite, c’est une erreur.

4. Où il s’exécute, et les types#

  • Arche l’exécute dans un JsRuntime (Lang = 'python' | 'typescript'), dans un Web Worker, sans DOM ni réseau. Le moteur gère le temps et l’état. Il utilise le même protocole d’appels vers l’hôte que le pont Python. Pyodide n’est chargé que si le projet contient du code Python.

  • archec sim (src/websim.ts, src/websimrt.ts) exécute le JavaScript directement, avec la même API. Il tourne dans node, dans la page qu’écrit archec sim --html, dans la page en direct et dans le panneau ▶ de VS Code.

  • archec stubs écrit arche.d.ts dans .arche/typings, dans le dossier du fichier principal. Il écrit au même endroit le paquet arche de Python. Le fichier contient :

    • les signatures de l’API ;
    • une interface par message, avec name ;
    • un type par composant : ses variables, ses ports et ses fonctions, ses états sous forme d’union de chaînes, et une union Msg de ce qu’il reçoit ;
    • les constantes et les énumérations.

    Rien n’est écrit à côté du code, et il n’y a pas de tsconfig.json. Dans VS Code, l’extension écrit le fichier d’elle-même, et son plugin TypeScript fait pointer "arche" et les noms globaux vers lui (voir editor.md). Pour tsc en ligne de commande, ajoutez deux lignes à votre tsconfig.json ; archec stubs les affiche :

    {
      "compilerOptions": { "paths": { "arche": ["./.arche/typings/arche.d.ts"] } },
      "include": ["*.ts", ".arche/typings/arche.d.ts"]
    }

    Une entrée paths associe "arche", pas "./arche" : importez depuis "arche" dans les fichiers que tsc vérifie. archec stubs --beside écrit plutôt arche.d.ts et un tsconfig.json à côté des fichiers .ts, comme le faisaient les versions précédentes.

5. Plans de test et gardes#

Arche exécute le code d’un plan de test dans le langage du projet. Ce code, ce sont le do et le expect d’une étape, un setup ou un stimulus. En arche-lang, vous l’écrivez en Python, comme avant. Dans un projet TypeScript, archec l’écrit pour Arche en TypeScript (src/testcode.ts) :

Écrit Arche exécute
abs(c.x) < 0.1 and not c.done Math.abs(c.x) < 0.1 && !(c.done)
send(rx.frames, RC_FRAME(throttle=1200, arm=True)) send(rx.frames, RC_FRAME({ throttle: 1200, arm: true }))
x is None, min, max, round, int, len(xs) x === null, Math.min, Math.max, Math.round, Math.trunc, (xs).length
pass, # note rien, // note
if c: / elif / else: / while c: / for i in range(n): / for x in xs: la même chose avec des accolades
  • Le préfixe d’une attente (within 5ms:, never:, always:) reste tel quel.
  • Ce qui se lit déjà comme du TypeScript (a && b, GO({ n: 1 })) reste tel quel. Un bloc ```ts est écrit tel quel.
  • Certaines tournures Python n’ont pas d’équivalent TypeScript simple : a if c else b, in, //, un def, with, try, une f-string, une lambda. Elles sont signalées (test-typescript). Écrivez-les autrement, ou dans un bloc ```ts.

La garde et l’action d’une transition s’écrivent de la même façon dans un projet TypeScript. [abs(angle) > FALLEN] arrive dans Arche sous la forme Math.abs(angle) > FALLEN. Les champs du déclencheur sont dans la portée par leur nom, dans les deux langages.

Dans archec#

Quoi Comment
Écrire le langage project { handlers typescript }, component c { handlers python }
Déplacer les blocs dans un fichier archec fmt --extract-code=behaviour.ts --write main.arche (ou --extract-code seul : un fichier par composant, dans son langage)
Les types pour l’éditeur archec stubs main.arche → .arche/typings/arche.d.ts (et le paquet arche s’il y a du Python)
L’exécuter archec sim main.arche (--html, --plant, --batch, --test), archec difftest
Le vérifier archec check : chaque erreur de syntaxe TypeScript sur sa ligne (ts)
Changer de langage archec convert-handlers main.arche --to typescript|python|arche [--component C] [--dry-run]

Limites#

Ce que archec sim exécute de l’API :

  • les attentes wait, compute, goto, et les fonctions propres à la part ;
  • send, reply (sur le port par lequel le message est arrivé), log, print, warn, fail, now ;
  • rand, randint, randn, avec leur graine ;
  • les durées, fmt, les fonctions d’aide sur les bits, les conversions d’entiers, message(name).

Ce qu’il n’exécute pas :

  • recv, select, call, put/get/take, lock, les bits, les flux et les timers, wait_until, clock, pulse, at, component. Chacun arrête le corps avec une erreur qui indique que le simulateur d’Arche l’exécute.
  • Math.random et Date. Ce sont aussi des erreurs, car une exécution doit pouvoir être rejouée.
  • Le state d’une poignée de port. Il n’existe pas dans archec sim.

Le TypeScript qui ne se lit pas :

  • un enum ou un namespace. Ils n’ont pas de JavaScript propre. Utilisez une union de chaînes, ou l’énumération du modèle.
  • un paramètre public x de constructeur.
  • une fonction fléchée async, dans archec sim. Écrivez plutôt une async function.

Un message sans champs, comme message GO: bool, vaut { name, value }.

TypeScript portable#

Les simulateurs exécutent n’importe quel TypeScript. Les générateurs, non. archec gen --target c|embassy|go et archec difftest ne traduisent que ce que le langage d’action sait dire, comme pour ```arche. Un corps TypeScript qui s’en tient à ce sous-ensemble est lu dans l’arbre du langage d’action. Le C, le Rust ou le Go est ensuite écrit à partir de cet arbre.

Le sous-ensemble :

TypeScript Le langage d’action
let x = e, const x = e (avec une valeur) var x = e
self.x = e, +=, -=, *=, /=, self.n++, --k x = e, n += 1, k -= 1
if (c) … else if (c) … else …, while (c) { } if, while
for (let i = a; i < b; i++) (ou i <= b, i += 1) for i in a..b
send(self.p, MSG({ k: v })), MSG(), { k } send p MSG { k: v }
await goto("Run"), await wait(ms(2)), wait(ms(self.t)) goto Run, wait 2ms, wait t * 1ms
log(…), print(…) log …
await self.f(a) f(a), la fonction de la part
msg.distance, msg.name distance, message (les champs du message reçu)
self.state === "Idle" state == Idle
=== !== < <= > >= + - * / % && || !, x ** 2 == != … and or not, x * x
Math.abs min max sqrt sin cos atan2, Math.trunc(x), Number(x), Math.PI abs …, int(x), float(x), un littéral
now(), to_s(t), to_ms(t), ns/us/ms/sec(x) la même chose
return, break, continue, nombres, chaînes, true, false, constantes, Color.Red la même chose

Ensuite, la vérification du langage d’action s’exécute. Le corps sort du sous-ensemble s’il contient un nom que la vérification ne connaît pas, un type qui ne convient pas, ou une division de deux entiers. (TypeScript divise les entiers comme des flottants.)

Sont hors du sous-ensemble : un tableau ou un indice (le langage d’action en a, buf[i] ; ceux de TypeScript n’y sont pas traduits), un ternaire, une chaîne gabarit, une méthode d’une valeur (list.push), une fonction utilitaire, reply, recv, un opérateur sur les bits, switch, try. Un tel corps s’exécute quand même tel quel dans les simulateurs. Les générateurs écrivent à sa place un TODO contenant le TypeScript, comme ils le font pour le Python qu’ils ne savent pas traduire. archec check nomme la construction (ts-portable). C’est une information dans un projet qui ne fait que simuler, et un avertissement quand un déploiement génère du code pour le composant.

Le on-receive d’un port en TypeScript peut lire son message (msg.distance). En C, il reçoit le message sous la forme <part>_on_receive_<port>(self, const void *arche_msg), avec ses champs par leur nom. Les gardes et les actions d’une transition reçoivent les leurs de la même façon. Une garde écrite en TypeScript ([msg.force > 0]) est traduite de la même façon, elle aussi. archec difftest compare donc le TypeScript qu’exécute le simulateur au C qu’il devient. examples/ts-handlers concorde.

Conversion#

archec convert-handlers main.arche --to typescript|python|arche réécrit sur place les handlers du modèle dans un autre langage. Il réécrit :

  • chaque bloc ```, en gardant sa clôture et son indentation ;
  • chaque fichier code. code "ctrl.py" devient "ctrl.ts". L’ancien fichier est conservé ; supprimez-le quand vous avez terminé. Vers arche, chaque fonction devient un bloc ```arche sur son élément ;
  • les gardes des transitions ;
  • handlers sur le projet, ou sur le composant avec --component Ctrl.

Comment chaque langage est lu :

  • Depuis ```arche : exactement, par les mêmes traducteurs que ceux qui produisent la copie d’Arche.
  • Depuis Python : instruction par instruction, à travers ce que dit le langage d’action. C’est la même lecture que celle des générateurs pour Python.
  • Depuis TypeScript : instruction par instruction, à travers le sous-ensemble portable ci-dessus.
  • Un message reçu : les noms de champs nus de Python (distance) deviennent msg.distance en TypeScript, et le message de Python devient msg.name. Le langage d’action n’a pas de message dans un corps : une instruction qui en lit un reste donc un TODO.

Ce que devient le reste :

  • Une instruction qui ne se traduit pas reste en commentaire, avec l’original : // TODO(convert): <python>, ou # TODO(convert): <ts> en Python. La commande les liste un par un, avec la raison. archec check le signale (convert-todo) tant que vous ne l’avez pas écrit.
  • Les commentaires entre les instructions sont conservés. Un commentaire en fin de ligne, ou dans un bloc imbriqué, ne l’est pas.
  • Rien n’est écrit quand le résultat contient plus d’erreurs que le modèle. --dry-run se contente de dire ce qui changerait.

La conversion garde le sens, pas le texte. clamp(x, a, b) revient de TypeScript sous la forme min(max(x, a), b), et a - b + (c - d) sous la forme a - b + c - d.

Diagnostics#

Code
handlers handlers ne nomme aucun langage de handler
handlers-language du code dans un autre langage que celui dans lequel Arche exécute le projet
code-language un bloc ``` dans un langage qui n’est pas un langage de handler
ts du TypeScript qui ne se lit pas, n’a pas de JavaScript, importe un module ou garde un état en tête de fichier
ts-portable un corps TypeScript hors du sous-ensemble portable : la construction ; les générateurs écrivent un TODO
convert-todo une instruction que archec convert-handlers a laissée en commentaire TODO(convert):
py-params, py-not-found, py-unused, code-not-found comme pour les fichiers .py
test-typescript du code de test, dans un projet TypeScript, qu’archec ne sait pas écrire en TypeScript (§5)