io lib-a — IoResult Errore Tipatuak, with timeout bidezko S/I eta Prozesuak

31.1. Zergatik existitzen da io lib-a? (Benetako arazoa eta Ridgun filosofia)

«Zergatik behar dut io lib bat hutsetik Ridgun hutsean idatzia, betiko C liburutegi bat estekatu beharrean?»

Hori da edozein sistema-ingeniarik io-era iristean egiten duen lehen galdera. Eta erantzunak ridgun-libs-en filosofia osoa laburbiltzen du:

Izan gaitezen zintzoak: epemugarik (timeout) gabeko read() dei bat edo ume-azpiprozesu bat zintzilikatutako baliabide bakar batek zure zerbitzariko langile guztiak agortzeko gonbidapena da.

io lib-ak sistemaren eragiketa bakoitza ADT esplizituekin modelatzen du (IoError, IoResult[A]), blokeatzailea ez den ppoll Ridgunen with timeout wait_ms do kuota lexikoekin uztartzen du eta read fd ... timeout zein write fd ... timeout mixfix eragileak eskaintzen ditu.

Ekosistema tradizional batean, IO domeinuko zereginak ebazteak C-ko kanpo-mendekotasunak arrastatzea, erakusle gordinekin borrokatzea, mota-bihurketa opakuak, egiaztatu gabeko salbuespenak edo zabor-biltzailearen geldialdi ustekabekoak jasatea dakar. Ridgunen, io lib-ak (src/main/ridgun/lib/io.rg) lau printzipio negoziatu ezinekin heltzen dio arazoari:

1. Deklaratu import io (edo import io as alias) fitxategiaren hasieran: lib bakoitzak module :: io izen-espazioa definitzen du eta --strict moduan hitz anitzeko funtzioei zuriune naturalekin deitzen zaie beti.
2. Kateatu zure datu-hodiak ezkerretik eskuinera -> bidez: idatzi sarrera lehen urratsa -> bigarren urratsa -> emaitza, erabili (+ _ _ +) maskarak sekuentziak desegituratzeko eta kendu _ = sententzia sekuentzialetan (edo baztertu -> () bidez).
3. Isats-errekurtsioa TCOrekin (Tail-Call Optimization): io-eko barne-ibilbide guztiak $O(1)$ pila-espazioko begizta natiboetara konpilatzen dira.
4. Memoria determinista (RMM1 / RMM2): tarteko egitura bakoitza bere azken irakurketa amaitzen den une zehatzean askatzen da, Garbage Collector gabe.

---

31.2. Artefaktu natiboak, inportazioa eta io APIaren katalogo osoa

ridgun-libs-en, io lehen mailako lib bat da, src/main/ridgun/lib/io.rg bidean kokatua (IO domeinua). stable bundle-ekin konpilatzean, hiru formatu natibotan paketatzen da:

Artefaktua	Bidea	Helburua
Ridgun Bundle-a	target/bundles/io.rglib	Banaketa eta inportazio zuzena import io bidez
Fitxategi konpilatua	target/io.rgc	ridgunc-ek egiaztatutako tarteko artefaktua
ELF64 objektu partekatua	target/libio.so	C edo libc mendekotasunik gabeko liburutegi dinamiko natiboa

Lib bakoitzak bere izen-espazioa deklaratzen du module :: io bidez: nahikoa da goiburuan import io (edo import io as alias) idaztea eta bere funtzioei zuriune naturalekin (nire funtzioa x) eta -> hodiekin (x nire funtzioa -> emaitza) deitzea.

31.2.1. io-eko familia funtzionalen laburpena

