ela
Contents

ManualLanguage

Process control

In the terminalela --spec process-control

  • exec cmd replaces 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.
  • run starts 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, and spawn is an error that names run.
  • A job's failure is taken by a catch run block below the line that started it, at its wait (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 run line, so a mistake in them stops the script there. A call's proc gets its parameters, as every call does, and its return value comes back at wait; cd and environment changes inside the job stay in it.
  • A job gives one value: its proc's return value, null when it returns none, and null for 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 and null. 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 sudo and ssh do to ask for a password, is stopped by the system, since the job's group is not the terminal's. In a script, wait sees 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 -n fails at once with no cached password, ssh -o BatchMode=yes without a key. At the prompt the job is listed as stopped, (wants the terminal) (SHELL.md, Job control).
  • $job.output is 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 $job waits 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 $job gives null instead for a job that went well, and the job's failure as an Error for one that failed (Errors as values); errs = try wait $jobs gives a list of them in the list's order. Under try no catch run block 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"])

Who starts a job, where its output goes, who waits for it, and what a stop does

  • A loop or an if owns nothing: its jobs are the proc's or the script's, so a loop can start them and a wait after it gathers them.
  • A proc may return a job it started. It has waited for it by then, so the caller's wait gives its value at once, and $job.output its 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 kill sent ended has ended as it was asked: wait gives null and no failure, and try wait an 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 signal block 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, as ps -e shows it; none is an error, and so are several, with their ids listed to pick from.
  • job(n) is the job numbered n, as jobs and the notices number it; job("name") is the one job whose command's first word, as jobs shows it, is that. None or several is an error that lists their numbers.
  • pid goes with kill alone: given to wait, fg or bg it 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 4242 or kill -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 752075 or kill $n holding a number, is an error that says to write kill pid(752075) for a process, or kill job(N) for a job, and --lint reports it. --lint also warns of pid(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 STOP and kill $job CONT return 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: wait on it is an error that names kill $job CONT, since the wait would never end.

run.max and $run.slot #

  • with run.max = N ... end with lets at most N jobs run at once in its block; a run beyond it waits at its line until one ends. N is a whole number, 1 or more. With no with, 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 at end with.
  • $run.slot is 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 command run starts. 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).