diff options
Diffstat (limited to 'bbot/agent/agent.cli')
| -rw-r--r-- | bbot/agent/agent.cli | 139 |
1 files changed, 128 insertions, 11 deletions
diff --git a/bbot/agent/agent.cli b/bbot/agent/agent.cli index b50a43a..23765cf 100644 --- a/bbot/agent/agent.cli +++ b/bbot/agent/agent.cli @@ -1,5 +1,5 @@ // file : bbot/agent.cli -// license : TBC; see accompanying LICENSE file +// license : MIT; see accompanying LICENSE file include <libbbot/manifest.hxx>; @@ -12,19 +12,77 @@ 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 this boosting semantics + may not be accurate if the agent is executed with CPU affinity. Also note + that there is no corresponding RAM boosting and it's possible that in some + configurations the amount of RAM will be insufficient for the boosted CPU + count. + + 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. @@ -61,10 +119,20 @@ namespace bbot "<num>", "Toolchain number, 1 by default. If agents are running for several toolchains, then each of them should have a unique toolchain number - between 1 and 99. This number is used as an offset for network ports, + between 1 and 9. This number is used as an offset for network ports, interfaces, etc." } + string --toolchain-lock // Note: string to allow empty path. + { + "<path>", + "Absolute path to the global toolchain lock file. If unspecified, then + \c{\b{/var/lock/bbot-agent-}\i{toolchain-name}\b{.lock}} is used by + default. If empty path is specified then no global locking is + performed. If one of the \cb{--fake-*} options is specified, then no + locking is performed by default." + } + standard_version --toolchain-ver { "<stdver>", @@ -101,16 +169,44 @@ namespace bbot network ports, interfaces, etc." } + uint16_t --instance-max = 0 + { + "<num>", + "Maximum number of instances that can perform tasks concurrently. If the + number of instances that have been started is greater than this number + (normally by just one), then when the maximum number of tasks is + already being performed, the extra instances operate in the \i{priority + monitor} mode: they only query controller URLs with priorities higher + than of the existing tasks and can only perform a task by interrupting + one of them. If the maximum number of instances is \cb{0} (default), + then it is assumed the number of instances started is the maximum + number, essentially disabling the priority monitor functionality." + } + size_t --cpu = 1 { "<num>", "Number of CPUs (threads) to use, 1 by default." } - size_t --ram (1024 * 1024) // 1G + size_t --build-ram (4 * 1024 * 1024) // 4GiB { "<num>", - "Amount of RAM (in kB) to use, 1G by default." + "Amount of RAM (in KiB) to use for the build machine, 4GiB by default." + } + + size_t --auxiliary-ram = 0 + { + "<num>", + "Amount of RAM (in KiB) to use for auxiliary machines. To disable + running auxiliary machines, specify \cb{0}. If unspecified, then + currently the behavior is the same as specifying \cb{0} but this + may change in the future (for example, to support a more dynamic + allocation strategy)." + + // Note: it's not going to be easy to set it to unspecified in + // bbot-agent@.service so we may have to invent some special value, + // like `auto`. } string --bridge = "br1" @@ -155,21 +251,35 @@ namespace bbot } // Low 23401+, 23501+, 23601+, etc., all look good collision-wise with - // with anything useful. + // anything useful. // uint16_t --tftp-port = 23400 { "<num>", "TFTP server port base, 23400 by default. The actual port is calculated - by adding an offset calculated based on the toolchain and instance - numbers." + by adding an offset calculated based on the toolchain, instance, and + machine numbers." + } + + size_t --bootstrap-startup = 300 + { + "<sec>", + "Maximum number of seconds to wait for build machine bootstrap startup, + 300 (5 minutes) by default." } size_t --bootstrap-timeout = 3600 { "<sec>", - "Maximum number of seconds to wait for machine bootstrap completion, - 3600 (60 minutes) by default." + "Maximum number of seconds to wait for build machine bootstrap + completion, 3600 (60 minutes) by default." + } + + size_t --bootstrap-auxiliary = 900 + { + "<sec>", + "Maximum number of seconds to wait for auxiliary machine bootstrap + completion, 900 (15 minutes) by default." } size_t --bootstrap-retries = 2 @@ -179,6 +289,13 @@ namespace bbot by default." } + size_t --build-startup = 240 + { + "<sec>", + "Maximum number of seconds to wait for build startup, 240 (4 minutes) by + default. This value is used for both build and auxiliary machines." + } + size_t --build-timeout = 5400 { "<sec>", |