Erreferentzia

Ridgun — Plataforma Abstrakzio Geruzaren (PAL) eta sistema-liburutegien (`posix.rglib`, `io.rglib`) espezifikazioa

Espezifikazio honek Ridgun konpiladorearen (ridgunc v0.9.5) eta Ridgun sistema-liburutegien (posix.rglib, io.rglib, unix-tools) arteko kontratua definitzen du, onartutako eta aurreikusitako sistema eragile helburu guztietan (Linux, MacOS, Windows) eta PUZ arkitektura guztietan (X86_64, Arm64).

1. Arkitekturaren ikuspegi orokorra: 2 geruzako PAL + helburuen batura-ADTak

Ridgunek ez ditu Linuxen soilik balio duten sistema-dei zenbaki gordinak edo sistema eragile bakoitzaren bit-banderak liburutegi eramangarrietan agerian uzten. Horretarako, sistemarekiko elkarrekintza bi konpiladore-geruzatan banatzen du, gehi oso tipatutako helburu-ADTak:

Aurrez deklaratutako helburu-plataformaren batura-ADTak (sys os => SysOs, sys arch => SysArch):

Tipatu gabeko String-ak itzuli beharrean (akatsak egiteko errazak dira eta mota-egiaztatzaileak ezin ditu egiaztatu), ridgunc-ek bi batura-ADT hedagarri deklaratzen ditu aurrez:

     type SysOs   = Linux | MacOS | Windows
     type SysArch = X86_64 | Arm64

sys os => SysOs eta sys arch => SysArch backendak konpilazio-garaian ebazten ditu, gainkargarik gabeko NLoadAdt0 konstante bihurtuta (Linux / X86_64 x86_64-linux-en, Linux / Arm64 arm64-linux-en).
Liburutegiek garbi bidera dezakete exekuzioa SysOs / SysArch motetan eredu bat-etortze taularatuaren bidez, ==-rekin alderatu ((sys os) == Linux), edo hedatu bare-metal edo BSD helburu pertsonalizatuetarako expand type SysOs = FreeBSD | BareMetal erabiliz (FR-COMP-005).

1. geruza — Plataforma anitzeko PAL primitibak (sys open mode, sys open, sys close, sys read fd, sys write fd, sys poll, sys terminate, sys kill, sys call):

1. geruzako primitibei pasatzen zaizkien bandera-maskara eta poll gertaera-maskara guztiek Ridgun PAL konstante normalizatuak erabiltzen dituzte.
Backend bakoitzak (x86_64.rg ELF64, arm64.rg ELF64, eta etorkizuneko Mach-O macOS / PE64 Windows backendak) konstante normalizatu horiek sistema eragilearen nukleoaren ABI natibora itzultzen ditu (openat/poll/kill Linuxen, open/poll/kill macOSen, CreateFileW/WaitForSingleObject/WSAPoll/TerminateProcess Windowsen).
Hizkuntza naturaleko zuriunez bereizitako sintaxia (sys open mode path "r") eta azpimarraz bereizitakoa (sys_open_mode path "r") berdin onartzen dira.

2. geruza — Exekuzio-kuota deklaratiboak (with timeout <duration> do):

Osoko literalek iraupen-atzizkiak onartzen dituzte: _ms (* 1), _s (* 1000) eta _min (* 60000).
with timeout 500_ms do <body>-k (eta with region 64_KB, timeout 500_ms do <body> konbinazioak) epe-muga lexiko bat (sys time ms + duration_ms) gehitzen dio hariaren PAL epe-mugen pilari, kanpoko epe-muga zorrotzagoa badago horretara mugatzen du (min(outer, new)) eta kanpoko epe-muga berrezartzen du irtetean.
with timeout bloke baten barruan, sys deadline ms => Int-ek epe-muga aktiboa itzultzen du (0 mugarik ez badago), sys remaining ms => Int-ek geratzen diren milisegundoak itzultzen ditu (-1 mugarik ez badago, 0 iraungi bada), eta sys poll fd events -1-ek bere itxaronaldia automatikoki sys remaining ms-ra mugatzen du.

2. Konpiladorean integratutako PALaren erreferentzia (`FR-COMP-007`)

2.1 Helburu-plataformaren introspekzioa

Primitiba	Sinadura	Deskribapena
`sys os`	`=> SysOs`	Konpilazio-garaiko helburuko sistema eragilea (`Linux \| MacOS \| Windows`).
`sys arch`	`=> SysArch`	Konpilazio-garaiko helburuko PUZ arkitektura (`X86_64 \| Arm64`).

Sistema eragile anitzeko bideratze idiomatikoaren adibidea .rglib liburutegi batean, if/else katerik gabe:

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 Deskribatzaile / handle bidezko S/I eta prest-egoeraren polling-a

