38 Ridgun Liburua

`agent` lib-a — Aktoreen Eredu Natiboa (`agent`, `send`, `receive`), KV Biltegia eta Rate Limiter-a

38.1. Zergatik existitzen da `agent` lib-a? (Benetako arazoa eta Ridgun filosofia)

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

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

Izan gaitezen zintzoak: harien artean memoria aldakorra Mutex, RwLock eta baldintza-aldagaiekin partekatzea deadlock eta lasterketa-baldintzen fabrika agortezina da.

agent lib-ak Ridgunen Agenteen Eredu Natiboa (agent, send ... to, receive from, try receive from, stop) baliatzen du Copy-on-Write mezu-igorpenezko postontzi isolatuak, gako-balio biltegi konkurrente bat (KvStore), token-ontzi bidezko tasa-mugatzaile bat (RateBucket) eta egoera-gainbegiratzea (AgentHealth) eskaintzeko.

Ekosistema tradizional batean, AGENT 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, agent lib-ak (src/main/ridgun/lib/agent.rg) lau printzipio negoziatu ezinekin heltzen dio arazoari:

Deklaratu import agent (edo import agent as alias) fitxategiaren hasieran: lib bakoitzak module :: agent izen-espazioa definitzen du eta --strict moduan hitz anitzeko funtzioei zuriune naturalekin deitzen zaie beti.
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).
Isats-errekurtsioa TCOrekin (Tail-Call Optimization): agent-eko barne-ibilbide guztiak $O(1)$ pila-espazioko begizta natiboetara konpilatzen dira.
Memoria determinista (RMM1 / RMM2): tarteko egitura bakoitza bere azken irakurketa amaitzen den une zehatzean askatzen da, Garbage Collector gabe.

38.2. Artefaktu natiboak, inportazioa eta `agent` APIaren katalogo osoa

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

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

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

38.2.1. `agent`-eko familia funtzionalen laburpena

Sinadura / Funtzioa / Mota	Zer egiten duen eta noiz erabili
`agent roundtrip / agent drain count`	Aktore natiboak (`agent`) abiarazi, mezuak trukatu (`send ... to` / `receive from`) eta `stop` egiten du
`kv store new / kv store apply`	Aktoreentzako gako-balio biltegi aldaezina (`KvPut`, `KvGet`, `KvDelete`, `KvClear`)
`rate bucket new / rate bucket allow`	Token-ontzi bidezko tasa-mugatzailea, ontzi eguneratua eta `(allowed, remaining)` itzultzen dituena
`sup mark failed / sup should restart`	Berrabiarazte-aurrekontua (`max_restarts`) kontrolatzen duten gainbegiratze-politikak

38.2.2. `src/main/ridgun/lib/agent.rg`-eko mota eta sinadura guztien katalogoa

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

agent-eko mota aljebraikoak eta erregistroak (type):

type AgentStatus = AgentRunning | AgentStopped | AgentTimedOut Int | AgentFailed String
type AgentReply  = ReplyInt Int | ReplyStr String | ReplyBool Bool | ReplyEmpty | ReplyStopped | ReplyTimeout Int | ReplyError String
type CounterState = cnt_val: Int
type KvCmd        = KvPut String String | KvGet String | KvDel String | KvHas String | KvCount | KvKeys | KvClear
type KvEntry      = kv_k: String, kv_v: String
type KvState      = kv_size: Int, kv_items: [KvEntry]
type LogState     = log_sep: String, log_buf: String

