/ 
App-karr-0.600
/ App::karr::Foundation::Limits

NAME

App::karr::Foundation::Limits - karr-foundation concurrency limits -- machine ceiling, per-agent estimates, chain header

VERSION

version 0.600

DESCRIPTION

How many agents karr-foundation may have running at once, and how many of any one named agent. Three levels, tightest wins:

1. concurrent: in the local config -- the machine ceiling.

It protects this machine's CPU and memory and is not a quota: it says nothing about what any account may spend, only about what this box can carry. It is the only one of the three that is always present, because it defaults to 1 -- which is exactly the serial runner karr-foundation has always been. Concurrency is opt-in for the same reason agent execution is: a default that suddenly started four agents on an operator's laptop would be a surprise, and the surprise would arrive on a machine, not in a review.

2. concurrent: on a named agent definition -- the operator's estimate.

This is where the prose policy lands as a number: roughly how many sessions of this agent may run side by side. It is a guess about somebody else's rate limit and is allowed to be wrong, because being wrong is cheap here -- the agent starts failing, App::karr::Foundation::Agents marks it so, every board on it is skipped for one probe interval, and the fallback takes over. That is the whole error budget this number needs.

3. limits: in the chain header -- what one particular run declares.
limits:
  concurrent: 4
  per_agent:
    minimax: 2

The chain is shared state, so this travels with the plan rather than with the machine. It can only ever tighten: a chain asking for eight concurrent runs on a box configured for two gets two.

The per_agent names are agent definition names -- the keys of the config's agents: section ("definitions" in App::karr::Foundation::Agents), not a second, free-form namespace. A name this machine does not define is dropped with a verbose note rather than an error: agent definitions are local and only local by design, so a chain written on a machine with minimax reaching one without it is the expected case, not a broken plan.

A malformed number is treated by where it came from. In the local config it is a user_error: it is the operator's own file, and a concurrent: "two" silently meaning one is the kind of quiet wrong answer this distribution refuses. In the chain header it warns and is ignored: the header was written on another machine, and refusing to run the fleet over a foreign typo is worse than running it at the local ceiling.

SEE ALSO

App::karr::Foundation, App::karr::Foundation::Agents, App::karr::Foundation::ChainStore

foundation

The owning App::karr::Foundation, held weakly. Required.

chain_limits

The limits: mapping of the current chain header, or {} when there is no hub configured, no chain written, or nothing readable in it. Read once per foundation run -- the fleet namespace is pulled before this is built (see "_sync_pull_foundation" in App::karr::Foundation), so it is the fleet's answer rather than whatever this machine happened to have.

concurrent

The effective machine-wide ceiling: how many boards may have an agent on them at once. Always at least 1, so a foundation configured with nothing at all behaves exactly as the serial runner did.

per_agent

Agent name => how many runs of that agent may be live at once, for the agents that have a limit at all. An agent that appears nowhere here is bounded only by "concurrent".

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/karr/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)