Skip to content

Commit 94f2bdf

Browse files
perazzperazz
committed
document is_running, is_completed, elapsed 
1 parent d8df028 commit 94f2bdf

File tree

2 files changed

+194
-6
lines changed

2 files changed

+194
-6
lines changed

‎doc/specs/stdlib_system.md

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,4 +49,141 @@ p(1) = run("echo 'Hello, world!'", wait=.true., want_stdout=.true.)
4949
5050
! Run a command using an argument list asynchronously
5151
p(2) = run(["/usr/bin/ls", "-l"], wait=.false.)
52+
```
53+
54+
## `is_running` - Check if a process is still running
55+
56+
### Status
57+
58+
Experimental
59+
60+
### Description
61+
62+
The `is_running` interface provides a method to check if an external process is still running.
63+
This is useful for monitoring the status of asynchronous processes created with the `run` interface.
64+
65+
### Syntax
66+
67+
`status = ` [[stdlib_subprocess(module):is_running(interface)]] `(process)`
68+
69+
### Arguments
70+
71+
`process`: Shall be a `type(process_type)` object representing the external process to check. This is an `intent(inout)` argument.
72+
73+
74+
### Return Value
75+
76+
Returns a `logical` value: `.true.` if the process is still running, or `.false.` if the process has terminated.
77+
After a call to `is_running`, the `type(process_type)` structure is also updated to the latest process state.
78+
79+
### Example
80+
81+
```fortran
82+
! Example usage of is_running
83+
type(process_type) :: proc
84+
logical :: status
85+
86+
! Start an asynchronous process
87+
proc = run("sleep 10", wait=.false.)
88+
89+
! Check if the process is running
90+
status = is_running(proc)
91+
92+
if (status) then
93+
print *, "Process is still running."
94+
else
95+
print *, "Process has terminated."
96+
end if
97+
```
98+
99+
## `is_completed` - Check if a process has completed execution
100+
101+
### Status
102+
103+
Experimental
104+
105+
### Description
106+
107+
The `is_completed` interface provides a method to check if an external process has finished execution.
108+
This is useful for determining whether asynchronous processes created with the `run` interface have terminated.
109+
110+
### Syntax
111+
112+
`status = ` [[stdlib_subprocess(module):is_completed(interface)]] `(process)`
113+
114+
### Arguments
115+
116+
`process`: Shall be a `type(process_type)` object representing the external process to check. This is an `intent(inout)` argument.
117+
118+
### Return Value
119+
120+
Returns a `logical` value:
121+
- `.true.` if the process has completed.
122+
- `.false.` if the process is still running.
123+
124+
After a call to `is_completed`, the `type(process_type)` structure is updated to reflect the latest process state.
125+
126+
### Example
127+
128+
```fortran
129+
! Example usage of is_completed
130+
type(process_type) :: proc
131+
logical :: status
132+
133+
! Start an asynchronous process
134+
proc = run("sleep 5", wait=.false.)
135+
136+
! Check if the process has completed
137+
status = is_completed(proc)
138+
139+
if (status) then
140+
print *, "Process has completed."
141+
else
142+
print *, "Process is still running."
143+
end if
144+
```
145+
146+
## `elapsed` - Return process lifetime in seconds
147+
148+
### Status
149+
150+
Experimental
151+
152+
### Description
153+
154+
The `elapsed` interface provides a method to calculate the total time that has elapsed since a process was started.
155+
This is useful for tracking the duration of an external process or for performance monitoring purposes.
156+
157+
The result is a real value representing the elapsed time in seconds, measured from the time the process was created.
158+
159+
### Syntax
160+
161+
`delta_t = ` [[stdlib_subprocess(module):elapsed(interface)]] `(process)`
162+
163+
### Arguments
164+
165+
`process`: Shall be a `type(process_type)` object representing the external process. It is an `intent(in)` argument.
166+
167+
### Return Value
168+
169+
Returns a `real(real64)` value that represents the elapsed time (in seconds) since the process was started.
170+
If the process is still running, the value returned is the time elapsed until the call to this function.
171+
Otherwise, the total process duration from creation until completion is returned.
172+
173+
### Example
174+
175+
```fortran
176+
! Example usage of elapsed
177+
type(process_type) :: p
178+
real(RTICKS) :: delta_t
179+
180+
! Create a process
181+
p = run("sleep 5", wait=.false.)
182+
183+
! Check elapsed time after 2 seconds
184+
call sleep(2)
185+
delta_t = elapsed(p)
186+
print *, "Elapsed time (s): ", delta_t
187+
```
188+
52189

‎src/stdlib_system.F90

Lines changed: 57 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ module stdlib_system
7272
!!
7373
!! @note The implementation depends on system-level process management capabilities.
7474
!!
75-
!! #### Procedures
75+
!! #### Methods
7676
!!
7777
!! - `process_open_cmd`: Opens a process using a command string.
7878
!! - `process_open_args`: Opens a process using an array of arguments.
@@ -104,28 +104,79 @@ module type(process_type) function process_open_args(args, wait, stdin, want_std
104104
end function process_open_args
105105
end interface run
106106

107-
108-
!> Live check if a process is still running
109107
interface is_running
108+
!! version: experimental
109+
!!
110+
!! Checks if an external process is still running.
111+
!! ([Specification](../page/specs/stdlib_system.html#is_running-check-if-a-process-is-still-running))
112+
!!
113+
!! ### Summary
114+
!! Provides a method to determine if an external process is still actively running.
115+
!!
116+
!! ### Description
117+
!!
118+
!! This interface checks the status of an external process to determine whether it is still actively running.
119+
!! It is particularly useful for monitoring asynchronous processes created using the `run` interface.
120+
!! The internal state of the `process_type` object is updated after the call to reflect the current process status.
121+
!!
122+
!! @note The implementation relies on system-level process management capabilities.
123+
!!
110124
module logical function process_is_running(process) result(is_running)
125+
!> The process object to check.
111126
class(process_type), intent(inout) :: process
127+
!> Logical result: `.true.` if the process is still running, `.false.` otherwise.
112128
end function process_is_running
113129
end interface is_running
114130

115-
!> Live check if a process is still running
131+
116132
interface is_completed
133+
!! version: experimental
134+
!!
135+
!! Checks if an external process has completed execution.
136+
!! ([Specification](../page/specs/stdlib_system.html#is_completed-check-if-a-process-has-completed-execution))
137+
!!
138+
!! ### Summary
139+
!! Provides a method to determine if an external process has finished execution.
140+
!!
141+
!! ### Description
142+
!!
143+
!! This interface checks the status of an external process to determine whether it has finished execution.
144+
!! It is particularly useful for monitoring asynchronous processes created using the `run` interface.
145+
!! The internal state of the `process_type` object is updated after the call to reflect the current process status.
146+
!!
147+
!! @note The implementation relies on system-level process management capabilities.
148+
!!
117149
module logical function process_is_completed(process) result(is_completed)
150+
!> The process object to check.
118151
class(process_type), intent(inout) :: process
152+
!> Logical result: `.true.` if the process has completed, `.false.` otherwise.
119153
end function process_is_completed
120154
end interface is_completed
121155

122-
!> Return process lifetime so far, in seconds
123156
interface elapsed
157+
!! version: experimental
158+
!!
159+
!! Returns the lifetime of a process, in seconds.
160+
!! ([Specification](../page/specs/stdlib_system.html#elapsed-return-process-lifetime-in-seconds))
161+
!!
162+
!! ### Summary
163+
!! Provides the total elapsed time (in seconds) since the creation of the specified process.
164+
!!
165+
!! ### Description
166+
!!
167+
!! This interface returns the total elapsed time (in seconds) for a given process since it was started.
168+
!! If the process is still running, the value returned reflects the time from the creation of the process
169+
!! until the call to this function. Otherwise, the total process duration until completion is returned.
170+
!!
124171
module real(RTICKS) function process_lifetime(process) result(delta_t)
125-
class(process_type), intent(in) :: process
172+
!> The process object for which to calculate elapsed time.
173+
class(process_type), intent(in) :: process
174+
!> The elapsed time in seconds since the process started.
175+
real(RTICKS) :: delta_t
126176
end function process_lifetime
127177
end interface elapsed
128178

179+
129180
!> Wait until a running process is completed
130181
interface wait
131182
module subroutine wait_for_completion(process, max_wait_time)

0 commit comments

Comments
 (0)