#	Funtzioa / Sinadura (`fn ::`)	Itzulera-mota
`1`	`fn :: format agent status AgentStatus`	`String`
`2`	`fn :: format agent reply AgentReply`	`String`
`3`	`fn :: is agent alive (Agent A B)`	`Bool`
`4`	`fn :: agent status (Agent A B)`	`AgentStatus`
`5`	`fn :: stop agent (Agent A B)`	`AgentStatus`
`6`	`fn :: agent stop all [Agent]`	`()`
`7`	`fn :: agent ask Agent A`	`B`
`8`	`fn :: agent try ask Agent A`	`Option`
`9`	`fn :: agent send batch Agent [A]`	`()`
`10`	`fn :: agent receive count Agent Int`	`[B]`
`11`	`fn :: agent receive count loop Agent Int [B]`	`[B]`
`12`	`fn :: agent map batch Agent [A]`	`[B]`
`13`	`fn :: agent list len [A] Int`	`Int`
`14`	`fn :: agent drain ready Agent`	`[B]`
`15`	`fn :: agent drain ready loop Agent [B]`	`[B]`
`16`	`fn :: agent drain step Agent Option [B]`	`[B]`
`17`	`fn :: ag cast opt A`	`B`
`18`	`fn :: ag unwrap try int (Option Int)`	`AgentReply`
`19`	`fn :: ag unwrap try str (Option String)`	`AgentReply`
`20`	`fn :: ask int (Agent Int Int) Int`	`AgentReply`
`21`	`fn :: ask str (Agent String String) String`	`AgentReply`
`22`	`fn :: try poll int (Agent A Int)`	`AgentReply`
`23`	`fn :: try poll str (Agent A String)`	`AgentReply`
`24`	`fn :: ag poll int step (Agent Int Int) (Option Int) Int Int`	`AgentReply`
`25`	`fn :: ag wait int loop (Agent Int Int) Int Int`	`AgentReply`
`26`	`fn :: ask int with timeout (Agent Int Int) Int Int`	`AgentReply`
`27`	`fn :: ag poll str step (Agent String String) (Option String) Int Int`	`AgentReply`
`28`	`fn :: ag wait str loop (Agent String String) Int Int`	`AgentReply`
`29`	`fn :: ask str with timeout (Agent String String) String Int`	`AgentReply`
`30`	`fn :: ask batch int (Agent Int Int) [Int]`	`[Int]`
`31`	`fn :: ask batch str (Agent String String) [String]`	`[String]`
`32`	`fn :: relay int (Agent Int Int) (Agent Int Int) Int`	`AgentReply`
`33`	`fn :: relay str (Agent String String) (Agent String String) String`	`AgentReply`
`34`	`fn :: ag counter step CounterState Int`	`CounterState Int`
`35`	`fn :: new counter agent Int`	`Agent Int Int`
`36`	`fn :: counter add (Agent Int Int) Int`	`Int`
`37`	`fn :: counter get (Agent Int Int)`	`Int`
`38`	`fn :: counter reset (Agent Int Int)`	`Int`
`39`	`fn :: ag log join String String String`	`String`
`40`	`fn :: ag log step LogState String`	`LogState String`
`41`	`fn :: new log agent String`	`Agent String String`
`42`	`fn :: log append (Agent String String) String`	`String`
`43`	`fn :: log read (Agent String String)`	`String`
`44`	`fn :: log clear (Agent String String)`	`String`
`45`	`fn :: ag kv lookup [KvEntry] String`	`String`
`46`	`fn :: ag kv exists [KvEntry] String`	`Bool`
`47`	`fn :: ag kv put list [KvEntry] String String`	`[KvEntry]`
`48`	`fn :: ag kv del list [KvEntry] String`	`[KvEntry]`
`49`	`fn :: ag kv len [KvEntry]`	`Int`
`50`	`fn :: ag kv keys join String String`	`String`
`51`	`fn :: ag kv keys str [KvEntry]`	`String`
`52`	`fn :: ag kv has str Bool`	`String`
`53`	`fn :: ag kv next state KvState KvCmd`	`KvState`
`54`	`fn :: ag kv next reply KvState KvCmd`	`String`
`55`	`fn :: ag kv step KvState KvCmd`	`KvState String`
`56`	`fn :: new kv agent`	`Agent KvCmd String`
`57`	`fn :: ag kv call (Agent KvCmd String) KvCmd`	`String`
`58`	`fn :: kv put (Agent KvCmd String) String String`	`String`
`59`	`fn :: kv get (Agent KvCmd String) String`	`String`
`60`	`fn :: kv delete (Agent KvCmd String) String`	`String`
`61`	`fn :: kv has (Agent KvCmd String) String`	`Bool`
`62`	`fn :: ag parse int String`	`Int`
`63`	`fn :: kv count (Agent KvCmd String)`	`Int`
`64`	`fn :: kv keys (Agent KvCmd String)`	`String`
`65`	`fn :: kv clear (Agent KvCmd String)`	`String`

