Skip to content

docs(config): clarify per-type WORKER_*_MAX_SLOTS is a reservation floor, not a cap - #2987

Closed
nicoloboschi wants to merge 1 commit into
mainfrom
docs-worker-slot-reservation-clarify
Closed

docs(config): clarify per-type WORKER_*_MAX_SLOTS is a reservation floor, not a cap#2987
nicoloboschi wants to merge 1 commit into
mainfrom
docs-worker-slot-reservation-clarify

Conversation

@nicoloboschi

Copy link
Copy Markdown
Collaborator

What

Documentation-only fix for #2963. The per-operation HINDSIGHT_API_WORKER_<TYPE>_MAX_SLOTS env vars are named like a per-type ceiling but actually set a reserved minimum (a floor). A type is guaranteed at least its reservation and may then overflow into the shared pool (WORKER_MAX_SLOTS - sum(reservations)) up to WORKER_MAX_SLOTS. So the name reads as the opposite of the behaviour, which cost the reporter a production latency investigation over a consolidation=6/1(avail=0) log line that was working as designed.

Changes

  • Config-table entries for every *_MAX_SLOTS now say Reserved (minimum) slots … a floor, not a per-type cap.
  • New warning admonition spelling out:
    • the real ceiling: reserved(type) + shared pool currently available;
    • that lowering the value lowers the guarantee, not the ceiling (e.g. CONSOLIDATION_MAX_SLOTS=1 still allows up to 10 concurrent);
    • the consolidation per-bank serialization caveat;
    • the only way to actually cap a type today — reserve the whole pool so the shared pool is zero (worked example).
  • Mirrored into versioned_docs/version-0.8 so it appears on the live site (production ships released versions only, not current).

Scope

Docs only — no behaviour change. Verified against config.py (WORKER_SLOT_RESERVATION_TYPES, the total_reserved <= worker_max_slots floor-shaped validation), worker/poller.py (_get_available_slots), and engine/db/ops_postgresql.py::claim_tasks (reserved phase + shared phase claims for any type).

A rename to *_RESERVED_SLOTS (with a deprecated alias) and/or an actual per-type ceiling knob — both suggested in the issue — are larger, behaviour-changing follow-ups intentionally left out of this PR.

Closes #2963

…oor, not a cap

The HINDSIGHT_API_WORKER_<TYPE>_MAX_SLOTS env vars set a reserved minimum
(a floor) for each operation type, not a per-type ceiling. A type can
overflow its reservation into the shared pool up to WORKER_MAX_SLOTS, so
the name reads as the opposite of the behaviour (issue #2963).

Clarify the config table entries and add a warning admonition explaining
the real ceiling (reserved + shared) and the only way to actually cap a
type today (reserve the whole pool so the shared pool is zero). Mirrored
into the published version-0.8 docs so it appears on the live site.
@nicoloboschi

Copy link
Copy Markdown
Collaborator Author

Superseded by #3016, which does the full rename (RESERVED_SLOTS floor + MAX_CONCURRENT ceiling, deprecated MAX_SLOTS alias) and includes the same docs clarification. Closing in favor of that.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

HINDSIGHT_API_WORKER_<TYPE>_MAX_SLOTS is a minimum, not a maximum

1 participant