gitoria

9.4 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. The program's stdin is empty (/dev/null); a program that waited
93. for input would otherwise hold the caller forever.
95. The wait holds the fiber that called, as fetch() does, so a server keeps
96. a run short or bounds it with `timeout`. A command that cannot start is an
97. Error, as for spawn; a program that ran and failed is not — read `exit`. *\
98. run(
99. command \\ the program and its arguments: a String, whitespace-separated, or a list
100. Hybrid options = null \\ { cwd, env, binary, timeout } — see above
101. ) {
102. let r = __native("proc.run", command, options)
103. // a failure an `on Error` handler absorbed leaves the call yielding null
104. if (r == null) {
105. return null
106. }
107. if (options != null && options.binary == true) {
108. return { exit = r.exit data = toBytes(r.out) stderr = linesOf(r.err) }
109. }
110. return { exit = r.exit lines = linesOf(r.out) stderr = linesOf(r.err) }
111. }
113. // A stream's text as its lines: split at each newline, and a final newline ends
114. // the last line rather than starting an empty one — spawn's `line` events say the same.
115. linesOf(String text) {
116. let nl = "
117. "
118. let out = []
119. if (text == '') {
120. return out
121. }
122. for (l of text.split(nl)) {
123. out.push(l)
124. }
125. if (text.endsWith(nl)) {
126. out.pop()
127. }
128. return out
129. }
131. \* The terminal's own input as instance events — `input = stdin()`, then
132. `on input.line(text)` per typed line and `on input.eof()` at Ctrl-D. A joined
133. terminal realm (SPEC "Joining a realm") reads its keyboard here. *\
134. stdin() {
135. return new Stdin().start()
136. }
138. \* One environment variable, null when unset. The runtime loads a `.env`
139. beside the project's entry BEFORE anything runs (KEY=VALUE lines, #
140. comments; the real environment always wins), so env('OPENROUTER_KEY')
141. reads either source through one call. *\
142. env(
143. String name \\ the variable's name
144. ) {
145. return __native("proc.env", name)
146. }
148. \* THE PROGRAM'S OWN ARGUMENTS (mission 317) — the strings that follow the
149. entry on the command line, in order, as a list; an empty list when there
150. were none.
152. hybriel lex.hl a b // args() is ['a', 'b']
153. ./lex a b // the compiled binary answers the same
155. A flag after the file is the program's too (`hybriel t.hl x --post` gives
156. ['x', '--post']), except hybriel's own — --port=, --strict, --offline,
157. --strict-boundaries — which stay hybriel's anywhere; after `--` every
158. argument is the program's, verbatim.
160. A project DIRECTORY entry is unchanged: `hybriel <projectDir> <realm>` still
161. JOINS that realm, so the positional there is the realm's name and never an
162. argument (SPEC "Joining a realm").
164. Built here rather than handed over whole because a `__native` call answers
165. with ONE value and a list is what the caller wants: the count and the i-th
166. argument are the two questions the runtime can answer, and the list is the
167. language's own. *\
168. args() {
169. let out = []
170. let n = __native("proc.argc")
171. let i = 0
172. while (i < n) {
173. out.push(__native("proc.arg", i))
174. i = i + 1
175. }
176. return out
177. }
179. \* WRITE TO THIS PROGRAM'S OWN STDOUT, RAW (ruling on ticket #42): a String's
180. bytes or a Bytes, exactly as they are — no newline, no text form, unlike
181. console.log. For a binary protocol on stdout. Answers how many bytes went. *\
182. writeStdout(
183. data \\ a String or a Bytes
184. ) {
185. if (hlTypeName(data) == 'Bytes') {
186. return __native("proc.write_stdout_hex", data.hex())
187. }
188. return __native("proc.write_stdout", data)
189. }
191. \* WRITE TO THIS PROGRAM'S OWN STDERR, RAW: writeStdout's twin on the error
192. stream — a String's bytes or a Bytes, exactly as they are, no newline.
193. Answers how many bytes went. *\
194. writeStderr(
195. data \\ a String or a Bytes
196. ) {
197. if (hlTypeName(data) == 'Bytes') {
198. return __native("proc.write_stderr_hex", data.hex())
199. }
200. return __native("proc.write_stderr", data)
201. }
203. \* END THIS PROGRAM NOW with an exit status (ruling on ticket #36): 0 is
204. success, anything up to 255 tells the shell it failed. Nothing after the
205. call runs. An uncaught error still exits 1 by itself. *\
206. exit(
207. Number code = 0 \\ the exit status, 0-255
208. ) {
209. __native("proc.exit", code)
210. }
212. \* THE PROGRAM'S OWN DIRECTORY, absolute (ticket #37): the directory of the
213. entry script on the interpreter, the directory the executable sits in for
214. a compiled binary (a binary knows no build directory). cwd() is where the
215. user launched from; file() is the calling file's path. *\
216. dir() {
217. return __native("proc.dir")
218. }
220. \* The process's current working directory, absolute — where the USER
221. launched from. Your own files resolve script-relatively everywhere
222. (imports, hl:fs, spawn); cwd() is for tools whose subject is the caller's
223. directory: a formatter, a scaffolder. *\
224. cwd() {
225. return __native("proc.cwd")
226. }