38.3. `agent` sakonki esploratzen: Funtzionalitate bakoitzaren urratsez urratseko adibideak

Ez da nahikoa sinadura-taula ikustea: agent 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 agent.rg-en egiaztatutako agertoki funtzional eta muga-kasu guztiak.

38.3.1. 1. adibidea: Fluxu nagusia estilo taularatuan `agent` erabiliz

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

import agent

fn :: probar contador actor => Int Int
      probar contador actor =
        10 new counter agent -> ag
        counter add ag 32 -> v1
        ag counter get -> v2
        ag stop agent -> ()
        (v1, v2)

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

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

import agent

fn :: consultar almacen kv => String Int
      consultar almacen kv =
        new kv agent -> kv
        kv put kv "modo" "produccion" -> ()
        kv get kv "modo" -> modo
        kv count kv -> total
        kv stop agent -> ()
        (modo, total)

38.3.3. 3. adibidea: Aktore-konbinatzaileak (`agent ask`, `try ask`, `send batch`, `map batch`, `drain ready`), zatikatutako pool-ak eta konexio-erreaktorea

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

fn :: test spec combinators pool and net agent => ()
      test spec combinators pool and net agent =
        w1 = agent (ag double worker)
        assert int equals (agent ask w1 21) 42 "agent ask 21 -> 42"
        mb = agent map batch w1 [3, 5, 7]
        assert int equals (ag sum ints mb) 30 "agent map batch [3,5,7] -> [6,10,14] sum 30"
        agent send batch w1 [10, 20] -> ()
        rc = agent receive count w1 2
        assert int equals (ag sum ints rc) 60 "agent send batch + agent receive count -> 60"
        c_dr = new counter agent 100
        send 5 to c_dr
        send 10 to c_dr
        dr = agent drain ready c_dr
        assert int equals (ag sum ints dr) 220 "agent drain ready [105, 115] -> 220"
        agent stop all [w1, c_dr] -> ()
        assert false (is agent alive w1) "w1 stopped by agent stop all"
        assert false (is agent alive c_dr) "c_dr stopped by agent stop all"

        s0 = new counter agent 0
        s1 = new counter agent 1000
        pl = Pool 2 [s0, s1]
        assert int equals (pool size pl) 2 "pool size 2"
        assert int equals (pool ask shard pl 0 5) 5 "pool ask shard 0 -> 5"
        assert int equals (pool ask shard pl 1 7) 1007 "pool ask shard 1 -> 1007"
        assert int equals (pool ask shard pl (0 - 3) 3) 1010 "pool ask shard negative key -> shard 1"
        pool broadcast pl 10 -> ()
        all_dr = pool drain all pl
        assert int equals (ag sum ints all_dr) 1035 "pool drain all [15, 1020] -> 1035"
        pool shutdown pl -> ()
        assert false (is agent alive s0) "pool s0 stopped"
        assert false (is agent alive s1) "pool s1 stopped"

        ca = agent (ag echo conn step) (CounterState 0)
        cb = agent (ag echo conn step) (CounterState 0)
        s_eof = conn feed payload (0 - 1) ca ""
        s_err = conn handle event (0 - 1) cb 8
        kept  = reactor sweep next s_eof (reactor sweep next s_err [])
        assert int equals (agent list len kept 0) 0 "reactor sweep next prunes closed slots"
        assert false (is agent alive ca) "ca stopped on EOF"
        assert false (is agent alive cb) "cb stopped on POLLERR"
        cc = agent (ag echo conn step) (CounterState 0)
        reactor shutdown [ConnSlot (0 - 1) cc] -> ()
        assert false (is agent alive cc) "cc stopped on reactor shutdown"

38.3.4. 4. adibidea: Agenteen bizi-zikloa (`is agent alive`, `agent status`, `stop agent`) eta egoera isolatuko agente kontagailua (`new counter agent`)

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

