notes

10.0 KB

1. \* hl:proc — child processes as INSTANCE EVENTS.
3. let server = spawn('llama-server -m ' + model + ' --port 8480')
4. on server.line({ line, stream }) { … } \\ stream: 'stdout' | 'stderr'
5. on server.exit({ exit, pid }) { … } \\ always arrives, kill or not
6. server.kill() \\ SIGTERM; exit still fires
7. server.write(text) \\ to its stdin ({ stdin = 'pipe' }): String or Bytes, raw
8. server.end() \\ close its stdin: it reads EOF
10. A child spawned with `{ binary = true }` delivers its output as raw Bytes
11. instead of text lines — `on server.data({ data, stream })`, one event per
12. chunk as it arrives, nothing split and nothing replaced. The default stays
13. text lines.
15. `stream` names the PIPE, not a verdict — most servers (llama.cpp included)
16. write their whole LOG to stderr, keeping stdout for data.
18. A CHILD DIES WITH ITS PARENT: every child is started with the kernel's
19. parent-death signal set to SIGTERM (Linux PR_SET_PDEATHSIG), so when this
20. program exits — any exit, a crash or Ctrl-C included — its children get
21. SIGTERM and no orphan keeps a port. There is no option to turn it off. The
22. setting is the child's own and is not inherited by what IT starts, so a
23. process meant to outlive you is started one level down, by the child:
24. spawnArgs([ 'sh', '-c', 'long-job &' ]).
26. A command that CANNOT START has no exit — it is an ERROR: caught by
27. `on server.Error(e)` (this instance) or the global `on Error(e)`; uncaught
28. it is a located crash naming the binary and the errno. A finished child
29. retires its event source, so a program whose children are done simply ends.
31. THE PROGRAM PATH follows the Hybriel path rule: `spawn('bin/llama-server …')`
32. resolves bin/ against THIS SCRIPT's directory (like imports and hl:fs) — a
33. copied build folder next to your .hl file just works. A bare name searches
34. PATH; absolute stays absolute.
36. OPTIONS, the last argument of spawn and spawnArgs, all optional: `cwd`
37. is the directory the child starts in — a relative one resolves against
38. THIS SCRIPT's directory, like the program path; `env` is added to the
39. environment the child inherits (`{ LANG = 'C' DEBUG = null }` sets LANG
40. and removes DEBUG); `binary = true` delivers the output as Bytes (above);
41. `stdin = 'pipe'` makes the child's stdin writable with write() and end()
42. — without it the child inherits this program's stdin, as before.
44. let st = spawn('git', [ 'status', '--short' ], { cwd = 'repo' })
46. There is NO SHELL — no quoting, no expansion (the safety property, not a
47. gap). `spawnArgs([ 'sh', '-c', pipeline ])` is how you ASK for one,
48. explicitly. *\
50. /* Gate file (docs campaign): __native lives only here; the Process class
51. (process.hl) carries the instance events and their declarations. */
53. \* Start a child from ONE command string: split on WHITESPACE RUNS (spaces,
54. tabs AND newlines — a command written across lines is one command); a
55. quoted argument is GROUPED and its quotes stripped ('{"a": 1}' arrives as
56. one argv entry). A command that cannot start is an Error — caught by
57. `on server.Error(e)` or the global `on Error(e)`. *\
58. spawn(
59. String cmd \\ the program and its arguments, whitespace-separated — or, with `args`, the program alone
60. Hybrid args = null \\ the arguments as a list, each passed as is (cmd is then not split)
61. Hybrid options = null \\ { cwd, env, stdin, binary } — see the head of this file
62. ) {
63. if (args == null) {
64. return new Process().start(cmd, options)
65. }
66. return new Process().startArgs([cmd] + args, options)
67. }
69. \* The LIST form — argv exactly as given: for arguments that contain spaces,
70. or to ask for a shell explicitly: spawnArgs([ 'sh', '-c', pipeline ]). *\
71. spawnArgs(
72. Hybrid args \\ argv entries, one string each — args[0] is the program
73. Hybrid options = null \\ { cwd, env, stdin, binary }, as for spawn
74. ) {
75. return new Process().startArgs(args, options)
76. }
78. \* RUN A PROGRAM AND WAIT FOR IT (ticket #80): the blocking twin of spawn,
79. for code that needs the output NOW — a page's root that is being
80. constructed on the server, a build step, a script. It answers once the
81. program has exited:
83. let log = run([ 'git', 'log', '--oneline', '-5' ], { cwd = 'repo' })
84. log.exit \\ the exit status (128 + n when signal n ended it)
85. log.lines \\ stdout, one String per line, no newlines
86. log.stderr \\ stderr, the same
88. `command` is a String (split like spawn's) or an argv list, passed as is.
89. `options` are spawn's `cwd`, `env` and `binary` — with `binary = true`
90. stdout comes back whole as `data`, a Bytes, instead of `lines` — and
91. `timeout`, in seconds: past it the program is killed and the call is an
92. Error. `stdin`, a String or a Bytes (ticket #91), is what the program
93. reads: written to it whole, then closed, so it reads EOF —
95. let r = run([ 'git', 'upload-pack', '--stateless-rpc', dir ], { stdin = req.bytes binary = true })
97. Without `stdin` the program's stdin is empty (/dev/null); a program that
98. waited for input would otherwise hold the caller forever.
100. The wait holds the fiber that called, as fetch() does, so a server keeps
101. a run short or bounds it with `timeout`. A command that cannot start is an
102. Error, as for spawn; a program that ran and failed is not — read `exit`. *\
103. run(
104. command \\ the program and its arguments: a String, whitespace-separated, or a list
105. Hybrid options = null \\ { cwd, env, binary, stdin, timeout } — see above
106. ) {
107. // stdin crosses the plugin boundary as hex (the ABI has no Bytes), beside the options
108. let o = options
109. let feed = null
110. if (o != null && o.stdin != null) {
111. let t = hlTypeName(o.stdin)
112. if (t == 'Bytes') {
113. feed = o.stdin.hex()
114. o.stdin = null
115. } else if (t == 'String') {
116. feed = toBytes(o.stdin).hex()
117. o.stdin = null
118. }
119. }
120. let r = __native("proc.run", command, o, feed)
121. // a failure an `on Error` handler absorbed leaves the call yielding null
122. if (r == null) {
123. return null
124. }
125. if (options != null && options.binary == true) {
126. return { exit = r.exit data = toBytes(r.out) stderr = linesOf(r.err) }
127. }
128. return { exit = r.exit lines = linesOf(r.out) stderr = linesOf(r.err) }
129. }
131. // A stream's text as its lines: split at each newline, and a final newline ends
132. // the last line rather than starting an empty one — spawn's `line` events say the same.
133. linesOf(String text) {
134. let nl = "
135. "
136. let out = []
137. if (text == '') {
138. return out
139. }
140. for (l of text.split(nl)) {
141. out.push(l)
142. }
143. if (text.endsWith(nl)) {
144. out.pop()
145. }
146. return out
147. }
149. \* The terminal's own input as instance events — `input = stdin()`, then
150. `on input.line(text)` per typed line and `on input.eof()` at Ctrl-D. A joined
151. terminal realm (SPEC "Joining a realm") reads its keyboard here. *\
152. stdin() {
153. return new Stdin().start()
154. }
156. \* One environment variable, null when unset. The runtime loads a `.env`
157. beside the project's entry BEFORE anything runs (KEY=VALUE lines, #
158. comments; the real environment always wins), so env('OPENROUTER_KEY')
159. reads either source through one call. *\
160. env(
161. String name \\ the variable's name
162. ) {
163. return __native("proc.env", name)
164. }
166. \* THE PROGRAM'S OWN ARGUMENTS (mission 317) — the strings that follow the
167. entry on the command line, in order, as a list; an empty list when there
168. were none.
170. hybriel lex.hl a b // args() is ['a', 'b']
171. ./lex a b // the compiled binary answers the same
173. EVERYTHING AFTER THE ENTRY IS THE PROGRAM'S, unchanged: `hybriel
174. [runtime flags] <file> [app args]` (creator ruling 2026-09-27). Flags
175. included — `hybriel t.hl x --post --strict --` gives
176. ['x', '--post', '--strict', '--']; hybriel's own flags (--strict,
177. --offline, --strict-boundaries) are written BEFORE the entry.
179. A project DIRECTORY entry is the same: every argument after it is the
180. program's. Joining a realm is a runtime flag, written before the entry:
181. `hybriel --realm=<name> <projectDir>` (SPEC "Joining a realm").
183. Built here rather than handed over whole because a `__native` call answers
184. with ONE value and a list is what the caller wants: the count and the i-th
185. argument are the two questions the runtime can answer, and the list is the
186. language's own. *\
187. args() {
188. let out = []
189. let n = __native("proc.argc")
190. let i = 0
191. while (i < n) {
192. out.push(__native("proc.arg", i))
193. i = i + 1
194. }
195. return out
196. }
198. \* WRITE TO THIS PROGRAM'S OWN STDOUT, RAW (ruling on ticket #42): a String's
199. bytes or a Bytes, exactly as they are — no newline, no text form, unlike
200. console.log. For a binary protocol on stdout. Answers how many bytes went. *\
201. writeStdout(
202. data \\ a String or a Bytes
203. ) {
204. if (hlTypeName(data) == 'Bytes') {
205. return __native("proc.write_stdout_hex", data.hex())
206. }
207. return __native("proc.write_stdout", data)
208. }
210. \* WRITE TO THIS PROGRAM'S OWN STDERR, RAW: writeStdout's twin on the error
211. stream — a String's bytes or a Bytes, exactly as they are, no newline.
212. Answers how many bytes went. *\
213. writeStderr(
214. data \\ a String or a Bytes
215. ) {
216. if (hlTypeName(data) == 'Bytes') {
217. return __native("proc.write_stderr_hex", data.hex())
218. }
219. return __native("proc.write_stderr", data)
220. }
222. \* END THIS PROGRAM NOW with an exit status (ruling on ticket #36): 0 is
223. success, anything up to 255 tells the shell it failed. Nothing after the
224. call runs. An uncaught error still exits 1 by itself. *\
225. exit(
226. Number code = 0 \\ the exit status, 0-255
227. ) {
228. __native("proc.exit", code)
229. }
231. \* THE PROGRAM'S OWN DIRECTORY, absolute (ticket #37): the directory of the
232. entry script on the interpreter, the directory the executable sits in for
233. a compiled binary (a binary knows no build directory). cwd() is where the
234. user launched from; file() is the calling file's path. *\
235. dir() {
236. return __native("proc.dir")
237. }
239. \* The process's current working directory, absolute — where the USER
240. launched from. Your own files resolve script-relatively everywhere
241. (imports, hl:fs, spawn); cwd() is for tools whose subject is the caller's
242. directory: a formatter, a scaffolder. *\
243. cwd() {
244. return __native("proc.cwd")
245. }