myxce/.kiro/specs/scheduler-controller-msg-gap/tasks.md

Tasks: scheduler-controller-msg-gap

Generated: 2026-05-11T19:30:00-07:00 Feature: scheduler-controller-msg-gap Status: Tasks Generated

Overview

Implementation tasks for filling gaps in the scheduler's handling of controller messages. The work follows the design's build order: shared helpers first, then header definitions, plugin hooks, business logic, handler wiring, and finally tests.

---

Task 1: Add name-lookup helpers to lib/helper

Requirements: 8

Add xce_notify_event_name() and xce_sched_op_name() to src/lib/helper.c and declare them in src/include/helper.h, following the exact pattern of the existing xce_dataset_table() helper (int argument, char* return, "UNKNOWN(%d)" fallback).

• 1.1 Declare xce_notify_event_name(int event) and xce_sched_op_name(xce_sched_op_t op) in src/include/helper.h
• 1.2 Implement xce_notify_event_name() in src/lib/helper.c — switch on all NotifyData_data_* enum values; return symbolic string; fall back to "UNKNOWN(%d)"
• 1.3 Implement xce_sched_op_name() in src/lib/helper.c — switch on all XCE_SCHED_OP_* enum values; return symbolic string; fall back to "UNKNOWN(%d)"

---

Task 2: Extend scheduler.h with new op types and request fields

Requirements: 1, 3, 4, 5, 6

Add five new xce_sched_op_t enum values and five corresponding union members in xce_sched_update_request_t to carry the payloads for queue update, resource update, full resval update, incremental resval update, and job rusage.

• 2.1 Add XCE_SCHED_OP_UPDATE_QUEUE, XCE_SCHED_OP_UPDATE_RESOURCES, XCE_SCHED_OP_UPDATE_RESVALS_FULL, XCE_SCHED_OP_UPDATE_RESVALS, and XCE_SCHED_OP_JOB_RUSAGE to the xce_sched_op_t enum in src/scheduler/include/scheduler.h
• 2.2 Add the corresponding named union members (queueupdate, resourceupdate, resvalfullupdate, resvalupdate, job_rusage) to xce_sched_update_request_t

---

Task 3: Add plugin rusage hook

Requirements: 6

Add the plugin_job_rusage_hook_t typedef, the rusage_hook field in plugin_hooks_t, and the plugin_job_rusage_update() global function. This follows the identical pattern used by plugin_job_state_change().

• 3.1 Add plugin_job_rusage_hook_t typedef and rusage_hook field to plugin_hooks_t in src/scheduler/include/plugin.h
• 3.2 Implement plugin_job_rusage_update() in src/scheduler/src/plugin.c — iterate registered plugins and call their rusage_hook when non-NULL

---

Task 4: Add queue update function in schedobj.c

Requirements: 4

Implement sched_update_existing_queue() in src/scheduler/src/schedobj.c. The function locates a queue by name via sched_get_queue(), updates its mutable fields (status, priority, accept_interval, sched_delay, resreq string), calls plugin_queue_update(), and returns -ENOENT if the queue is unknown.

• 4.1 Implement sched_update_existing_queue(xce_scheduler_t*, xce_queue_t*) in src/scheduler/src/schedobj.c with correct lookup, field update, string reallocation for resreq, plugin call, and error returns

---

Task 5: Extend scheduler.c dequeue processing and error logging

Requirements: 1, 3, 4, 5, 6, 7

Wire the five new op types into the switch (req->op) in sched_update(), implement sched_update_existing_job(), and add WARN-level error logging after the switch when a handler returns non-zero.

• 5.1 Add XCE_SCHED_OP_UPDATE_QUEUE case — delegate to sched_update_existing_queue(), return -ENOENT when queue not found
• 5.2 Add XCE_SCHED_OP_UPDATE_RESOURCES case — iterate resdata->resources[], call makeResource(sched->resmgr, r) for each non-NULL entry
• 5.3 Add XCE_SCHED_OP_UPDATE_RESVALS_FULL case — iterate resvaldata->vals[], find resource in sched->resmgr by name, update value; log WARN and skip unknown resources
• 5.4 Add XCE_SCHED_OP_UPDATE_RESVALS case — iterate resvals->vals[], find worker by host name via sched_get_worker(), update worker's resvals zarray; silently skip unknown hosts
• 5.5 Add XCE_SCHED_OP_JOB_RUSAGE case — find job by jobid, store rusage data, call plugin_job_rusage_update(); return -ENOENT if job not found
• 5.6 Implement sched_update_existing_job() — find job by jobid via sched_get_job(), update mutable fields (state, priority, allocs), call plugin_job_update(); return -ENOENT when jobid is unknown
• 5.7 Add WARN log in sched_update() after switch block for non-zero rc — include symbolic op name via xce_sched_op_name() and strerror(-rc)
• 5.8 Extend sched_pend_update_killer with no-op cases for all five new op types to suppress unhandled-case compiler warnings