fn :: test agent lifecycle and counter => ()
      test agent lifecycle and counter =
        assert str eq (format agent status AgentRunning) "running" "format AgentRunning"
        assert str eq (format agent status AgentStopped) "stopped" "format AgentStopped"
        assert str eq (format agent status (AgentTimedOut 250)) "timeout after 250 ms" "format AgentTimedOut"
        assert str eq (format agent status (AgentFailed "boom")) "failed: boom" "format AgentFailed"
        assert str eq (format agent reply (ReplyInt 42)) "42" "format ReplyInt"
        assert str eq (format agent reply (ReplyStr "ok")) "ok" "format ReplyStr"
        assert str eq (format agent reply (ReplyBool True)) "true" "format ReplyBool True"
        assert str eq (format agent reply (ReplyBool False)) "false" "format ReplyBool False"
        assert str eq (format agent reply ReplyEmpty) "agent outbox empty" "format ReplyEmpty"
        assert str eq (format agent reply ReplyStopped) "agent stopped" "format ReplyStopped"
        assert str eq (format agent reply (ReplyTimeout 50)) "agent timeout after 50 ms" "format ReplyTimeout"
        assert str eq (format agent reply (ReplyError "bad")) "agent error: bad" "format ReplyError"

        c   = new counter agent 10
        assert ok (is agent alive c)
        assert str eq (format agent status (agent status c)) "running" "counter running"
        assert str eq (format agent reply (try poll int c)) "agent outbox empty" "empty outbox before send"
        assert eq (counter get c) 10
        assert eq (counter add c 5) 15
        assert eq (counter add c 7) 22
        assert str eq (format agent reply (ask int c 8)) "30" "ask int 8 -> 30"
        assert str eq (format agent reply (ask int with timeout c 12 200)) "42" "ask int with timeout -> 42"
        assert eq (counter reset c) 0
        assert eq (counter get c) 0
        bs  = ask batch int c [1, 2, 3, 4]
        assert eq (ag sum ints bs) 20

        c2  = new counter agent 100
        rel = relay int c c2 5
        assert str eq (format agent reply rel) "115" "relay int c (10+5=15) -> c2 (100+15=115)"

        st1 = stop agent c
        assert str eq (format agent status st1) "stopped" "stop agent returns AgentStopped"
        assert eq (is agent alive c) False
        assert str eq (format agent status (agent status c)) "stopped" "agent status after stop"
        assert str eq (format agent reply (ask int c 1)) "agent stopped" "ask int after stop"
        assert str eq (format agent reply (try poll int c)) "agent stopped" "try poll int after stop"
        assert str eq (format agent reply (ask int with timeout c 1 50)) "agent stopped" "ask int with timeout after stop"
        assert str eq (format agent reply (relay int c c2 1)) "agent stopped" "relay int after stop"
        c0  = new counter agent 0
        assert int equals (counter get c0) 0 "counter 0 initial"
        assert int equals (counter add c0 3) 3 "counter 0 add 3"
        stop agent c0
        stop agent c2
        assert eq (is agent alive c2) False

38.3.5. 5. adibidea: Append-only egunkari-agentea (`new log agent`) eta mezu-igorpenezko memoriako gako-balio biltegia (`new kv agent`)

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

