lei.chen/myxce
1
0
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(scheduler-controller-msg-gap): reconcile sched_op_name layering (bug-765 G-7)

Browse source 
The spec/design placed the scheduler-op name lookup as xce_sched_op_name in
lib/helper, but xce_sched_op_t is a scheduler-only type and src/lib must not
depend on scheduler headers — so it is correctly a static sched_op_name() in
scheduler.c. Code kept as-is (correct); docs amended to match:
- Task 1 intro + 1.1/1.3 + 5.7 + 9.1: scheduler-layer placement + layering note.
- design.md Component 8/9, file table, risks: same reconciliation.
Only xce_notify_event_name (int-typed, lib-level) lives in lib/helper.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Rongsong Shen 2026-06-19 03:51:01 +00:00
parent 93124c5601
commit 080ff78a80
2 changed files with 20 additions and 15 deletions
Download patch file Download diff file Expand all files Collapse all files

20
.kiro/specs/scheduler-controller-msg-gap/design.md
View file

@ -288,9 +288,11 @@ These are unreachable because `vtask_entry()` in `src/lib/xcectx.c` rewrites all
**Requirement traceability:** 2.1, 2.2
### Component 8: helper.c / helper.h — Name-lookup functions (Req 8)
### Component 8: Name-lookup functions (Req 8)
#### New function: `xce_notify_event_name`
> **Layering correction (bug-765 G-7, 2026-06-18):** these two helpers live in DIFFERENT layers. `xce_notify_event_name(int)` is lib-level and lives in `src/lib/helper.c` / `src/include/helper.h`. The scheduler-op name lookup operates on `xce_sched_op_t`, a **scheduler-only** type (`scheduler.h`); `src/lib` must not include scheduler headers (no layering inversion), so it is a **static `sched_op_name(xce_sched_op_t)` in `src/scheduler/src/scheduler.c`**, NOT `xce_sched_op_name` in lib/helper. The original "both in helper.c" text below is superseded for the scheduler-op helper.
#### New function: `xce_notify_event_name` (lib — `src/lib/helper.c`)
```
Signature: char* xce_notify_event_name(int event)
@ -301,16 +303,16 @@ Fallback: "UNKNOWN(%d)" with numeric substitution.
Matches pattern of `xce_dataset_table()` — takes int, returns `char*`.
#### New function: `xce_sched_op_name`
#### Scheduler-op name lookup: static `sched_op_name` (scheduler — `src/scheduler/src/scheduler.c`)
```
Signature: char* xce_sched_op_name(xce_sched_op_t op)
Signature: static char* sched_op_name(xce_sched_op_t op)
Behavior: Switch on XCE_SCHED_OP_* enum values, return symbolic string.
Fallback: "UNKNOWN(%d)" with numeric substitution.
```
Required for Requirement 7's error logging in `sched_update()`.
Kept in the scheduler layer (NOT lib/helper as `xce_sched_op_name`) because `xce_sched_op_t` is a scheduler-only type and `src/lib` must not depend on scheduler headers — see the layering correction above. Required for Requirement 7's error logging in `sched_update()`.
#### Changes to `handler.c` logging
@ -327,7 +329,7 @@ In the `sched_update()` main loop, after the `switch (req->op)` block, when `rc
```
WARN("%s: op %s failed: %s (%d)", __func__,
xce_sched_op_name(req->op), strerror(-rc), rc);
sched_op_name(req->op), strerror(-rc), rc);
```
**Requirement traceability:** 7.1
@ -443,8 +445,8 @@ xce_push_data_req()
| `src/scheduler/include/plugin.h` | Modified — add rusage hook typedef and global function | 6 |
| `src/scheduler/src/plugin.c` | Modified — add `plugin_job_rusage_update()` implementation | 6 |
| `src/scheduler/src/schedobj.c` | Modified — add `sched_update_existing_queue()` | 4 |
| `src/lib/helper.c` | Modified — add `xce_notify_event_name()`, `xce_sched_op_name()` | 8 |
| `src/include/helper.h` | Modified — add function declarations | 8 |
| `src/lib/helper.c` | Modified — add `xce_notify_event_name()` (lib-level, int arg); the scheduler-op name lookup is a static `sched_op_name()` in `scheduler.c` instead — see Component 8 layering note | 8 |
| `src/include/helper.h` | Modified — declare `xce_notify_event_name()` | 8 |
| `src/scheduler/testsuite/test.c` | Modified — add unit tests for all new handlers | All |
## Build Order
@ -466,4 +468,4 @@ xce_push_data_req()
| Memory ownership of queued data — capnp-decoded structs freed before dequeue processes them | High | Follow existing pattern: for dataset paths, nullify `dataset->nrows`/`dataset->rows` after enqueue to transfer ownership. For notify paths, copy essential data into the request struct rather than holding pointers to capnp memory. |
| `sched_update_existing_job` must handle concurrent modification — handler thread enqueues while main thread processes | Medium | Already mitigated by existing double-buffer swap in `sched_update()`. The handler thread only touches `pend_updates[0]` while the main thread drains `pend_updates[1]`. |
| New `UPDATE_QUEUE` op requires queue name lookup — potential lock contention | Low | `sched_get_queue()` already uses read lock. Queue updates are infrequent. |
| `xce_sched_op_name` must handle future enum additions | Low | Follow `xce_dataset_table` pattern — return `"UNKNOWN(%d)"` for unrecognized values. |
| `sched_op_name` (static, scheduler.c) must handle future enum additions | Low | Follow `xce_dataset_table` pattern — return `"UNKNOWN(%d)"` for unrecognized values. |