71 lines
5.5 KiB
Markdown
71 lines
5.5 KiB
Markdown
# Requirements Document
|
|
|
|
## Project Description (Input)
|
|
Simplify the code of worker join in the controller by first checking whether the host is in `workermgr`; if it does not exist, create the host first; otherwise find the host in `workermgr` and update the host attrs and endpoint. Then update host status and resource information.
|
|
|
|
## Introduction
|
|
|
|
The controller's `handle_worker_join` function currently delegates the entire create-or-update decision to `add_worker`, which in turn delegates to `makeWorker` in `wobj.c`. The internal branching is invisible at the call site and the locking structure is confusing (the outer join handler holds the `workermgr` write lock while `makeWorker` re-acquires the same lock). This refactor restructures the worker join path so the check → create-or-update → status/resource-update sequence is explicit and readable.
|
|
|
|
## Boundary Context
|
|
|
|
- **In scope**: `handle_worker_join` in `src/controller/join.c` and `add_worker` in `src/controller/worker.c`.
|
|
- **Out of scope**: `makeWorker` in `src/lib/wobj.c`, other join handlers (`handle_client_join`, `handle_scheduler_join`, etc.), job dispatch, and the persist/WAL subsystem behavior.
|
|
- **Adjacent expectations**: Persist hooks (`XCE_CONTROLLER_HOOK_WORKER`) must still fire at the same event points (BEFORE_EVENT / AFTER_EVENT for HOOK_DETAIL_WORKER_JOIN). The `on_worker_join` callback that pushes configuration to the worker must still be called after a successful join.
|
|
|
|
## Requirements
|
|
|
|
### Requirement 1: Explicit Host Existence Check
|
|
|
|
**Objective:** As a controller maintainer, I want the worker join code to make an explicit lookup before deciding whether to create or update, so that the control flow is readable without tracing into `makeWorker`.
|
|
|
|
#### Acceptance Criteria
|
|
1. When a worker join request is received, the Controller shall look up the joining host by name in `workermgr` using `key_find` before taking any create-or-update action.
|
|
2. The Controller shall branch on the result of that lookup: one branch for a host that does not yet exist, one branch for a host that already exists.
|
|
3. If `key_find` returns an error other than `-ENOENT`, the Controller shall reject the join and return that error code.
|
|
|
|
---
|
|
|
|
### Requirement 2: Host Creation for First-Time Workers
|
|
|
|
**Objective:** As a controller maintainer, I want a new host entry to be created when a worker joins for the first time, so that the cluster knows about this node.
|
|
|
|
#### Acceptance Criteria
|
|
1. When the host is not found in `workermgr`, the Controller shall allocate and register a new worker entry (via the existing `makeWorker` or equivalent creation path) using the joining worker's name and host attributes.
|
|
2. If creation fails, the Controller shall log the failure, set the reply status to the error code, and return without calling `on_worker_join`.
|
|
3. The Controller shall assign the new entry's index to `priv->u.idx` so subsequent disconnect handling can find the worker.
|
|
|
|
---
|
|
|
|
### Requirement 3: Attribute and Endpoint Update for Rejoining Workers
|
|
|
|
**Objective:** As a controller maintainer, I want an existing worker entry to be updated in-place when the same host rejoins, so that stale attributes and the old disconnected endpoint are replaced.
|
|
|
|
#### Acceptance Criteria
|
|
1. When the host already exists in `workermgr`, the Controller shall update the existing worker's host attributes (`hostattrs`) with the values supplied in the join message.
|
|
2. When the host already exists in `workermgr`, the Controller shall update the existing worker's endpoint (`ep`) to the new connection's endpoint.
|
|
3. The Controller shall preserve any admin-set status bits (`XCE_WORKER_LOCKEDU`, `XCE_WORKER_CLOSED`, `XCE_WORKER_HIDDEN`, `XCE_WORKER_CLOSED_BY_ADMIN`) when updating an existing entry.
|
|
|
|
---
|
|
|
|
### Requirement 4: Status and Resource Information Update
|
|
|
|
**Objective:** As a controller maintainer, I want status and resource data to be updated after every successful join (both new and rejoining), so that the scheduler sees accurate host availability and capacity.
|
|
|
|
#### Acceptance Criteria
|
|
1. After a successful create or update, the Controller shall clear the `XCE_WORKER_UNAVAIL` flag on the worker's status.
|
|
2. After a successful create or update, the Controller shall apply host-config overrides (hosttype, hostmodel, mxj slots, dispatch window, thresholds, and boolean resources) from the matched `xce_hostconfig_t`.
|
|
3. After a successful create or update, the Controller shall update all host-attribute-mapped resource values (`type`, `model`, `cpuf`, `maxcpus`, `maxmem`, `maxswap`, `maxtmp`, `ndisks`, `slots`).
|
|
4. If `find_matched_hostconfig` returns `NULL`, the Controller shall reject the join with an appropriate error code and not modify `workermgr`.
|
|
|
|
---
|
|
|
|
### Requirement 5: Behavioral Preservation
|
|
|
|
**Objective:** As a developer, I want the refactored code to preserve all existing observable behavior so that no regressions are introduced.
|
|
|
|
#### Acceptance Criteria
|
|
1. The Controller shall fire `XCE_CONTROLLER_HOOK_WORKER / HOOK_BEFORE_EVENT / HOOK_DETAIL_WORKER_JOIN` before modifying the worker entry, and `HOOK_AFTER_EVENT / HOOK_DETAIL_WORKER_JOIN` after modification, matching the existing hook invocation order.
|
|
2. The Controller shall call `on_worker_join` after a successful join (both new and rejoin) to push configuration to the worker.
|
|
3. While the `workermgr` write lock is held during the join operation, the Controller shall keep the critical section as short as the current implementation.
|
|
4. The existing unit tests in `src/controller/testsuite/` shall pass without modification.
|