code wiki / (root) / nx_swarm_job.nx

nx_swarm_job.nx

buildroot/runtime/nx_swarm_job.nx

22056 B483 linesdepth 4pulls 4 transitivereach 0 importersview sourcekind tooltopic swarm
docsdependenciesstructsconstsfunctions

about

nx_swarm_job.nx -- SWARM FABRIC job engine (SF-R3): decompose a chunky GEN job into independent chunks and run them across opportunistic heterogeneous devices, straggler-proof + crash-safe. The north-star compute substrate ("unified supercomputer for gen, any device") -- GREENFIELD from OUR primitives, NOT a Ray/K3s clone. THE DESIGN (durable-execution + speculative-execution fused, shared-nothing): * DURABLE COMPLETION JOURNAL -- the ONLY thing that must survive a crash. A chunk is DONE iff a "DONE <cid>" record exists (framed-append floor = flock'd, torn-write-proof). You never re-run a completed chunk, ever. * TRANSIENT O_EXCL LEASES -- a chunk is LEASED iff a fresh "<lockdir>/<job>.<cid>.lease" lockfile exists (O_CREAT|O_EXCL = exactly one claimer wins, the dispatch_lease idiom). The lockfile is stamped with a DEADLINE; a contender STEALS an expired lease (straggler / crashed holder). A hub crash simply loses the lockfiles -> every in-flight chunk returns to PENDING = CORRECT. * SPECULATIVE HARVEST -- whichever node completes a chunk FIRST wins; a duplicate complete of an already-DONE chunk is IGNORED (idempotent). So a slow straggler racing its speculative re-lease never corrupts the result and never stalls the job (ray.wait's "any finishes" -- but journaled). COMPOSES (check-before-build 2026-07-15): the O_EXCL+stale-steal lease = the PROVEN nx_dispatch_lease mechanism (generalized fixed DL_STALE_SEC -> per-lease deadline); the journal floor = nx_framed_append; row/read/parse helpers = nx_swarm_lib. Placement (which node) = the SEPARATE nx_swarm_place organ, composed by the DRIVER (rule 9 single-responsibility: this organ queues; place picks; a script wires). submit <journal.log> <njobs> -- define the chunk universe 0..njobs-1 lease <journal.log> <lockdir> <job> <njobs> <ttl_s> -- claim the next PENDING/stale chunk (O_EXCL) complete <journal.log> <lockdir> <job> <cid> <node> -- durable DONE (idempotent; dup -> IGNORED) status <journal.log> <lockdir> <job> <njobs> -- done/leased/pending + COMPLETE verdict harvest <journal.log> <lockdir> <job> <njobs> <ttl> <node> [maxiter] -- in-proc drain (sim exec) [gate] -- self-gate, 8 tests incl liar-killers PATH LAW: journal must pass sb_path_ok (.log); lockdir must be a bare name or under /tmp/. license_tier: ORIGINAL expect_exit:0

dependencies 1 imports · 0 importers

nx_swarm_lib.nx nx_swarm_job.nx

imports: nx_swarm_lib.nx

imported by: nobody (leaf or entry point)

call flow from main pre-order; caps 40 nodes / depth 6 declared; ↻ = already shown

main sj_eq sj_puts fa_len sb_path_ok fa_len ↻ sb_pint fa_len ↻ sj_submit fa_cat fa_catn sys_mmap fa_append sys_mmap ↻ sys_openat_append sys_flock fa_write_all sys_write sys_close sj_lockdir_ok fa_len ↻ sj_lease sj_read_journal sb_read sys_openat_rd sys_read sys_close ↻ sj_derive_done sb_pint ↻ sys_now_realtime_sec sys_mmap ↻ sys_clock_gettime_real sj_lease_path fa_cat ↻ fa_catn ↻ sj_lock_try sj_writeint_fd sj_readint sys_read ↻ sj_unlink

structs

none

consts

32const SJ_MAGIC_1970: i64 = 1970
33const SJ_MAGIC_100000: i64 = 100000
35const SJ_OEXCL: i64 = 193 // O_CREAT|O_EXCL|O_WRONLY
36const SJ_MODE: i64 = 420 // 0644
37const SJ_JBUF: i64 = 262144
38const SJ_REC: i64 = 256

functions

40func sj_puts(s: *u8) -> i64 { sys_write(1, s, fa_len(s)); return 0 }
called by 2: sj_gatemain calls 1: fa_len
42func sj_eq(a: *u8, b: *u8) -> i64
called by 1: main
50func sj_lockdir_ok(p: *u8) -> i64
called by 1: main calls 1: fa_len
71func sj_lease_path(lockdir: *u8, job: *u8, cid: i64, out: *u8) -> i64
called by 4: sj_leasesj_completesj_statussj_gate calls 2: fa_catfa_catn
83func sj_writeint_fd(fd: i64, v: i64) -> i64
called by 2: sj_lock_trysj_gate
96func sj_readint(path: *u8) -> i64
called by 2: sj_lock_trysj_lease_fresh calls 1: sys_read
112func sj_lock_try(lockpath: *u8, deadline_sec: i64, now_sec: i64) -> i64
called by 1: sj_lease calls 3: sj_writeint_fdsj_readintsj_unlink
125func sj_lease_fresh(lockpath: *u8, now_sec: i64) -> i64
called by 1: sj_status calls 1: sj_readint
135func sj_derive_done(jbuf: *u8, jn: i64, njobs: i64, done: *i64) -> i64
called by 4: sj_leasesj_completesj_statussj_gate calls 1: sb_pint
161func sj_read_journal(journal: *u8, jbuf: *u8) -> i64
called by 5: sj_leasesj_completesj_statussj_journal_countsj_gate calls 1: sb_read
168func sj_submit(journal: *u8, njobs: i64) -> i64
called by 2: sj_gatemain calls 3: fa_catfa_catnfa_append
180func sj_lease(journal: *u8, lockdir: *u8, job: *u8, njobs: i64, ttl_sec: i64) -> i64
called by 3: sj_harvestsj_gatemain calls 5: sj_read_journalsj_derive_donesys_now_realtime_secsj_lease_pathsj_lock_try
203func sj_complete(journal: *u8, lockdir: *u8, job: *u8, njobs: i64, cid: i64, node: *u8) -> i64
called by 3: sj_harvestsj_gatemain calls 7: sj_read_journalsj_derive_donefa_catfa_catnfa_appendsj_lease_path+1
226func sj_status(journal: *u8, lockdir: *u8, job: *u8, njobs: i64) -> i64
called by 3: sj_harvestsj_gatemain calls 7: sj_read_journalsj_derive_donesys_now_realtime_secsj_lease_pathsj_lease_freshfa_cat+1
262func sj_harvest(journal: *u8, lockdir: *u8, job: *u8, njobs: i64, ttl_sec: i64, node: *u8, maxiter: i64) -> i64
called by 2: sj_gatemain calls 5: sj_leasesj_completefa_catfa_catnsj_status
288func sj_wfile_trunc(path: *u8) -> i64
called by 1: sj_gate
295func sj_journal_count(journal: *u8, needle: *u8) -> i64
called by 1: sj_gate calls 2: sj_read_journalfa_len
311func sj_gate() -> i64
called by 1: main calls 16: sys_now_usfa_catfa_catnsj_wfile_truncsj_submitsj_status+10
410func main(argc: i64, argv: *i64) -> i64
calls 14: sj_eqsj_putssb_path_oksb_pintfa_lensj_submit+8