fn :: test log and kv agents => ()
      test log and kv agents =
        lg  = new log agent "\n"
        assert ok (is agent alive lg)
        assert str eq (format agent reply (try poll str lg)) "agent outbox empty" "log empty outbox"
        assert str eq (log read lg) "" "initial log empty"
        assert str eq (log append lg "alpha") "alpha" "log append alpha"
        assert str eq (log append lg "beta") "alpha\nbeta" "log append beta"
        assert str eq (format agent reply (ask str with timeout lg "gamma" 200)) "alpha\nbeta\ngamma" "ask str with timeout gamma"
        assert str eq (log read lg) "alpha\nbeta\ngamma" "log read"
        assert str eq (log clear lg) "" "log clear"
        assert str eq (log read lg) "" "log read after clear"
        b   = ask batch str lg ["one", "two"]
        assert str eq (ag join strs b) "one|one\ntwo" "ask batch str"
        lg2 = new log agent ":"
        assert str eq (format agent reply (relay str lg lg2 "three")) "one\ntwo\nthree" "relay str"
        stop agent lg
        stop agent lg2
        assert str eq (format agent reply (ask str lg "x")) "agent stopped" "ask str after stop"

        kv  = new kv agent
        assert ok (is agent alive kv)
        assert int equals (kv count kv) 0 "kv count 0"
        assert false (kv has kv "host") "kv has host false"
        assert str eq (kv put kv "host" "127.0.0.1") "127.0.0.1" "kv put host"
        assert str eq (kv put kv "port" "8080") "8080" "kv put port"
        assert int equals (kv count kv) 2 "kv count 2"
        assert ok (kv has kv "host")
        assert ok (kv has kv "port")
        assert str eq (kv get kv "host") "127.0.0.1" "kv get host"
        assert str eq (kv get kv "port") "8080" "kv get port"
        assert str eq (kv keys kv) "host,port" "kv keys"
        assert str eq (kv put kv "port" "9090") "9090" "kv overwrite port"
        assert str eq (kv get kv "port") "9090" "kv get updated port"
        assert int equals (kv count kv) 2 "kv count after overwrite"
        assert str eq (kv delete kv "host") "127.0.0.1" "kv delete host"
        assert false (kv has kv "host") "kv has host after delete"
        assert int equals (kv count kv) 1 "kv count 1"
        assert str eq (kv clear kv) "" "kv clear"
        assert int equals (kv count kv) 0 "kv count after clear"
        stop agent kv
        assert false (is agent alive kv) "kv stopped"

38.4. Kaputaren azpian: nola dagoen eraikia `agent` Ridgun hutsean (`src/main/ridgun/lib/agent.rg`)

ridgun-libs-en abantaila handienetako bat C-ko kutxa beltzik ez egotea da. src/main/ridgun/lib/agent.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:

38.4.1. Barne-inplementazioa: Status & Reply Formatting

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

module :: agent

fn :: format agent status AgentStatus        => String
      format agent status AgentRunning       =  "running"
      format agent status AgentStopped       =  "stopped"
      format agent status (AgentTimedOut ms) =  "timeout after {ms} ms"
      format agent status (AgentFailed   msg) = "failed: {msg}"

fn :: format agent reply AgentReply        => String
      format agent reply (ReplyInt     n)  =  int to str n
      format agent reply (ReplyStr     s)  =  s
      format agent reply (ReplyBool True)  =  "true"
      format agent reply (ReplyBool False) =  "false"
      format agent reply ReplyEmpty        =  "agent outbox empty"
      format agent reply ReplyStopped      =  "agent stopped"
      format agent reply (ReplyTimeout ms) =  "agent timeout after {ms} ms"
      format agent reply (ReplyError  msg) =  "agent error: {msg}"

38.4.2. Barne-inplementazioa: Core Combinators (`agent ask`, `agent try ask`, `agent send batch`, `agent receive count`, `agent map batch`, `agent drain ready`)

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

fn :: agent ask Agent A   => B
      agent ask ag    msg =  ask ag msg

fn :: agent try ask Agent A   => Option
      agent try ask ag    msg =
        send msg to ag
        try receive from ag

fn :: agent send batch Agent [A]      => ()
      agent send batch _     []       =  ()
      agent send batch ag    (m:rest) =
        send m to ag
        agent send batch ag rest

fn :: agent receive count Agent Int   => [B]
      agent receive count ag    count =  agent receive count loop ag count []

fn :: agent receive count loop Agent Int [B] => [B]
      agent receive count loop ag count acc
        | count <= 0 = acc
        | otherwise =
          r = receive from ag
          agent receive count loop ag (count - 1) (acc :: [r])

fn :: agent map batch Agent [A]  => [B]
      agent map batch ag    msgs =
        agent list len msgs 0 -> n
        agent send batch ag msgs -> ()
        agent receive count ag n

fn :: agent list len [A]    Int => Int
      agent list len []     acc =  acc
      agent list len (_:xs) acc =  agent list len xs (acc + 1)

