Contrat de module natif

Statut documentaire : reference — voir Maturité et preuves.

Frontière

Un module ABI natif est une bibliothèque dynamique qui expose une fonction connue retournant une table de fonctions versionnée. L'hôte ne découvre pas arbitrairement des méthodes d'implémentation exportées : il charge la table, la valide, initialise le module, puis effectue les appels via cette table.

bibliothèque dynamique
  -> GetModuleAPI
  -> table d'API versionnée
       init
       shutdown
       invoke
       release
       free
       get-last-error

Les noms ci-dessus décrivent les rôles publics des entrées ; les SDK applicatifs ne doivent pas exposer cette table bas niveau.

Validation avant utilisation

Le loader actuel vérifie : chargement de la bibliothèque, présence du point d'entrée, table non nulle, version ABI, taille minimale, fonctions obligatoires et succès de l'initialisation. Un échec empêche l'utilisation du module.

Initialisation et arrêt

L'initialisation reçoit un contexte hôte opaque. Le contrat ABI générique n'impose pas la structure interne de ce contexte.

Le shutdown appartient au cycle de vie du module. La bibliothèque dynamique n'est déchargée qu'après la tentative d'arrêt et l'abandon de la table d'API.

Invocation

La fonction native générique reçoit :

receiver handle
method id
argument-record pointer
result-storage pointer

Un constructeur ou appel statique n'a normalement pas de receiver. Un appel d'instance transporte le handle opaque obtenu précédemment. Le descripteur détermine si un receiver est obligatoire et l'hôte rejette les incohérences avant l'entrée dans le module.

Codes de résultat et dernière erreur

0 signifie succès dans le contrat actuel. En cas d'échec, le module peut fournir son dernier message UTF-8. Le buffer appartient au module : l'hôte copie le texte puis le libère avec la fonction free du même module.

Handles

Un handle est opaque. Le client ne doit pas le déréférencer, supposer un layout natif stable, comparer son adresse comme identité métier, ni le libérer avec l'allocateur hôte.

Lorsque l'ownership indique que l'appelant possède le handle, la libération passe par l'entrée release du module.

Note de portabilité actuelle

Le loader natif inspecté pour cette passe utilise actuellement le chemin de chargement dynamique Windows. La forme de la table ABI est portable, mais cette page ne prétend pas que chaque loader hôte soit déjà certifié sur tous les OS.