fgof-jobs Public

Watch 0 Fork 0 Star 0
markdown · 4837 bytes Raw Blame History

fgof-jobs

Background job, process-group, and wait-model helpers for modern Fortran.

fgof-jobs is intended to be a small, standalone library for the parts of job control that shells, supervisors, and long-running tool hosts usually end up rebuilding locally.

It is part of the FortranGoingOnForty lib-modules catalog, but it is intended to stand on its own as a normal fpm package.

Current v1 target:

  • stable job spec, job handle, and job result types
  • job-state helpers that can support foreground and background process groups
  • room for wait, signal, and pipeline helpers without forcing shell UI policy

Future scope:

  • pipeline helpers layered over fgof-process
  • signal and terminal handoff helpers
  • examples for shell-like and tool-runner workflows

Status

Sprint 04 is in place.

Tracked today:

  • package layout, CI, and standalone repo setup
  • foundational job types for specs, handles, and results
  • explicit configure, attach, complete, and release lifecycle helpers
  • explicit process-group ownership tracking on job handles
  • wait-result constructors for exited, signaled, stopped, and continued outcomes
  • state-transition helpers that distinguish stopped jobs from terminal jobs
  • grouped pipeline-member tracking on job handles
  • explicit signal-forwarding and terminal-handoff policy fields
  • pipeline-aware stop, continue, and completion aggregation
  • tracked examples for lifecycle and pipeline state transitions
  • replacement-safe pipeline member attachment and cleaner group-stop member results
  • CI now runs both tests and tracked examples

Public API Shape

Primary modules:

  • fgof_jobs
  • fgof_jobs_types

Public types:

  • job_spec
  • job_handle
  • job_result

Current public procedures:

  • clear_job_spec
  • clear_job_handle
  • clear_job_result
  • make_job_spec
  • configure_job
  • attach_job
  • attach_pipeline_members
  • complete_job
  • observe_wait_result
  • release_job
  • clear_job_member
  • job_exit_result
  • job_signal_result
  • job_stop_result
  • job_continue_result
  • job_is_configured
  • job_is_running
  • job_is_stopped
  • job_is_finished
  • job_needs_cleanup
  • job_owns_process_group
  • job_signal_scope
  • job_resume_sends_sigcont
  • job_requires_terminal_handoff
  • pipeline_member_count
  • jobs_backend_name

Current semantics:

  • job_spec carries the intended command, argument vector, and foreground/background intent
  • make_job_spec() builds a reusable spec value for later launch or attach work
  • configure_job() resets a handle into a configured-but-not-running state from a spec
  • attach_job() records pid/process-group identity for an already launched job and establishes both process and process-group ownership expectations
  • attach_pipeline_members() binds one handle to multiple tracked member pids for pipeline-style jobs
  • job_exit_result(), job_signal_result(), job_stop_result(), and job_continue_result() build explicit wait outcomes for later launch or wait backends
  • observe_wait_result() applies non-terminal and terminal wait state transitions to a tracked handle and now updates pipeline members too
  • complete_job() now models terminal completion only and clears runtime cleanup obligations after exit or signal outcomes
  • release_job() drops cleanup ownership while preserving runtime tracking metadata
  • job_is_configured(), job_is_running(), job_is_stopped(), job_is_finished(), job_needs_cleanup(), and job_owns_process_group() expose the current stable lifecycle predicates
  • job_signal_scope(), job_resume_sends_sigcont(), and job_requires_terminal_handoff() make signal and terminal assumptions explicit for future backends
  • job_handle is now the explicit ownership point for a launched job group, and may track member-level pipeline state
  • job_result now carries pid/process-group identity plus exited, signaled, stopped, and continued wait outcomes
  • grouped pipeline jobs only finish once all tracked members have reached terminal outcomes
  • reattaching pipeline members replaces the previous tracked member set cleanly
  • group-scoped stop fanout preserves each tracked member pid in member-level results
  • jobs_backend_name() currently reports the planned backend family and exists to stabilize the package surface early

Build And Test

fpm test

Tracked examples:

Supported Platforms

  • macOS
  • Linux

Boundaries

  • intended to stay independently versioned and releasable
  • focused on reusable job-control mechanics first, not full shell policy
  • should remain useful on its own even if future shells or supervisors build on top

License

MIT