fn :: agent drain ready Agent => [B]
      agent drain ready ag    =  agent drain ready loop ag []

fn :: agent drain ready loop Agent [B] => [B]
      agent drain ready loop ag acc =
        agent drain step ag (try receive from ag) acc

fn :: agent drain step Agent Option [B] => [B]
      agent drain step _ None acc = acc
      agent drain step ag (Some r) acc = agent drain ready loop ag (acc :: [r])

38.4.3. Barne-inplementazioa: Stateful Counter Agent (`new counter agent`, `counter add`, `counter get`, `counter reset`)

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

fn :: ag counter step CounterState Int   => CounterState Int
      ag counter step st           delta =
        | delta == (0 - 999999999) = (CounterState 0, 0)
        | otherwise                =
          nxt = (cnt_val st) + delta
          (CounterState nxt, nxt)

fn :: new counter agent Int  => Agent Int Int
      new counter agent init =  agent (ag counter step) (CounterState init)

fn :: counter add (Agent Int Int) Int   => Int
      counter add ag              delta =
        | not (agent alive ag) = 0
        | otherwise            =
          _ = send delta to ag
          receive from ag

fn :: counter get (Agent Int Int) => Int
      counter get ag              =  counter add ag 0

fn :: counter reset (Agent Int Int) => Int
      counter reset ag              =  counter add ag (0 - 999999999)

38.4.4. Barne-inplementazioa: Stateful In-Memory Key-Value Agent (`new kv agent`, `kv put`, `kv get`, `kv delete`, `kv has`, `kv count`, `kv keys`, `kv clear`)

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

fn :: ag kv lookup [KvEntry] String => String
      ag kv lookup []        _      =  ""
      ag kv lookup (e:rest)  key    =
        | (kv_k e) == key = kv_v e
        | otherwise       = ag kv lookup rest key

fn :: ag kv exists [KvEntry] String => Bool
      ag kv exists []        _      =  False
      ag kv exists (e:rest)  key    =
        | (kv_k e) == key = True
        | otherwise       = ag kv exists rest key

fn :: ag kv put list [KvEntry] String String => [KvEntry]
      ag kv put list [] key val = [KvEntry key val]
      ag kv put list (e:rest) key val =
        | (kv_k e) == key = [KvEntry key val] :: rest
        | otherwise       = [e] :: (ag kv put list rest key val)

fn :: ag kv del list [KvEntry] String => [KvEntry]
      ag kv del list [] _ = []
      ag kv del list (e:rest) key =
        | (kv_k e) == key = rest
        | otherwise       = [e] :: (ag kv del list rest key)

fn :: ag kv len [KvEntry] => Int
      ag kv len []        =  0
      ag kv len (_:rest)  =  1 + (ag kv len rest)

fn :: ag kv keys join String String => String
      ag kv keys join k rest_s =
        | (str len rest_s) == 0 = k
        | otherwise             = k + "," + rest_s

fn :: ag kv keys str [KvEntry] => String
      ag kv keys str []        =  ""
      ag kv keys str (e:rest)  =  ag kv keys join (kv_k e) (ag kv keys str rest)

fn :: ag kv has str Bool  => String
      ag kv has str True  =  "1"
      ag kv has str False =  "0"

38.5. Berme algoritmikoak, `RMM1`/`RMM2` memoria eta `agent`-en Urrezko 5 Arauak

Berme algoritmikoa eta segurtasunekoa: Zero memoria aldakor partekatu aktoreen artean: mezu bakoitza balioz / Copy-on-Write bidez transferitzen da eta stop-ek agentearen eskualdea modu deterministan askatzen du.
$O(1)$ pila-konplexutasuna TCOrekin: src/main/ridgun/lib/agent.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 agent.rg suite automatizatuaren bidez.

`agent`-ekin programatzeko Urrezko 5 Arauak

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

39. kapituluan pool lib-a sakonki esploratuko dugu (pool lib-a — Langileen Pool Mugatua, Round-Robin eta Lan-lapurreta).