Sinadura / Funtzioa / Mota	Zer egiten duen eta noiz erabili
type IoError / type IoResult[A]	`IoNotFound
io read with timeout / io write with timeout	wait_ms bidez mugatutako deskribatzaileen irakurketa/idazketa ez-blokeatzailea
read fd N max M timeout T / write fd N data S timeout T	Epemugadun deskribatzaileen S/I-rako mixfix eragile ergonomikoak (op ::)
io read file / io write file / io read lines	IoResult itzultzen duten fitxategi eta lerro-korronteen funtzio seguruak
exec with timeout : String -> Int -> IoResult[ProcStatus]	Kanpoko komando bat exekutatzen du with timeout kuota lexiko batez mugatuta

31.2.2. src/main/ridgun/lib/io.rg-eko mota eta sinadura guztien katalogoa

Jarraian duzu src/main/ridgun/lib/io.rg fitxategian definitutako mota aljebraiko (type), eragile (op ::) eta funtzio-sinadura (fn ::) guztien inbentario osoa (2 mota, 2 eragile eta 42 funtzio):

io-eko mota aljebraikoak eta erregistroak (type):

type IoError = Timeout Int | Eof | SysErr Int String | NotFound String
type IoResult = String | Int | Timeout Int | Eof | SysErr Int String | NotFound String | IoErr IoError | IoOk String | IoTimeout | IoEof | IoError Int

io-eko mixfix eragileak (op ::):

op :: read fd Int max Int timeout Int => IoResult
op :: write fd Int data String timeout Int => IoResult

#	Funtzioa / Sinadura (fn ::)	Itzulera-mota
1	fn :: format io error IoError	String
2	fn :: format io result IoResult	String
3	fn :: map read bytes String	IoResult
4	fn :: read fd after poll PollStatus Int Int Int	IoResult
5	fn :: read fd Int Int Int	IoResult
6	fn :: map write rc Int	IoResult
7	fn :: write fd after poll PollStatus Int String Int	IoResult
8	fn :: write fd Int String Int	IoResult
9	fn :: has null char String Int Int	Bool
10	fn :: pad ms three Int	String
11	fn :: format timeout sec Int	String
12	fn :: map exec rc Int Int	IoResult
13	fn :: io exec timeout String Int	IoResult
14	fn :: exec with timeout String Int	IoResult
15	fn :: read existing or empty String	String
16	fn :: append file String String	Int
17	fn :: file exists String	Bool
18	fn :: is file String	Bool
19	fn :: is dir String	Bool
20	fn :: is symlink String	Bool
21	fn :: extract size (Bool String Int Int Int String String Int String)	Int
22	fn :: file size String	Int
23	fn :: extract mtime (Bool String Int Int Int String String Int String)	Int
24	fn :: file mtime String	Int
25	fn :: extract mode (Bool String Int Int Int String String Int String)	Int
26	fn :: file mode String	Int
27	fn :: io read file safe String	IoResult
28	fn :: split lines loop String Int Int Int	[String]
29	fn :: split non empty lines String Int	[String]
30	fn :: io read lines String	[String]
31	fn :: str list is empty [String]	Bool
32	fn :: join lines nl [String]	String
33	fn :: io write lines String [String]	Int
34	fn :: io wrap chunk String	IoResult
35	fn :: io read after poll Int Int	IoResult
36	fn :: io read poll step Int	IoResult
37	fn :: io read with timeout String Int	IoResult

---

31.3. io sakonki esploratzen: Funtzionalitate bakoitzaren urratsez urratseko adibideak

Ez da nahikoa sinadura-taula ikustea: io lib-aren funtzionalitate bakoitza Ridgunen exekutagarriak diren adibide progresiboen bidez esploratuko dugu. Eguneroko bi errezeta taularatuekin hasiko gara eta ondoren xehetasunez ikusiko ditugu src/test/ridgun/test io.rg-en egiaztatutako agertoki funtzional eta muga-kasu guztiak.

31.3.1. 1. adibidea: Fluxu nagusia estilo taularatuan io erabiliz

Ikusi nola Ridgunen = ikurrak eta io bidezko eraldaketa-urratsak taula garbi bat bezala lerrokatuta geratzen diren, beharrezkoak ez diren aldagai aldakorrik edo ezkutuko albo-ondoriorik gabe:

import io

fn :: leer peticion segura Int => String
      leer peticion segura fd =
        read fd fd max 4096 timeout 250 -> res
        res format io result

31.3.2. 2. adibidea: Konposizio segurua eta muga-kasuen kudeaketa

io lib-eko funtzio oro | guarda boolearrekin eta ridgun-libs-eko gainerako 32 lib-ekin konposatzeko diseinatuta dago:

import io

fn :: describir fallo => String
      describir fallo =
        format io error (Timeout 250)

31.3.3. 3. adibidea: IoError errore-hierarkia hedagarria (Timeout, Eof, InvalidInput, PermissionDenied, NotFound, PosixErrno) eta io error message formatua

Adibide praktiko honetan io bloke funtzional honetan nola portatzen den sakonki aztertzen dugu, sarrera estandarrak, parametro-konbinazioak eta muga-balioak barne:

fn :: test io error formatting => ()
      test io error formatting =
        assert str eq (format io error (Timeout 500)) "timeout after 500 ms" "format Timeout 500"
        assert str eq (format io error Eof) "unexpected end of file" "format Eof"
        assert str eq (format io error (SysErr 9 "poll")) "syscall error 9 in poll" "format SysErr"
        assert str eq (format io error (NotFound "/missing")) "file not found: /missing" "format NotFound"
        ()

31.3.4. 4. adibidea: Epez bornatutako deskribatzaileen irakurketa eta idazketa (read fd ... timeout, write fd ... timeout, with timeout) eta Eof detekzioa

Adibide praktiko honetan io bloke funtzional honetan nola portatzen den sakonki aztertzen dugu, sarrera estandarrak, parametro-konbinazioak eta muga-balioak barne:

fn :: test io pipe timeout and eof => ()
      test io pipe timeout and eof =
        pt     = posix pipe
        rc     = pipe rc3 pt
        rfd    = pipe rfd3 pt
        wfd    = pipe wfd3 pt
        assert eq rc 0

        -- 1. Empty pipe read with 50 ms timeout must time out within [40, 300) ms (TS-PERF-001 AC2)
        t3     = sys monotonic ms
        r_to   = read fd rfd max 32 timeout 50
        t4     = sys monotonic ms
        dt     = t4 - t3
        assert str eq (format io result r_to) "err:timeout after 50 ms" "empty pipe read Timeout 50"
        assert true (dt >= 40 and dt < 300) "dt in [40, 300): {dt}"

        -- 2. Write payload via mixfix `write fd ... data ... timeout ...`
        w_res  = write fd wfd data "stream-ok" timeout 100
        assert str eq (format io result w_res) "ok:int:9" "write fd returns 9 bytes"

        -- 3. Read payload via mixfix `read fd ... max ... timeout ...`
        r_ok   = read fd rfd max 64 timeout 100
        assert str eq (format io result r_ok) "ok:str:stream-ok" "read fd returns stream-ok"

        -- 4. Close write end and verify subsequent read returns Eof
        posix close wfd -> ()
        r_eof  = read fd rfd max 64 timeout 100
        assert str eq (format io result r_eof) "err:unexpected end of file" "closed pipe read returns Eof"
        posix close rfd -> ()

        -- 5. Bad fd / invalid max_bytes
        r_bad  = read fd (0 - 1) max 64 timeout 50
        assert str eq (format io result r_bad) "err:syscall error 9 in read" "negative fd read SysErr 9"
        r_zero = read fd rfd max 0 timeout 50
        assert str eq (format io result r_zero) "err:syscall error 22 in read" "zero max_bytes read SysErr 22"
        ()

31.3.5. 5. adibidea: Azpiprozesuen exekuzio segurua denbora-muga zorrotzarekin (io exec timeout) eta ume-prozesuaren garbiketa automatikoa

Adibide praktiko honetan io bloke funtzional honetan nola portatzen den sakonki aztertzen dugu, sarrera estandarrak, parametro-konbinazioak eta muga-balioak barne:

fn :: test io exec timeout => ()
      test io exec timeout =
        ok_res = io exec timeout "true" 500
        assert str eq (format io result ok_res) "ok:int:0" "io exec timeout true succeeds"
        to_res = io exec timeout "sleep 2" 40
        assert str eq (format io result to_res) "err:timeout after 40 ms" "io exec timeout sleep 2 times out"
        ()

31.3.6. 6. adibidea: Fitxategi-sistemako predikatuak (file exists, is dir, is regular file, file size), lerrokako irakurketa (io read lines) eta kopia (copy file)

Adibide praktiko honetan io bloke funtzional honetan nola portatzen den sakonki aztertzen dugu, sarrera estandarrak, parametro-konbinazioak eta muga-balioak barne:

fn :: test io file and metadata => ()
      test io file and metadata =
        pid   = sys getpid
        dpath = "/tmp/rg_io_dir_{pid}"
        fpath = "{dpath}/file.txt"
        spath = "{dpath}/sym.txt"
        bpath = "{dpath}/bytes.bin"
        lpath = "{dpath}/lines.txt"

        sys rmdir dpath -> ()
        posix mkdir dpath -> ()
        assert true (is dir dpath) "is dir dpath"
        assert false (is file dpath) "not is file dpath"

        -- 1. write file + append file + read file
        write file fpath "hello "
        w2    = append file fpath "world"
        assert eq w2 0
        assert str eq (read file fpath) "hello world" "write_file + append_file content"

        -- 2. write_bytes + read_bytes
        write bytes bpath [65, 66, 67, 0, 255]
        rb    = read bytes bpath
        assert eq (int list len rb) 5

        -- 3. symlink + metadata predicates
        assert true (sys symlink fpath spath) "sys symlink fpath spath"
        assert true (file exists fpath) "file exists fpath"
        assert true (is file fpath) "is file fpath"
        assert false (is symlink fpath) "not is symlink fpath"
        assert true (is symlink spath) "is symlink spath"
        assert eq (file size fpath) 11
        assert true ((file mtime fpath) > 1700000000) "file mtime > 1700000000"
        assert true ((file mode fpath) > 0) "file mode > 0"
        assert false (file exists "/tmp/rg_io_nonexistent_999999.txt") "missing file exists False"

        -- 4. io read file safe + io write lines / io read lines
        miss  = io read file safe "/tmp/rg_io_missing_999.txt"
        assert str eq (format io result miss) "err:file not found: /tmp/rg_io_missing_999.txt" "NotFound missing file"
        hit   = io read file safe fpath
        assert str eq (format io result hit) "ok:str:hello world" "safe read existing file"

        io write lines lpath ["alpha", "beta", "gamma"] -> ()
        lines = io read lines lpath
        assert eq (str list len lines) 3

        -- 5. v0.9.5 PAL `io read with timeout` (`with timeout wait_ms do` + `sys open path 2048 0` + `sys poll fd 1 -1`)
        r_amb  = io read with timeout fpath 200_ms
        assert str eq (format io result r_amb) "ok:str:hello world" "io read with timeout 200_ms"
        r_miss = io read with timeout "/tmp/rg_io_missing_999.txt" 50_ms
        assert true (str starts with (format io result r_miss) "err:io error -") "io read with timeout missing file -> IoError"

        -- Cleanup
        sys unlink spath -> ()
        sys unlink fpath -> ()
        sys unlink bpath -> ()
        sys unlink lpath -> ()
        sys rmdir dpath -> ()
        ()

---

31.4. Kaputaren azpian: nola dagoen eraikia io Ridgun hutsean (src/main/ridgun/lib/io.rg)

ridgun-libs-en abantaila handienetako bat C-ko kutxa beltzik ez egotea da. src/main/ridgun/lib/io.rg ireki dezakezu eta eragiketa bakoitza pattern matching, | / |. guarda-zuhaitzak eta isats-errekurtsioa (TCO) erabiliz nola inplementatuta dagoen irakurri. Ikus ditzagun bere benetako inplementazioaren funtsezko piezak:

31.4.1. Barne-inplementazioa: Extensible I/O Error & Result Sum Types (§5.1)

Ikusi nola io.rg-ek lehenik fn :: ... => ... sinadurak egituratzen dituen eta kasu bakoitza lerrokatutako ekuazioen eta isats-deien bidez ebazten duen:

module :: io

type IoError = Timeout Int | Eof | SysErr Int String | NotFound String

type IoResult = String | Int | Timeout Int | Eof | SysErr Int String | NotFound String | IoErr IoError | IoOk String | IoTimeout | IoEof | IoError Int

fn :: format io error IoError            => String
      format io error (Timeout ms)       =  "timeout after {ms} ms"
      format io error Eof                =  "unexpected end of file"
      format io error (SysErr c op_name) =  "syscall error {c} in {op_name}"
      format io error (NotFound path)    =  "file not found: {path}"
      format io error _                  =  "unknown io error"

fn :: format io result IoResult           => String
      format io result (String s)         =  "ok:str:{s}"
      format io result (IoOk s)           =  "ok:str:{s}"
      format io result (Int n)            =  "ok:int:{n}"
      format io result (Timeout ms)       =  "err:timeout after {ms} ms"
      format io result IoTimeout          =  "err:timeout"
      format io result Eof                =  "err:unexpected end of file"
      format io result IoEof              =  "err:unexpected end of file"
      format io result (IoError c)        =  "err:io error {c}"
      format io result (SysErr c op_name) =  "err:syscall error {c} in {op_name}"
      format io result (NotFound path)    =  "err:file not found: {path}"
      format io result (IoErr err)        =  "err:" + (format io error err)
      format io result _                  =  "err:unknown io error"

31.4.2. Barne-inplementazioa: Timeout-Bounded Command Execution (§5.2)

Ikusi nola io.rg-ek lehenik fn :: ... => ... sinadurak egituratzen dituen eta kasu bakoitza lerrokatutako ekuazioen eta isats-deien bidez ebazten duen:

fn :: has null char String Int Int => Bool
      has null char s idx slen =
        | idx >= slen              = False
        | (str char at s idx) == 0 = True
        | otherwise                = has null char s (idx + 1) slen

fn :: pad ms three Int => String
      pad ms three rem =
        | rem < 10  = "00{rem}"
        | rem < 100 = "0{rem}"
        | otherwise = "{rem}"

fn :: format timeout sec Int => String
      format timeout sec ms  =
        secs = ms / 1000
        rem  = ms % 1000
        p    = pad ms three rem
        "{secs}.{p}s"

fn :: map exec rc Int Int        => IoResult
      map exec rc rc  timeout_ms =
        | rc == 124 or rc == 137 = Timeout timeout_ms
        | rc < 0                 = SysErr (0 - rc) "exec"
        | otherwise              = Int rc

fn :: io exec timeout String Int        => IoResult
      io exec timeout cmd    timeout_ms =
        | (str len cmd) == 0 or (has null char cmd 0 (str len cmd)) = SysErr 22 "exec"
        | timeout_ms <= 0                                           = Timeout timeout_ms
        | otherwise                                                 =
          tspec = format timeout sec timeout_ms
          rc    = shell exec "timeout -k 0.01s {tspec} sh -c \"{cmd}\" >/dev/null 2>&1"
          map exec rc rc timeout_ms

fn :: exec with timeout String Int        => IoResult
      exec with timeout cmd    timeout_ms =
        io exec timeout cmd timeout_ms

31.4.3. Barne-inplementazioa: Safe File Read & Line-Stream Helpers

Ikusi nola io.rg-ek lehenik fn :: ... => ... sinadurak egituratzen dituen eta kasu bakoitza lerrokatutako ekuazioen eta isats-deien bidez ebazten duen:

fn :: io read file safe String => IoResult
      io read file safe path   =
        | not (is safe posix path path)        = SysErr 22 "read_file"
        | not (lstat exists (file lstat path)) = NotFound path
        | otherwise                            = String (read file path)

fn :: split lines loop String Int Int Int => [String]
      split lines loop s idx start slen =
        | idx >= slen =
          | start == slen = []
          | otherwise     = [str slice s start slen] |.
        | (str char at s idx) == 10 =
          line = str slice s start idx
          [line] :: (split lines loop s (idx + 1) (idx + 1) slen)
        | otherwise =
          split lines loop s (idx + 1) start slen

fn :: split non empty lines String Int => [String]
      split non empty lines raw rlen =
        | rlen == 0 = []
        | otherwise = split lines loop raw 0 0 rlen

fn :: io read lines String => [String]
      io read lines path   =
        | not (is safe posix path path)        = []
        | not (lstat exists (file lstat path)) = []
        | otherwise                            =
          raw = read file path
          split non empty lines raw (str len raw)

fn :: str list is empty [String] => Bool
      str list is empty []       =  True
      str list is empty (_:_)    =  False

fn :: join lines nl [String]    => String
      join lines nl []          =  ""
      join lines nl (line:rest) =
        | str list is empty rest = line + "\n"
        | otherwise              = line + "\n" + (join lines nl rest)

fn :: io write lines step String [String] => Int
      io write lines step path   lines    =
        lines join lines nl -> body
        write file path body
        0

fn :: io write lines String [String] => Int
      io write lines path   lines    =
        | not (is safe posix path path) = 0 - 22
        | otherwise                     = io write lines step path lines

31.4.4. Barne-inplementazioa: Ridgun v0.9.5 PAL & Ambient Deadline io read with timeout (§3.1)

Ikusi nola io.rg-ek lehenik fn :: ... => ... sinadurak egituratzen dituen eta kasu bakoitza lerrokatutako ekuazioen eta isats-deien bidez ebazten duen:

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

fn :: io close and return Int IoResult => IoResult
      io close and return fd  res      =
        sys close fd -> ()
        res

fn :: io read chunk and close Int => IoResult
      io read chunk and close fd  =
        sys read fd fd 65536 -> chunk
        sys close fd -> ()
        chunk io wrap chunk

fn :: io read after poll Int Int => IoResult
      io read after poll fd ev =
        | ev == 0   = io close and return fd IoTimeout
        | ev < 0    = io close and return fd (IoError ev)
        | otherwise = io read chunk and close fd

fn :: io poll and read Int => IoResult
      io poll and read fd  =
        sys poll fd 1 (0 - 1) -> ev
        io read after poll fd ev

fn :: io read poll step Int => IoResult
      io read poll step fd  =
        | fd < 0    = IoError fd
        | otherwise = io poll and read fd

fn :: io read with timeout String Int => IoResult
      io read with timeout path wait_ms =
        with timeout wait_ms do
          fd = sys open path 2048 0
          io read poll step fd

---

31.5. Berme algoritmikoak, RMM1/RMM2 memoria eta io-en Urrezko 5 Arauak

• Berme algoritmikoa eta segurtasunekoa: wait_ms kuotarekin io bidez exekutatutako inongo irakurketa, idazketa edo komandok ezin du deitzen duen haria edo aktorea mugagabe blokeatu.
• $O(1)$ pila-konplexutasuna TCOrekin: src/main/ridgun/lib/io.rg-eko begizta errekurtsibo guztiak isats-posizioan daude; beraz, ridgunc-ek pila-hazkuntzarik gabeko jauzi natiboetara konpilatzen ditu.
• Memoria determinista (RMM1/RMM2): Zero zabor-biltzaile etenaldi; tarteko egitura guztiak modu deterministan askatzen dira esparrutik irtetean.
• Etengabeko egiaztapena: Zorrotz probatua stable check eta src/test/ridgun/test io.rg suite automatizatuaren bidez.

io-ekin programatzeko Urrezko 5 Arauak

1. Deklaratu import io fitxategiaren hasieran eta baliatu zuriuneen eta azpimarren arteko baliokidetasuna zure kodea prosa bezala irakur dadin.
2. Lerrokatu zure datu-hodiak = ikurrarekin: kateatu io-erako deiak izen propioko urratsetan eta utzi stable format-i zutabeak lerrokatzen.
3. Baliatu io-eko funtzio osoak zure | guardetan: egiaztatu itzulera-balioak edo askatu ADTak pattern matching bidez, kanpoko sarrera beti baliozkoa dela suposatu beharrean.
4. Saihestu egitura handiak kopiatzea eremu bat kontsultatu besterik behar ez baduzu: gogoratu RMM2-n sarrerako argumentuek ez dituztela kontagailuak handitzen edo txikitzen (+0 / -0).
5. Konbinatu io eta test (import test): idatzi beti asertzioak assert equals edo assert true erabiliz zure domeinuaren inbarianteak finkatzeko.

---

32. kapituluan crypto lib-a sakonki esploratuko dugu (crypto lib-a — SHA-256, HMAC, PBKDF2, Argon2id eta ChaCha20-Poly1305 AEAD).