Brunobkr/llama.cpp_AlgMor24_github

1# foreground-child2 3Run a child as if it's the foreground process. Give it stdio. Exit4when it exits.5 6Mostly this module is here to support some use cases around7wrapping child processes for test coverage and such. But it's8also generally useful any time you want one program to execute9another as if it's the "main" process, for example, if a program10takes a `--cmd` argument to execute in some way.11 12## USAGE13 14```js15import { foregroundChild } from 'foreground-child'16// hybrid module, this also works:17// const { foregroundChild } = require('foreground-child')18 19// cats out this file20const child = foregroundChild('cat', [__filename])21 22// At this point, it's best to just do nothing else.23// return or whatever.24// If the child gets a signal, or just exits, then this25// parent process will exit in the same way.26```27 28You can provide custom spawn options by passing an object after29the program and arguments:30 31```js32const child = foregroundChild(`cat ${__filename}`, { shell: true })33```34 35A callback can optionally be provided, if you want to perform an36action before your foreground-child exits:37 38```js39const child = foregroundChild('cat', [__filename], spawnOptions, () => {40  doSomeActions()41})42```43 44The callback can return a Promise in order to perform45asynchronous actions. If the callback does not return a promise,46then it must complete its actions within a single JavaScript47tick.48 49```js50const child = foregroundChild('cat', [__filename], async () => {51  await doSomeAsyncActions()52})53```54 55If the callback throws or rejects, then it will be unhandled, and56node will exit in error.57 58If the callback returns a string value, then that will be used as59the signal to exit the parent process. If it returns a number,60then that number will be used as the parent exit status code. If61it returns boolean `false`, then the parent process will not be62terminated. If it returns `undefined`, then it will exit with the63same signal/code as the child process.64 65## Caveats66 67The "normal" standard IO file descriptors (0, 1, and 2 for stdin,68stdout, and stderr respectively) are shared with the child process.69Additionally, if there is an IPC channel set up in the parent, then70messages are proxied to the child on file descriptor 3.71 72In Node, it's possible to also map arbitrary file descriptors73into a child process. In these cases, foreground-child will not74map the file descriptors into the child. If file descriptors 0,751, or 2 are used for the IPC channel, then strange behavior may76happen (like printing IPC messages to stderr, for example).77 78Note that a SIGKILL will always kill the parent process, but79will not proxy the signal to the child process, because SIGKILL80cannot be caught. In order to address this, a special "watchdog"81child process is spawned which will send a SIGKILL to the child82process if it does not terminate within half a second after the83watchdog receives a SIGHUP due to its parent terminating.84 85On Windows, issuing a `process.kill(process.pid, signal)` with a86fatal termination signal may cause the process to exit with a `1`87status code rather than reporting the signal properly. This88module tries to do the right thing, but on Windows systems, you89may see that incorrect result. There is as far as I'm aware no90workaround for this.91 92## util: `foreground-child/proxy-signals`93 94If you just want to proxy the signals to a child process that the95main process receives, you can use the `proxy-signals` export96from this package.97 98```js99import { proxySignals } from 'foreground-child/proxy-signals'100 101const childProcess = spawn('command', ['some', 'args'])102proxySignals(childProcess)103```104 105Now, any fatal signal received by the current process will be106proxied to the child process.107 108It doesn't go in the other direction; ie, signals sent to the109child process will not affect the parent. For that, listen to the110child `exit` or `close` events, and handle them appropriately.111 112## util: `foreground-child/watchdog`113 114If you are spawning a child process, and want to ensure that it115isn't left dangling if the parent process exits, you can use the116watchdog utility exported by this module.117 118```js119import { watchdog } from 'foreground-child/watchdog'120 121const childProcess = spawn('command', ['some', 'args'])122const watchdogProcess = watchdog(childProcess)123 124// watchdogProcess is a reference to the process monitoring the125// parent and child. There's usually no reason to do anything126// with it, as it's silent and will terminate127// automatically when it's no longer needed.128```129