Salta al contingut
Ridgun
Català
EnglishEspañolCatalàEuskaraGalegoPortuguêsSvenskaItaliano

Referència

Ridgun — Especificació de la capa d'abstracció de plataforma (PAL) i de les llibreries del sistema (posix.rglib, io.rglib)

Aquesta especificació defineix el contracte entre el compilador de Ridgun (ridgunc v0.9.5) i les llibreries del sistema de Ridgun (posix.rglib, io.rglib, unix-tools) per a tots els sistemes operatius de destinació, admesos i previstos (Linux, MacOS, Windows), i totes les arquitectures de CPU (X86_64, Arm64).

1. Visió general de l'arquitectura: PAL de 2 capes + ADT suma de destinació

Ridgun evita exposar números de crida al sistema exclusius de Linux o màscares de bits específiques d'un sistema operatiu a les llibreries portables. Per fer-ho, divideix la interacció amb el sistema en dues capes del compilador més uns ADT de destinació fortament tipats:

  1. ADT suma de plataforma de destinació predeclarats (sys os => SysOs, sys arch => SysArch):
  • En lloc de retornar valors String sense tipar (propensos a errors tipogràfics i que el comprovador de tipus no pot verificar), ridgunc predeclara dos ADT suma extensibles:
     type SysOs   = Linux | MacOS | Windows
     type SysArch = X86_64 | Arm64
  • El backend resol sys os => SysOs i sys arch => SysArch en temps de compilació en constants NLoadAdt0 sense cap sobrecost (Linux / X86_64 a x86_64-linux, Linux / Arm64 a arm64-linux).
  • Les llibreries poden triar el cas amb netedat mitjançant pattern matching tabular sobre SysOs / SysArch, comparar amb == ((sys os) == Linux) o estendre'ls per a destinacions BSD o sense sistema operatiu pròpies amb expand type SysOs = FreeBSD | BareMetal (FR-COMP-005).
  1. Capa 1 — Primitives PAL multiplataforma (sys open mode, sys open, sys close, sys read fd, sys write fd, sys poll, sys terminate, sys kill, sys call):
  • Totes les màscares d'indicadors i d'esdeveniments de sondeig que es passen a les primitives de la capa 1 fan servir constants normalitzades de la PAL de Ridgun.
  • Cada backend (x86_64.rg ELF64, arm64.rg ELF64 i els futurs backends Mach-O per a macOS i PE64 per a Windows) tradueix aquestes constants normalitzades a l'ABI nativa del nucli del sistema operatiu (openat/poll/kill a Linux, open/poll/kill a macOS, CreateFileW/WaitForSingleObject/WSAPoll/TerminateProcess a Windows).
  • S'accepten de manera idèntica la sintaxi de llenguatge natural separada per espais (sys open mode path "r") i la sintaxi separada per guions baixos (sys_open_mode path "r").
  1. Capa 2 — Quotes d'execució declaratives (with timeout <duration> do):
  • Els literals enters admeten sufixos de durada: _ms (* 1), _s (* 1000) i _min (* 60000).
  • with timeout 500_ms do <body> (i la forma combinada with region 64_KB, timeout 500_ms do <body>) afegeix un termini lèxic (sys time ms + duration_ms) a la pila de terminis de la PAL local del fil, el limita a qualsevol termini exterior més estricte (min(outer, new)) i restaura el termini exterior en sortir.
  • Dins d'un bloc with timeout, sys deadline ms => Int retorna el termini actiu en temps absolut (0 si no n'hi ha), sys remaining ms => Int retorna els mil·lisegons restants (-1 si no hi ha termini, 0 si ha vençut), i sys poll fd events -1 limita automàticament el temps d'espera a sys remaining ms.

2. Referència de la PAL integrada al compilador (FR-COMP-007)

2.1 Introspecció de la plataforma de destinació

PrimitivaSignaturaDescripció
sys os=> SysOsSistema operatiu de destinació en temps de compilació (Linux | MacOS | Windows).
sys arch=> SysArchArquitectura de CPU de destinació en temps de compilació (X86_64 | Arm64).

Exemple idiomàtic de selecció per sistema operatiu en una llibreria .rglib sense cadenes if/else:

fn :: path separator SysOs   => String
      path separator Linux   =  "/"
      path separator MacOS   =  "/"
      path separator Windows =  "\\"

fn :: null device => String
      null device =  null device for (sys os)

fn :: null device for SysOs   => String
      null device for Windows =  "NUL"
      null device for _       =  "/dev/null"

2.2 E/S amb descriptors o identificadors i sondeig de disponibilitat

PrimitivaSignaturaContracte PAL normalitzat
sys open modeString String => IntObre path amb la cadena de mode portable "r", "w", "a", "rw", "w+" o "a+" (permís per defecte 0644 / 420 en crear). Retorna un descriptor/identificador >= 0 o un codi d'error negatiu (-errno).
sys openString Int Int => IntObre path amb els flags normalitzats de la PAL de Ridgun (0 = només lectura, 1 = només escriptura, 2 = lectura i escriptura, 64 = crear, 512 = truncar, 1024 = afegir al final, 2048 = no bloquejant) i el permís mode (p. ex. 420 per a 0644).
sys closeInt => IntTanca fd o l'identificador. Retorna 0 si té èxit o un -errno negatiu.
sys read fdInt Int => StringLlegeix fins a max_bytes de fd o de l'identificador (0 = stdin, 1 = stdout, 2 = stderr, o un fitxer, pipe o FIFO obert). Retorna "" en cas d'EOF (0 bytes) o d'error.
sys write fdInt String => IntEscriu data a fd o a l'identificador. Retorna els bytes escrits (>= 0) o un -errno negatiu.
sys pollInt Int Int => IntSondeja fd per als events normalitzats (1 = POLLIN llegible, 4 = POLLOUT escrivible, 8 = POLLERR, 16 = POLLHUP) amb timeout_ms (-1 = infinit o limitat a sys remaining ms dins de with timeout, 0 = sondeig no bloquejant, > 0 = espera màxima en ms). Retorna una màscara de bits > 0 amb els esdeveniments a punt, 0 si s'esgota el temps o < 0 amb -errno.

