diff options
Diffstat (limited to 'bbot/agent/agent.cli')
| -rw-r--r-- | bbot/agent/agent.cli | 58 |
1 files changed, 56 insertions, 2 deletions
diff --git a/bbot/agent/agent.cli b/bbot/agent/agent.cli index 3d028fd..1046685 100644 --- a/bbot/agent/agent.cli +++ b/bbot/agent/agent.cli @@ -12,19 +12,73 @@ include <bbot/common.cli>; namespace bbot { { - "<options> <url>", + "<options> <priority> <url>", " \h|SYNOPSIS| \c{\b{bbot-agent --help}\n \b{bbot-agent --version}\n - \b{bbot-agent} [<options>] <url>...} + \b{bbot-agent} [<options>] [<priority>=]<url>...} \h|DESCRIPTION| \cb{bbot-agent} @@ TODO. + The controller URL <priority> is a four or five-digit decimal value. If it + is absent, then \cb{0} (lowest priority) is assumed. URLs with equal + priority are queried at random. + + The <priority> value has the \c{[\i{F}]\i{DCBA}} form which encodes four + priority levels (\ci{DCBA}) each occupying one decimal digit (so there are + 10 distinct priorities in each level) plus the optional boost flag + (\ci{F}). These levels offer different trade-offs between the speed of + completing a higher priority task and potentially discarding work that has + already been done. + + The first priority level (\ci{A}) is a simple preference: among the URLs + with equal values for other levels (\ci{DCB}), those with higher first + level priorities are queried first. + + The second priority level (\ci{B}) has the semantics of the first level + plus it prevents URLs with lower second priority level from being + queried until the task with a higher second priority level has completed, + effectively conserving the resources for the higher priority task. + + The third priority level (\ci{C}) has the semantics of the second level + plus it may interrupt one lower third priority level task in order to + perform the higher third priority task (the interrupt is necessary if the + desired machine is used by the lower priority task or the number of tasks + already being performed is the maximum allowed to be performed + concurrently; see \cb{--instance-max}). + + Finally, the fourth priority level (\ci{D}) has the semantics of the third + level except that not one but all the lower fourth priority level tasks + are interrupting, effectively dedicating all the available resources to + the higher priority task. This level can also be combined with the boost + flag \ci{F}. If this flag is \cb{1} then the higher priority task's CPU + number (\cb{--cpu}) is boosted to the full number of available hardware + threads (or, to view it another way, the fourth priority level has 20 + possible values, not 10, with the first 0-9 being without the boost while + the last 10-19 being with the boost). + + Note that the priority levels are hierarchical in a sense that within a + given higher level URLs can be further prioritized using the lower + levels. As an example, consider a deployment with three controller URLs: + background package rebuilds (\cb{pkg.example.org}), user-initiated CI + (\cb{ci.example.org}), and user-initiated interactive CI + (\cb{ici.example.org}). Given the following priorities: + + \ + 0000=https://pkg.example.org + 0100=https://ci.example.org + 0101=https://ici.example.org + \ + + Both types of CI tasks will interrupt one background rebuild task if + necessary while the interactive CI tasks will be merely preferred over + non-interactive. + Note that on termination \cb{bbot-agent} may leave behind a machine lock and working machine snapshot. It is expected that the caller (normally Build OS monitor) cleans them up before restarting the agent. |