Documentation
¶
Overview ¶
Package bgrun runs a jaira subcommand in the background, at most every so often, without any command ever waiting for it.
Three things in this program work that way — the release check, the board's snapshot, and the ref fetch — and they are the same five careful details every time. Written out three times, one of those details would eventually be missing from one of them, and the symptom would be a command that hangs, or a process that spawns itself for ever.
The details, and why each is there:
- The stamp is written BEFORE the run, not after. A run that dies or hangs must not make the next command start another one.
- The child is given the disable switch as an environment variable, so it can never decide the task is due and spawn a grandchild. That is the same switch a user flips to turn the task off, so there is one mechanism here rather than two.
- Nothing waits. The parent is about to exit and the child is reparented to init; a background task nobody asked for must never be something somebody waits for.
- Never from a test binary, which has no such subcommand and would re-run its own suite, detached, reaching the network on the way.
- Stdio goes to os.DevNull: a child writing to the terminal after the parent has exited is the exact failure this design avoids.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Task ¶
type Task struct {
// Stamp is the file recording when this task last ran, normally under the
// board's state directory — never inside the repository, because when a
// background job last ran is this machine's business.
Stamp string
// DisableEnv is the environment variable that turns the task off, and is
// also handed to the child as its recursion guard.
DisableEnv string
// Args is the jaira subcommand to run, e.g. []string{"fetch", "--quiet"}.
Args []string
// Dir is the board the child should act on. It must be set explicitly: a
// child inherits the parent's working directory, not the parent's -C flag,
// so a task spawned from a command run with -C would otherwise quietly
// operate on whatever directory the shell happened to be in.
Dir string
// Every is how old the last run may be before another is due. Zero means
// the task is never due on its own.
Every time.Duration
}
Task is one background job: what to run, how often, and how to switch it off.
func (Task) Read ¶
Read returns the last mark, or a zero Mark. Every error is swallowed: a missing or damaged mark is indistinguishable from "never ran" for every purpose this serves, and the cost of getting it wrong is one extra run.
Source Files