agent lib-a — Aktoreen Eredu Natiboa (agent, send, receive), KV Biltegia eta Rate Limiter-a

38.1. Zergatik existitzen da agent lib-a? (Benetako arazoa eta Ridgun filosofia)

38.2. Artefaktu natiboak, inportazioa eta agent APIaren katalogo osoa

38.2.1. agent-eko familia funtzionalen laburpena

38.2.2. src/main/ridgun/lib/agent.rg-eko mota eta sinadura guztien katalogoa

38.3. agent sakonki esploratzen: Funtzionalitate bakoitzaren urratsez urratseko adibideak

38.3.1. 1. adibidea: Fluxu nagusia estilo taularatuan agent erabiliz

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

38.3.3. 3. adibidea: Aktore-konbinatzaileak (agent ask, try ask, send batch, map batch, drain ready), zatikatutako pool-ak eta konexio-erreaktorea

38.3.4. 4. adibidea: Agenteen bizi-zikloa (is agent alive, agent status, stop agent) eta egoera isolatuko agente kontagailua (new counter agent)

38.3.5. 5. adibidea: Append-only egunkari-agentea (new log agent) eta mezu-igorpenezko memoriako gako-balio biltegia (new kv agent)

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

38.4.1. Barne-inplementazioa: Status & Reply Formatting

38.4.2. Barne-inplementazioa: Core Combinators (agent ask, agent try ask, agent send batch, agent receive count, agent map batch, agent drain ready)

38.4.3. Barne-inplementazioa: Stateful Counter Agent (new counter agent, counter add, counter get, counter reset)

38.4.4. Barne-inplementazioa: Stateful In-Memory Key-Value Agent (new kv agent, kv put, kv get, kv delete, kv has, kv count, kv keys, kv clear)

38.5. Berme algoritmikoak, RMM1/RMM2 memoria eta agent-en Urrezko 5 Arauak

agent-ekin programatzeko Urrezko 5 Arauak

`agent` lib-a — Aktoreen Eredu Natiboa (`agent`, `send`, `receive`), KV Biltegia eta Rate Limiter-a

38.1. Zergatik existitzen da `agent` lib-a? (Benetako arazoa eta Ridgun filosofia)

38.2. Artefaktu natiboak, inportazioa eta `agent` APIaren katalogo osoa

38.2.1. `agent`-eko familia funtzionalen laburpena

38.2.2. `src/main/ridgun/lib/agent.rg`-eko mota eta sinadura guztien katalogoa

38.3. `agent` sakonki esploratzen: Funtzionalitate bakoitzaren urratsez urratseko adibideak

38.3.1. 1. adibidea: Fluxu nagusia estilo taularatuan `agent` erabiliz

38.3.3. 3. adibidea: Aktore-konbinatzaileak (`agent ask`, `try ask`, `send batch`, `map batch`, `drain ready`), zatikatutako pool-ak eta konexio-erreaktorea

38.3.4. 4. adibidea: Agenteen bizi-zikloa (`is agent alive`, `agent status`, `stop agent`) eta egoera isolatuko agente kontagailua (`new counter agent`)

38.3.5. 5. adibidea: Append-only egunkari-agentea (`new log agent`) eta mezu-igorpenezko memoriako gako-balio biltegia (`new kv agent`)

38.4. Kaputaren azpian: nola dagoen eraikia `agent` Ridgun hutsean (`src/main/ridgun/lib/agent.rg`)

38.4.2. Barne-inplementazioa: Core Combinators (`agent ask`, `agent try ask`, `agent send batch`, `agent receive count`, `agent map batch`, `agent drain ready`)

38.4.3. Barne-inplementazioa: Stateful Counter Agent (`new counter agent`, `counter add`, `counter get`, `counter reset`)

38.4.4. Barne-inplementazioa: Stateful In-Memory Key-Value Agent (`new kv agent`, `kv put`, `kv get`, `kv delete`, `kv has`, `kv count`, `kv keys`, `kv clear`)

38.5. Berme algoritmikoak, `RMM1`/`RMM2` memoria eta `agent`-en Urrezko 5 Arauak

`agent`-ekin programatzeko Urrezko 5 Arauak