Primitiba	Sinadura	PAL kontratu normalizatua
`sys open mode`	`String String => Int`	`path` irekitzen du `"r"`, `"w"`, `"a"`, `"rw"`, `"w+"` edo `"a+"` modu-kate eramangarriarekin (sortzean lehenetsitako baimena: `0644` / `420`). Deskribatzailea/handle-a `>= 0` edo errore-kode negatiboa (`-errno`) itzultzen du.
`sys open`	`String Int Int => Int`	`path` irekitzen du Ridgun PAL `flags` normalizatuekin (`0` = irakurtzeko soilik, `1` = idazteko soilik, `2` = irakurtzeko eta idazteko, `64` = sortu, `512` = moztu, `1024` = gehitu amaieran, `2048` = blokeatu gabe) eta `mode` baimenarekin (adibidez, `420` `0644`-rako).
`sys close`	`Int => Int`	`fd`/handle-a ixten du. `0` itzultzen du arrakasta badu, edo `-errno` negatiboa.
`sys read fd`	`Int Int => String`	Gehienez `max_bytes` irakurtzen du `fd`/handle-tik (`0` = stdin, `1` = stdout, `2` = stderr, edo irekitako fitxategia/kanalizazioa/FIFOa). `""` itzultzen du EOF denean (`0` byte) edo errorea gertatzean.
`sys write fd`	`Int String => Int`	`data` idazten du `fd`/handle-an. Idatzitako byteak (`>= 0`) edo `-errno` negatiboa itzultzen ditu.
`sys poll`	`Int Int Int => Int`	`fd`-ren `events` normalizatuak (`1` = `POLLIN` irakurgarria, `4` = `POLLOUT` idazgarria, `8` = `POLLERR`, `16` = `POLLHUP`) kontsultatzen ditu `timeout_ms`-rekin (`-1` = mugagabea, edo `sys remaining ms`-ra mugatua `with timeout` barruan; `0` = kontsulta blokeatu gabea; `> 0` = gehienezko itxaronaldia ms-tan). `> 0` prest dauden gertaeren bit-maskara itzultzen du, `0` denbora-muga gainditzean, edo `< 0` `-errno` denean.

2.3 Erlojuak, epe-mugak, seinaleak eta maila baxuko ihesbidea

Primitiba	Sinadura	PAL kontratu normalizatua
`sys time ms`	`=> Int`	Milisegundoko erloju monotonoa (`CLOCK_MONOTONIC`).
`sys sleep ms`	`Int => ()`	`ms` milisegundoz lo egiten du (`nanosleep` / `Sleep`).
`sys deadline ms`	`=> Int`	Epe-muga lexiko aktiboa ms monotonotan (`0` `with timeout`-etik kanpo).
`sys remaining ms`	`=> Int`	Epe-muga lexiko aktiborako geratzen diren milisegundoak (`-1` `with timeout`-etik kanpo, `0` iraungi denean).
`sys getpid`	`=> Int`	Uneko prozesuaren IDa (`> 0`).
`sys terminate`	`Int Bool => Int`	Plataforma anitzeko prozesu-amaiera: `force = False`-k amaiera ordenatua eskatzen du (`SIGTERM` POSIXen), `force = True`-k berehalako amaiera behartzen du (`SIGKILL` POSIXen, `TerminateProcess` Windowsen). `0` edo `-errno` itzultzen du.
`sys kill`	`Int Int => Int`	Seinale normalizatua (`0` = existitzen den probatzeko, `2` = `SIGINT`, `9` = `SIGKILL`, `15` = `SIGTERM`) bidaltzen dio `pid`-i (edo prozesu-taldeari `pid < 0` denean). `0` edo `-errno` itzultzen du.
`sys pipe`	`=> Int Int`	Sistema eragilearen kanalizazio bat (`__NR_pipe = 22`) sortzen du eta `(read_fd, write_fd)` itzultzen du (edo `(-1, -1)` errorea gertatzean).
`sys waitpid`	`Int Int => Int Int`	`pid` prozesu umearen zain geratzen da `options`-ekin (`0` = blokeatzailea, `1` = `WNOHANG`) `__NR_wait4 = 61` bidez, eta `(ret_pid, exit_status)` itzultzen du, `WIFEXITED`/`WEXITSTATUS` (`0..255`) eta `WIFSIGNALED` (`128 + WTERMSIG`) bidez deskodetuta.
`sys call`	`Int Int Int Int Int Int Int => Int`	Helburuko ABIko maila baxuko sistema-dei gordina (`nr`, `a1..a6`), sistema eragile jakin baterako driverretarako. Erabiltzean, babestu `sys os` / `sys arch` bidez.

3. Gomendatutako `.rglib` liburutegi-azalera (`io.rglib` eta `posix.rglib`)

3.1 `io.rglib` — Denbora-mugak kontuan hartzen dituzten goi-mailako S/I bilgarriak

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` — Konstante sinbolikoak eta prozesu-laguntzaileak

-- 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. `.rglib` eta `.so` liburutegiak eraikitzea eta banatzea

Konpilatu edozein liburutegi-modulu main behar izan gabe:

# 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

Ridgun — Plataforma Abstrakzio Geruzaren (PAL) eta sistema-liburutegien (posix.rglib, io.rglib) espezifikazioa

1. Arkitekturaren ikuspegi orokorra: 2 geruzako PAL + helburuen batura-ADTak

2. Konpiladorean integratutako PALaren erreferentzia (FR-COMP-007)

2.1 Helburu-plataformaren introspekzioa

2.2 Deskribatzaile / handle bidezko S/I eta prest-egoeraren polling-a

2.3 Erlojuak, epe-mugak, seinaleak eta maila baxuko ihesbidea

3. Gomendatutako .rglib liburutegi-azalera (io.rglib eta posix.rglib)

3.1 io.rglib — Denbora-mugak kontuan hartzen dituzten goi-mailako S/I bilgarriak