2.3 Rellotges, terminis, senyals i via d'escapament de baix nivell

PrimitivaSignaturaContracte PAL normalitzat
sys time ms=> IntRellotge monòton en mil·lisegons (CLOCK_MONOTONIC).
sys sleep msInt => ()Dorm durant ms mil·lisegons (nanosleep / Sleep).
sys deadline ms=> IntTermini lèxic actiu en ms monòtons (0 fora de with timeout).
sys remaining ms=> IntMil·lisegons que falten per al termini lèxic actiu (-1 fora de with timeout, 0 si ha vençut).
sys getpid=> IntIdentificador del procés actual (> 0).
sys terminateInt Bool => IntFinalització de processos multiplataforma: force = False envia una finalització ordenada (SIGTERM a POSIX), force = True força la finalització immediata (SIGKILL a POSIX, TerminateProcess a Windows). Retorna 0 o -errno.
sys killInt Int => IntEnvia un senyal normalitzat (0 = comprovació d'existència, 2 = SIGINT, 9 = SIGKILL, 15 = SIGTERM) a pid (o al grup de processos quan pid < 0). Retorna 0 o -errno.
sys pipe=> Int IntCrea un pipe del sistema operatiu (__NR_pipe = 22) i retorna (read_fd, write_fd) (o (-1, -1) en cas d'error).
sys waitpidInt Int => Int IntEspera el procés fill pid amb options (0 = bloquejant, 1 = WNOHANG) mitjançant __NR_wait4 = 61 i retorna (ret_pid, exit_status), descodificat amb WIFEXITED/WEXITSTATUS (0..255) i WIFSIGNALED (128 + WTERMSIG).
sys callInt Int Int Int Int Int Int => IntCrida al sistema directa de baix nivell segons l'ABI de destinació (nr, a1..a6) per a controladors específics d'un sistema operatiu. Quan la facis servir, protegeix-la amb sys os / sys arch.

3. Superfície recomanada de les llibreries .rglib (io.rglib i posix.rglib)

3.1 io.rglib — Embolcalls d'E/S d'alt nivell que tenen en compte el temps d'espera

type IoResult = IoOk String | IoTimeout | IoEof | IoError Int

fn :: io read with timeout String Int     => IoResult
      io read with timeout path   wait_ms =
        with timeout wait_ms do
          -- Open non-blocking (0 + 2048 = O_RDONLY | O_NONBLOCK) so FIFO/device open never hangs
          fd = sys open path 2048 0
          io read poll step fd

fn :: io read poll step Int => IoResult
      io read poll step fd
        | fd < 0 = IoError fd
        | otherwise =
          -- timeout_ms = -1 automatically uses `sys remaining ms` from the active `with timeout` block
          ev = sys poll fd 1 (0 - 1)
          io read after poll fd ev

fn :: io read after poll Int Int => IoResult
      io read after poll fd  ev
        | ev == 0 =
          _ = sys close fd
          IoTimeout
        | ev < 0 =
          _ = sys close fd
          IoError ev
        | otherwise =
          chunk = sys read fd fd 65536
          _ = sys close fd
          io wrap chunk chunk

fn :: io wrap chunk String => IoResult
      io wrap chunk ""     =  IoEof
      io wrap chunk s      =  IoOk s

3.2 posix.rglib — Constants simbòliques i funcions auxiliars de processos

-- Normalized PAL Open Flags
fn :: o rdonly   => Int
      o rdonly   =  0

fn :: o wronly   => Int
      o wronly   =  1

fn :: o rdwr     => Int
      o rdwr     =  2

fn :: o creat    => Int
      o creat    =  64

fn :: o trunc    => Int
      o trunc    =  512

fn :: o append   => Int
      o append   =  1024

fn :: o nonblock => Int
      o nonblock =  2048

-- Normalized PAL Poll Events
fn :: poll in  => Int
      poll in  =  1

fn :: poll out => Int
      poll out =  4

fn :: poll err => Int
      poll err =  8

fn :: poll hup => Int
      poll hup =  16

-- Normalized Signals
fn :: sig int  => Int
      sig int  =  2

fn :: sig kill => Int
      sig kill =  9

fn :: sig term => Int
      sig term =  15

fn :: process exists Int => Bool
      process exists pid =  (sys kill pid 0) == 0

4. Compilar i distribuir llibreries .rglib i .so

Compila qualsevol mòdul de llibreria sense necessitat de main:

# Emit portable Ridgun library bundle (.rglib)
./bin/ridgunc build --lib src/main/ridgun/lib/io.rg -o target/io.rglib

# Emit native ELF64 shared object (.so)
./bin/ridgunc build --so src/main/ridgun/lib/io.rg -o target/libio.so

# Or via stable in a library project (`stable new --lib io`):
./bin/stable built lib