---

Task 6: Wire notify handlers in handler.c

Requirements: 3, 4, 5, 6, 8

Add four static handler functions for the currently-stubbed NotifyData events, wire them into sched_handle_notify(), and update the TRACE log calls in sched_handle_notify() and sched_handle_dataset() to use symbolic name helpers.

• 6.1 Implement sched_handle_sched_update_job() — validate non-NULL, enqueue XCE_SCHED_OP_UPDATE_JOB; return -EINVAL on NULL, -ENOMEM on alloc failure
• 6.2 Implement sched_handle_sched_update_queue() — validate non-NULL, enqueue XCE_SCHED_OP_UPDATE_QUEUE; return -EINVAL on NULL, -ENOMEM on alloc failure
• 6.3 Implement sched_handle_sched_update_resvals() — skip if NULL or count==0, enqueue XCE_SCHED_OP_UPDATE_RESVALS; return -ENOMEM on alloc failure
• 6.4 Implement sched_handle_sched_job_rusage() — validate non-NULL, enqueue XCE_SCHED_OP_JOB_RUSAGE; return -EINVAL on NULL, -ENOMEM on alloc failure
• 6.5 Wire all four handlers into sched_handle_notify() switch — replace stub break / TRACE-only cases
• 6.6 Update TRACE log in sched_handle_dataset() from %d table integer to %s via xce_dataset_table() (8.2), and update notify event logs to use xce_notify_event_name() (8.3)

---

Task 7: Add dataset handlers in handler.c

Requirements: 1, 8

Add sched_handle_resources() and sched_handle_resvals() static functions and wire them into the sched_handle_dataset() switch for the two currently-empty Data table cases. Update the existing opcode log in scheduler_req_handler to use xce_request_op_name().

• 7.1 Implement sched_handle_resources() — skip if NULL or count==0, enqueue XCE_SCHED_OP_UPDATE_RESOURCES; return -ENOMEM on alloc failure
• 7.2 Implement sched_handle_resvals() — skip if NULL or count==0, enqueue XCE_SCHED_OP_UPDATE_RESVALS_FULL; return -ENOMEM on alloc failure
• 7.3 Wire sched_handle_resources() and sched_handle_resvals() into sched_handle_dataset() switch replacing the empty break cases
• 7.4 Update opcode log in scheduler_req_handler to call xce_request_op_name() instead of printing the numeric value (8.1)

---

Task 8: Remove dead code pushmsg branches

Requirements: 2

Delete the Request_body_pushmsg case block from scheduler_req_handler() and the static functions sched_handle_jobpush() and sched_handle_workerpush(). These paths are unreachable because vtask_entry() rewrites all pushmsg into datamsg before invoking the handler.

• 8.1 Remove the Request_body_pushmsg case and its two nested branches (job/worker) from scheduler_req_handler() in src/scheduler/src/handler.c
• 8.2 Remove the static function definitions sched_handle_jobpush() and sched_handle_workerpush() from src/scheduler/src/handler.c

---

Task 9: Write unit tests for all new message handlers

Requirements: 1, 2, 3, 4, 5, 6, 7, 8

Extend src/scheduler/testsuite/test.c with unit tests covering every acceptance criterion. Tests must run without a live server — use stub schedulers, table-driven cases, and the existing testsuite harness.

• 9.1 Test xce_notify_event_name() and xce_sched_op_name() — verify known values return correct strings, unknown values return "UNKNOWN(%d)" format
• 9.2 Test sched_handle_resources() and sched_handle_resvals() handler functions — verify enqueue on valid input, skip on NULL/empty, -ENOMEM path
• 9.3 Test sched_handle_sched_update_job(), sched_handle_sched_update_queue(), sched_handle_sched_update_resvals(), sched_handle_sched_job_rusage() — verify -EINVAL on NULL, enqueue on valid input
• 9.4 Test sched_update_existing_job() — verify -ENOENT for unknown jobid, correct field update and plugin call for known jobid
• 9.5 Test sched_update_existing_queue() — verify -ENOENT for unknown queue, correct field update and plugin call for known queue; verify -EINVAL on NULL payload
• 9.6 Test dequeue path for XCE_SCHED_OP_UPDATE_RESVALS — verify unknown host skipped, known host updated
• 9.7 Test dequeue path for XCE_SCHED_OP_JOB_RUSAGE — verify -ENOENT for unknown jobid, rusage stored and plugin called for known jobid; verify -EINVAL on NULL rusage
• 9.8 Verify dead code symbols are absent — compile-time check that sched_handle_jobpush / sched_handle_workerpush are not defined (2.1, 2.2)
• [~] 9.9 (gated: log capture infrastructure) Verify WARN log is emitted in sched_update() when any handler returns a non-zero error code (optional — may require log capture infrastructure)