Test2:...bSlots(3pm)

💖 Test2::Harness::Runner::Resource::SharedJobSlots 💖

okay bestie, so this is a 3pm manual page — like, Perl module docs, but make it group chat. Welcome to Test2::Harness::Runner::Resource::SharedJobSlots, a whole module whose entire personality is: limit the job count (-j) per machine. That's it. That's the gig. She's a gatekeeper and she is slaying at it. 👑

---

✨ NAME ✨

Test2::Harness::Runner::Resource::SharedJobSlots — the icon herself. Her one job (pun fully intended): cap how many jobs (-j) one machine is allowed to run. No cap, no chill.

---

🫶 SYNOPSIS 🫶

okay real talk, this synopsis is not about using this thing in your code, it's about how you use it on the command line. Different vibe entirely. iykyk.

So to actually get SharedJobSlots working you have to do one of these two things, no skipping:

• make a .sharedjobslots.yml file, or
• pass the --shared-jobs-config PATH argument on the command line.

And <italic>PATH</italic> here? It must be a path to a yaml file that has your configuration specifications for job sharing. fr fr, that's the whole deal.

---

🎀 CONFIG FILE 🎀

Config files for shared slots must be yaml files. They also must be parsable by YAML::Tiny, which — heads up — implements a subset of yaml, so don't get cute with the fancy yaml features, she won't understand you.

Here's an example config file, and yes it's iconic, look at her:

---
DEFAULT:
  state_file: /tmp/yath-slot-state
  max_slots:  8
  max_slots_per_job: 2
  max_slots_per_run: 6

myhostname:
  state_file: /tmp/myhostname-slot-state
  max_slots:  16
  max_slots_per_job: 4
  max_slots_per_run: 12

---

🌸 TOP LEVEL KEYS (HOSTNAMES) 🌸

All the top level keys are hostnames. The way that this works: when the config gets read, the settings for the current hostname get used. If your hostname isn't defined in there? Then the DEFAULT host gets read instead. And if there's genuinely no DEFAULT host defined at all? 🚨 An exception gets thrown. Like, outright thrown. So define your defaults, bestie.

---

💅 CONFIG OPTIONS 💅

Every single one of these options has to be specified under a hostname. None of them are valid standing on their own. Understand the assignment or don't show up. 🙈

• state_file: /path/to/shared/state/file — REQUIRED. This is the path to the shared state file. And listen: all yath processes, by all users who are sharing slots, need read + write access to this file. Everybody. All of them. So check your perms before you come crying to me. 😭
• state_umask: 0007 — defaults to 0007. This is used to set the umask of the state file, and also the lock file. Two for one, we love efficiency. ✨
• max_slots: 8 — the max slots system-wide, for all users to share. The whole system's budget, right there.
• max_slots_per_run: 4 — the max slots that a specific test run is allowed to use. One run cannot eat the whole buffet.
• min_slots_per_run: 0 — the minimum slots per run. Set this if you want to make sure that all runs get at least N slots, EVEN IF IT MEANS GOING OVER THE SYSTEM-WIDE MAXIMUM!. Yes. That's real. She said what she said. This defaults to 0.
• max_slots_per_job: 2 — the max slots a specific test job (aka a test file) can use.
• default_slots_per_run: 4 — if the user doesn't specify a number of slots, this is what gets used. The fallback queen.
• default_slots_per_job: 2 — if the user doesn't specify a number of job slots, use this one as the default.
• algorithm: fair — the algorithm to use when assigning slots. 'fair' is the default, so she's the main character unless you say otherwise.
• algorithm: first — same key, different personality. Also an algorithm option for assigning slots.
• algorithm: Fully::Qualified::Module::function_name — you can point this at a fully qualified subroutine name and roll your own algorithm. Custom is cute. 🦋

---

⭐ ALGORITHMS ⭐

These are the algorithms used to decide which test runs get which slots. Pick your fighter. 🌈

• fair — DEFAULT. This algorithm tries to balance slots so that all runs share an equal fraction of the available slots. If there aren't enough slots to go around, then priority goes to the oldest runs, followed by the oldest requests. Fair is fair, bestie. ⚖️
• first — priority goes to the oldest run, followed by the next oldest, etc. And if the run age isn't sufficient to sort the requests, this falls back to 'fair'. This one's mainly useful for CI systems or batched test boxes. It gives priority to the first test run started, so additional test runs won't consume slots that the first run wants to use — but if the first run is winding down and doesn't need all the slots, the second test run can start using only the spare slots. So: use this with ordered test runs where you do not want a purely serial run order. 💅
• Fully::Qualified::Module::function_name — you can specify custom algorithms by giving fully qualified subroutine names. Yes, your own. Go off. 👑

Example custom algorithm, copied with love, don't touch the code:

sub custom_sort {
    my ($state_object, $state_data, $a, $b) = @_;

    return 1 if a_should_come_first($a, $b);
    return -1 if b_should_come_first($a, $b);
    return 0 if both_have_same_priority($a, $b);

    # *shrug*
    return 0;
}

Ultimately this gets used in a sort() call, so the usual rules apply: your return should be 1, 0, or -1. Where <italic>$a</italic> and <italic>$b</italic> are the 2 items being compared. And <italic>$state_object</italic> is an instance of Test2::Harness::Runner::Resource::SharedJobSlots::State, while <italic>$state_data</italic> is a hashref like the one you get from $state_object->state() — which is lowkey useful if you want to know how many slots each runner is using, for that 'fair' style algorth (yes, that typo is in the original, we keep the lore 🫡).

Oh and go take a look at the request_sort_XXX methods on Test2::Harness::Runner::Resource::SharedJobSlots::State, because those implement the 3 original sorting methods. Homework. Not optional. 📚

---

🌟 SOURCE 🌟

The source code repository for Test2-Harness can be found at http://github.com/Test-More/Test2-Harness/. Go star her, she deserves it. ⭐

---

💜 MAINTAINERS 💜

• Chad Granum <exodist@cpan.org>

---

🌸 AUTHORS 🌸

• Chad Granum <exodist@cpan.org>

(the same legend, twice, respectfully 💖)

---

👑 COPYRIGHT 👑

Copyright 2022 Chad Granum <exodist7@gmail.com>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://dev.perl.org/licenses/

---

and that's the whole page bestie, no cap 🧚 — she was written for perl v5.40.1, dated 2026-05-10, and lives as Test2:...bSlots(3pm) in the User Contributed Perl Documentation, so go forth, share your slots, and stay within your max_slots 💅✨🍓