View source
1 # fgof-jobs
2
3 Background job, process-group, and wait-model helpers for modern Fortran.
4
5 `fgof-jobs` is intended to be a small, standalone library for the parts of job
6 control that shells, supervisors, and long-running tool hosts usually end up
7 rebuilding locally.
8
9 It is part of the [FortranGoingOnForty lib-modules](https://github.com/FortranGoingOnForty/lib-modules)
10 catalog, but it is intended to stand on its own as a normal `fpm` package.
11
12 Current v1 target:
13
14 - stable job spec, job handle, and job result types
15 - job-state helpers that can support foreground and background process groups
16 - room for wait, signal, and pipeline helpers without forcing shell UI policy
17
18 Future scope:
19
20 - pipeline helpers layered over `fgof-process`
21 - signal and terminal handoff helpers
22 - examples for shell-like and tool-runner workflows
23
24 ## Status
25
26 Sprint 04 is in place.
27
28 Tracked today:
29
30 - package layout, CI, and standalone repo setup
31 - foundational job types for specs, handles, and results
32 - explicit configure, attach, complete, and release lifecycle helpers
33 - explicit process-group ownership tracking on job handles
34 - wait-result constructors for exited, signaled, stopped, and continued outcomes
35 - state-transition helpers that distinguish stopped jobs from terminal jobs
36 - grouped pipeline-member tracking on job handles
37 - explicit signal-forwarding and terminal-handoff policy fields
38 - pipeline-aware stop, continue, and completion aggregation
39 - tracked examples for lifecycle and pipeline state transitions
40 - replacement-safe pipeline member attachment and cleaner group-stop member results
41 - CI now runs both tests and tracked examples
42
43 ## Public API Shape
44
45 Primary modules:
46
47 - `fgof_jobs`
48 - `fgof_jobs_types`
49
50 Public types:
51
52 - `job_spec`
53 - `job_handle`
54 - `job_result`
55
56 Current public procedures:
57
58 - `clear_job_spec`
59 - `clear_job_handle`
60 - `clear_job_result`
61 - `make_job_spec`
62 - `configure_job`
63 - `attach_job`
64 - `attach_pipeline_members`
65 - `complete_job`
66 - `observe_wait_result`
67 - `release_job`
68 - `clear_job_member`
69 - `job_exit_result`
70 - `job_signal_result`
71 - `job_stop_result`
72 - `job_continue_result`
73 - `job_is_configured`
74 - `job_is_running`
75 - `job_is_stopped`
76 - `job_is_finished`
77 - `job_needs_cleanup`
78 - `job_owns_process_group`
79 - `job_signal_scope`
80 - `job_resume_sends_sigcont`
81 - `job_requires_terminal_handoff`
82 - `pipeline_member_count`
83 - `jobs_backend_name`
84
85 Current semantics:
86
87 - `job_spec` carries the intended command, argument vector, and foreground/background intent
88 - `make_job_spec()` builds a reusable spec value for later launch or attach work
89 - `configure_job()` resets a handle into a configured-but-not-running state from a spec
90 - `attach_job()` records pid/process-group identity for an already launched job and establishes both process and process-group ownership expectations
91 - `attach_pipeline_members()` binds one handle to multiple tracked member pids for pipeline-style jobs
92 - `job_exit_result()`, `job_signal_result()`, `job_stop_result()`, and `job_continue_result()` build explicit wait outcomes for later launch or wait backends
93 - `observe_wait_result()` applies non-terminal and terminal wait state transitions to a tracked handle and now updates pipeline members too
94 - `complete_job()` now models terminal completion only and clears runtime cleanup obligations after exit or signal outcomes
95 - `release_job()` drops cleanup ownership while preserving runtime tracking metadata
96 - `job_is_configured()`, `job_is_running()`, `job_is_stopped()`, `job_is_finished()`, `job_needs_cleanup()`, and `job_owns_process_group()` expose the current stable lifecycle predicates
97 - `job_signal_scope()`, `job_resume_sends_sigcont()`, and `job_requires_terminal_handoff()` make signal and terminal assumptions explicit for future backends
98 - `job_handle` is now the explicit ownership point for a launched job group, and may track member-level pipeline state
99 - `job_result` now carries pid/process-group identity plus exited, signaled, stopped, and continued wait outcomes
100 - grouped pipeline jobs only finish once all tracked members have reached terminal outcomes
101 - reattaching pipeline members replaces the previous tracked member set cleanly
102 - group-scoped stop fanout preserves each tracked member pid in member-level results
103 - `jobs_backend_name()` currently reports the planned backend family and exists to stabilize the package surface early
104
105 ## Build And Test
106
107 ```bash
108 fpm test
109 ```
110
111 Tracked examples:
112
113 - [job_lifecycle_demo.f90](example/job_lifecycle_demo.f90)
114 - [pipeline_tracking_demo.f90](example/pipeline_tracking_demo.f90)
115
116 ## Supported Platforms
117
118 - macOS
119 - Linux
120
121 ## Boundaries
122
123 - intended to stay independently versioned and releasable
124 - focused on reusable job-control mechanics first, not full shell policy
125 - should remain useful on its own even if future shells or supervisors build on top
126
127 ## License
128
129 MIT