Process control
In the terminalela --spec process-control
exec cmdreplaces the shell process. It never returns; when the program exits, the process exits with its code. If exec fails, as for a command not found, fail-fast stops the script.runstarts a job in the background and gives it: a command or a pipeline,x = run make test, or a call,x = run deploy("api"). It replaces Bash's&and$!; there is no raw fork, andspawnis an error that namesrun.- A job's failure is taken by a
catch runblock below the line that started it, at itswait(catch).
proc deploy(host: string) rsync -a build/ "$host:/srv/app" return $(ssh $host cat /srv/app/VERSION)end proc jobs = []for host in ["web1.example", "web2.example", "web3.example"] jobs = list.append($jobs, run deploy($host))end forversions = wait $jobs # ["1.4.2", "1.4.2", "1.4.2"], once all three have ended
Jobs #
- A job is a process of its own, never a thread: a call runs in a copy of ela made when the job starts. Its words and arguments are worked out at the
runline, so a mistake in them stops the script there. A call's proc gets its parameters, as every call does, and itsreturnvalue comes back atwait;cdand environment changes inside the job stay in it. - A job gives one value: its proc's
returnvalue,nullwhen it returns none, andnullfor a command. A proc that returns several values returns them in a list or a struct. The value comes back as data: text, numbers, lists, maps, structs, enums andnull. A job in it is an error. - A job reads no input: its stdin is
/dev/null. Its stdout and stderr go together, in the order written, to a file in the user's runtime folder ($XDG_RUNTIME_DIR, else$TMPDIR, else/tmp), removed as it is made, so none is left however the job or ela ends. The runtime folder is memory on most systems, so a job's output there takes memory until the job is waited for; one that writes gigabytes goes to a file of its own with a redirect,run make > build.log. - A job never reads the terminal either. A command of it that opens the terminal itself, as
sudoandsshdo to ask for a password, is stopped by the system, since the job's group is not the terminal's. In a script,waitsees the stop within a quarter of a second, ends the job and fails with a message that says so; its command is given what it asks another way:sudo -nfails at once with no cached password,ssh -o BatchMode=yeswithout a key. At the prompt the job is listed as stopped,(wants the terminal)(SHELL.md, Job control). $job.outputis that text once the job has ended, its last newline trimmed as$( )trims it. Reading it while the job runs is an error.
wait #
wait $jobwaits for the job to end, prints its output whole, and gives its value.wait $jobs, a list of jobs, waits for every one, prints their output in the order they were started, and gives a list of their values in the list's order.- A job's output is printed once, at the first wait; waiting again prints nothing and gives the same value.
- A job that failed stops the script at
wait, as a failed command does, with the job's exit code, its output printed first. In a list, the first failure in the list's order stops it, once every job has ended and every output is printed. err = try wait $jobgivesnullinstead for a job that went well, and the job's failure as an Error for one that failed (Errors as values);errs = try wait $jobsgives a list of them in the list's order. Undertrynocatch runblock runs.- A failed job never stops another: the jobs beside it run to their end, and the failure surfaces at its wait.
Who waits #
A job belongs to the code that started it: the proc, the with block or the script. When that code ends, at its end, by return, by an error or by exit, it waits for every job it started that has not been waited for, after its deferred lines, as wait would: their output printed in the order they were started, and a failure the proc's, the block's or the script's. So no job outlives the code that started it, and a job is never left running unnoticed.
proc check_all(hosts: list) for host in $hosts run ssh $host systemctl is-active app end for echo "checks started"end proc # waits for every check, and fails as the first that failed check_all(["web1.example", "web2.example"])
- A loop or an
ifowns nothing: its jobs are the proc's or the script's, so a loop can start them and awaitafter it gathers them. - A proc may return a job it started. It has waited for it by then, so the caller's
waitgives its value at once, and$job.outputits output. - A job that should end with its proc, a server for the tests, is stopped by
defer kill, since deferred lines come first.
proc test_api() server = run ./server --port 8080 defer kill $server sleep 1 curl -fsS http://localhost:8080/healthend proc
- A job the signal
killsent ended has ended as it was asked:waitgivesnulland no failure, andtry waitan Error with its code (143 for TERM). A job that took the signal and went on to fail has failed, as any job does. - When a signal ends the script, or a proc on its way up to the
catch signalblock that covers it, the signal is passed on to the jobs they started, which are then waited for.
kill #
kill sends a signal to a process or to a job, and the word after it says which: pid(…) for a process, job(…) or a job value for a job. The signal comes last and is TERM unless named (TERM, INT, KILL, HUP, QUIT, USR1, USR2, STOP, CONT).
kill pid(1343453) # the process with that idkill pid("firefox") KILL # the one process named firefox, sent KILLkill job(1) # the session's job 1, as jobs lists itkill job("vim") # the one job whose command is vimx = run make testkill $x # the job run gave
At the prompt a bare number is a process id: kill 1343453 is kill pid(1343453).
pid(n)is the process with that id, a whole number from 1 up.pid("name")is the one process whose name is exactly that, asps -eshows it; none is an error, and so are several, with their ids listed to pick from.job(n)is the job numbered n, asjobsand the notices number it;job("name")is the one job whose command's first word, asjobsshows it, is that. None or several is an error that lists their numbers.pidgoes withkillalone: given towait,fgorbgit is an error, since ela waits only for its own jobs.job(…)goes to all four.- Bash's signal flag before the target,
kill -TERM $p,kill -9 4242orkill -s INT 4242, is an error before the script runs, which writes the line in ela's order:kill pid(4242) KILL. - In a script a bare number to
kill,kill 752075orkill $nholding a number, is an error that says to writekill pid(752075)for a process, orkill job(N)for a job, and--lintreports it.--lintalso warns ofpid(N)with N below 300, which is almost always a job's number. - At the prompt, when the system refuses the signal to a bare number and the session has a job of that number, the error says so:
for job 1 write kill job(1). - A job is sent the signal to every process of it; one that has ended is sent nothing, and a stopped one is sent CONT after the signal, so it takes it.
kill $job STOPandkill $job CONTreturn once every process of the job has stopped or carried on, so the line after sees the job as it asked. A job a script stopped is waited for only once it carries on:waiton it is an error that nameskill $job CONT, since the wait would never end.
run.max and $run.slot #
with run.max = N ... end withlets at most N jobs run at once in its block; arunbeyond it waits at its line until one ends. N is a whole number, 1 or more. With nowith, the limit is the number of CPUs ela may use: those it may run on, capped by its cgroup's CPU limit (cpu.max, a part of a CPU counted whole), at least 1; nested blocks put the limit before back atend with.$run.slotis a job's slot, from 0 to the limit less 1, held by no other job running at the same time: read in the job's proc, and in the words of the commandrunstarts. Outside a job it is an error. A job's own jobs number their slots apart from the job's.
proc train(fold: number) with env.CUDA_VISIBLE_DEVICES = "$run.slot" python train.py --fold $fold end withend proc with run.max = 2 # two GPUs scores = wait [run train(1), run train(2), run train(3), run train(4)]end with
At the interactive prompt the jobs belong to the session, and fg, bg and jobs work on them (SHELL.md, Jobs at the prompt and Job control).