split run vs runasync

perazz · perazz · commit a1aaf2fe6dce · 2025-01-28T19:54:46.000+01:00
diff --git a/example/system/example_process_1.f90 b/example/system/example_process_1.f90
@@ -7,7 +7,7 @@ program run_sync
     logical :: completed
 
     ! Run a synchronous process to list directory contents
-    p = run("ls -l", wait=.true., want_stdout=.true.)
+    p = run("ls -l", want_stdout=.true.)
 
     ! Check if the process is completed (should be true since wait=.true.)
     if (is_completed(p)) then
diff --git a/example/system/example_process_2.f90 b/example/system/example_process_2.f90
@@ -1,12 +1,12 @@
 ! Process example 2: Run an Asynchronous Command and check its status
 program run_async
-    use stdlib_system, only: process_type, run, is_running, wait
+    use stdlib_system, only: process_type, runasync, is_running, wait
     implicit none
 
     type(process_type) :: p
 
     ! Run an asynchronous process to sleep for 1 second
-    p = run("sleep 1", wait=.false.)
+    p = runasync("sleep 1")
 
     ! Check if the process is running
     if (is_running(p)) then
diff --git a/example/system/example_process_3.f90 b/example/system/example_process_3.f90
@@ -11,8 +11,8 @@ program run_with_args
     args(1) = "echo"
     args(2) = "Hello, Fortran!"
 
-    ! Run the command with arguments
-    p = run(args, wait=.true.)
+    ! Run the command with arguments (synchronous)
+    p = run(args)
 
     ! Print the runtime of the process
     print *, "Process runtime:", elapsed(p), "seconds."
diff --git a/example/system/example_process_4.f90 b/example/system/example_process_4.f90
@@ -1,15 +1,15 @@
 ! Process example 4: Kill a running process
 program example_process_kill
-    use stdlib_system, only: process_type, run, is_running, kill, elapsed, has_win32, sleep
+    use stdlib_system, only: process_type, runasync, is_running, kill, elapsed, has_win32, sleep
     implicit none
     type(process_type) :: process
     logical :: running, success
 
     print *, "Starting a long-running process..."
     if (has_win32()) then
-        process = run("ping -n 10 127.0.0.1", wait=.false.)
+        process = runasync("ping -n 10 127.0.0.1")
     else
-        process = run("ping -c 10 127.0.0.1", wait=.false.)
+        process = runasync("ping -c 10 127.0.0.1")
     endif
 
     ! Verify the process is running
diff --git a/src/stdlib_system.F90 b/src/stdlib_system.F90
@@ -7,6 +7,7 @@ module stdlib_system
 
 !> Public sub-processing interface
 public :: run
+public :: runasync
 public :: process_type
 public :: is_completed
 public :: is_running
@@ -53,7 +54,7 @@ module stdlib_system
     
 end type process_type
 
-interface run
+interface runasync
     !! version: experimental
     !!
     !! Executes an external process, either synchronously or asynchronously.
@@ -72,40 +73,77 @@ module stdlib_system
     !!
     !! @note The implementation depends on system-level process management capabilities.
     !!
-    !! #### Methods
+    module function run_async_cmd(cmd, stdin, want_stdout, want_stderr) result(process)
+        !> The command line string to execute.
+        character(*), intent(in) :: cmd
+        !> Optional input sent to the process via standard input (stdin).
+        character(*), optional, intent(in) :: stdin
+        !> Whether to collect standard output.
+        logical, optional, intent(in) :: want_stdout
+        !> Whether to collect standard error output.
+        logical, optional, intent(in) :: want_stderr
+        !> The output process handler.
+        type(process_type) :: process
+    end function run_async_cmd
+
+    module function run_async_args(args, stdin, want_stdout, want_stderr) result(process)
+        !> List of arguments for the process to execute.
+        character(*), intent(in) :: args(:)
+        !> Optional input sent to the process via standard input (stdin).
+        character(*), optional, intent(in) :: stdin
+        !> Whether to collect standard output.
+        logical, optional, intent(in) :: want_stdout
+        !> Whether to collect standard error output.
+        logical, optional, intent(in) :: want_stderr
+        !> The output process handler.
+        type(process_type) :: process        
+    end function run_async_args
+end interface runasync
+
+interface run
+    !! version: experimental
+    !!
+    !! Executes an external process, either synchronously or asynchronously.
+    !! ([Specification](../page/specs/stdlib_system.html#run-execute-an-external-process))
+    !!
+    !! ### Summary
+    !! Provides methods for executing external processes via a single command string or an argument list, 
+    !! with options for synchronous or asynchronous execution and output collection.
     !!
-    !! - `process_open_cmd`: Opens a process using a command string.
-    !! - `process_open_args`: Opens a process using an array of arguments.
+    !! ### Description
     !! 
-    module function process_open_cmd(cmd, wait, stdin, want_stdout, want_stderr) result(process)
+    !! This interface allows the user to spawn external processes using either a single command string 
+    !! or a list of arguments. Processes can be executed synchronously (blocking) or asynchronously 
+    !! (non-blocking), with optional request to collect standard output and error streams, or to provide
+    !! a standard input stream via a `character` string.
+    !!
+    !! @note The implementation depends on system-level process management capabilities.
+    !!
+    module function run_sync_cmd(cmd, stdin, want_stdout, want_stderr) result(process)
         !> The command line string to execute.
         character(*), intent(in) :: cmd
         !> Optional input sent to the process via standard input (stdin).
         character(*), optional, intent(in) :: stdin
-        !> Whether to wait for process completion (synchronous).
-        logical, optional, intent(in) :: wait
         !> Whether to collect standard output.
         logical, optional, intent(in) :: want_stdout
         !> Whether to collect standard error output.
         logical, optional, intent(in) :: want_stderr
         !> The output process handler.
         type(process_type) :: process
-    end function process_open_cmd
+    end function run_sync_cmd
 
-    module function process_open_args(args, wait, stdin, want_stdout, want_stderr) result(process)
+    module function run_sync_args(args, stdin, want_stdout, want_stderr) result(process)
         !> List of arguments for the process to execute.
         character(*), intent(in) :: args(:)
         !> Optional input sent to the process via standard input (stdin).
         character(*), optional, intent(in) :: stdin
-        !> Whether to wait for process completion (synchronous).
-        logical, optional, intent(in) :: wait
         !> Whether to collect standard output.
         logical, optional, intent(in) :: want_stdout
         !> Whether to collect standard error output.
         logical, optional, intent(in) :: want_stderr
         !> The output process handler.
         type(process_type) :: process        
-    end function process_open_args
+    end function run_sync_args
 end interface run
 
 interface is_running
diff --git a/src/stdlib_system_subprocess.F90 b/src/stdlib_system_subprocess.F90
@@ -85,31 +85,95 @@ module subroutine sleep(millisec)
         
     end subroutine sleep
 
-    !> Open a new process
-    module function process_open_cmd(cmd,wait,stdin,want_stdout,want_stderr) result(process)
+    module function run_async_cmd(cmd, stdin, want_stdout, want_stderr) result(process)
+        !> The command line string to execute.
+        character(*), intent(in) :: cmd
+        !> Optional input sent to the process via standard input (stdin).
+        character(*), optional, intent(in) :: stdin
+        !> Whether to collect standard output.
+        logical, optional, intent(in) :: want_stdout
+        !> Whether to collect standard error output.
+        logical, optional, intent(in) :: want_stderr
+        !> The output process handler.
+        type(process_type) :: process
+        
+        process = process_open([cmd],.false.,stdin,want_stdout,want_stderr)
+        
+    end function run_async_cmd
+
+    module function run_async_args(args, stdin, want_stdout, want_stderr) result(process)
+        !> List of arguments for the process to execute.
+        character(*), intent(in) :: args(:)
+        !> Optional input sent to the process via standard input (stdin).
+        character(*), optional, intent(in) :: stdin
+        !> Whether to collect standard output.
+        logical, optional, intent(in) :: want_stdout
+        !> Whether to collect standard error output.
+        logical, optional, intent(in) :: want_stderr
+        !> The output process handler.
+        type(process_type) :: process  
+        
+        process = process_open(args,.false.,stdin,want_stdout,want_stderr)
+              
+    end function run_async_args
+
+    module function run_sync_cmd(cmd, stdin, want_stdout, want_stderr) result(process)
+        !> The command line string to execute.
+        character(*), intent(in) :: cmd
+        !> Optional input sent to the process via standard input (stdin).
+        character(*), optional, intent(in) :: stdin
+        !> Whether to collect standard output.
+        logical, optional, intent(in) :: want_stdout
+        !> Whether to collect standard error output.
+        logical, optional, intent(in) :: want_stderr
+        !> The output process handler.
+        type(process_type) :: process
+        
+        process = process_open([cmd],.true.,stdin,want_stdout,want_stderr)
+        
+    end function run_sync_cmd
+
+    module function run_sync_args(args, stdin, want_stdout, want_stderr) result(process)
+        !> List of arguments for the process to execute.
+        character(*), intent(in) :: args(:)
+        !> Optional input sent to the process via standard input (stdin).
+        character(*), optional, intent(in) :: stdin
+        !> Whether to collect standard output.
+        logical, optional, intent(in) :: want_stdout
+        !> Whether to collect standard error output.
+        logical, optional, intent(in) :: want_stderr
+        !> The output process handler.
+        type(process_type) :: process  
+        
+        process = process_open(args,.true.,stdin,want_stdout,want_stderr)
+              
+    end function run_sync_args
+
+    !> Internal function: open a new process from a command line
+    function process_open_cmd(cmd,wait,stdin,want_stdout,want_stderr) result(process)
         !> The command and arguments
         character(*), intent(in) :: cmd
         !> Optional character input to be sent to the process via pipe
         character(*), optional, intent(in) :: stdin
         !> Define if the process should be synchronous (wait=.true.), or asynchronous(wait=.false.)
-        logical, optional, intent(in) :: wait
+        logical, intent(in) :: wait
         !> Require collecting output
         logical, optional, intent(in) :: want_stdout, want_stderr
         !> The output process handler
         type(process_type) :: process        
         
-        process = process_open_args([cmd],wait,stdin,want_stdout,want_stderr)
+        process = process_open([cmd],wait,stdin,want_stdout,want_stderr)
         
     end function process_open_cmd
 
-    !> Open a new process
-    module function process_open_args(args,wait,stdin,want_stdout,want_stderr) result(process)
+    !> Internal function: open a new process from arguments
+    function process_open(args,wait,stdin,want_stdout,want_stderr) result(process)
         !> The command and arguments
         character(*), intent(in) :: args(:)
         !> Optional character input to be sent to the process via pipe
         character(*), optional, intent(in) :: stdin
         !> Define if the process should be synchronous (wait=.true.), or asynchronous(wait=.false.)
-        logical, optional, intent(in) :: wait
+        logical, intent(in) :: wait
         !> Require collecting output
         logical, optional, intent(in) :: want_stdout, want_stderr
         !> The output process handler
@@ -121,11 +185,10 @@ module function process_open_args(args,wait,stdin,want_stdout,want_stderr) resul
         integer(TICKS) :: count_max
         
         ! Process user requests
-        asynchronous   = .false.
+        asynchronous   = .not.wait
         collect_stdout = .false.
         collect_stderr = .false.
         has_stdin      = present(stdin)
-        if (present(wait))        asynchronous   = .not.wait
         if (present(want_stdout)) collect_stdout = want_stdout
         if (present(want_stderr)) collect_stderr = want_stderr
         
@@ -173,7 +236,7 @@ module function process_open_args(args,wait,stdin,want_stdout,want_stderr) resul
         ! Run a first update
         call update_process_state(process)   
            
-    end function process_open_args
+    end function process_open
     
     subroutine launch_asynchronous(process, args, stdin)
         class(process_type), intent(inout) :: process
diff --git a/test/system/test_subprocess.f90 b/test/system/test_subprocess.f90
@@ -1,6 +1,6 @@
 module test_subprocess
     use testdrive, only : new_unittest, unittest_type, error_type, check, skip_test
-    use stdlib_system, only: process_type, run, is_running, wait, update, elapsed, has_win32, kill
+    use stdlib_system, only: process_type, run, runasync, is_running, wait, update, elapsed, has_win32, kill
 
     implicit none
 
@@ -25,7 +25,7 @@ subroutine test_run_synchronous(error)
         type(process_type) :: process
         character(len=*), parameter :: command = "echo Hello"
 
-        process = run(command, wait=.true., want_stdout=.true.)
+        process = run(command, want_stdout=.true.)
         call check(error, process%completed)
         if (allocated(error)) return
         
@@ -40,9 +40,9 @@ subroutine test_run_asynchronous(error)
 
         ! The closest possible to a cross-platform command that waits
         if (has_win32()) then 
-            process = run("ping -n 2 127.0.0.1", wait=.false.)
+            process = runasync("ping -n 2 127.0.0.1")
         else
-            process = run("ping -c 2 127.0.0.1", wait=.false.)
+            process = runasync("ping -c 2 127.0.0.1")
         endif
         ! Should not be immediately completed
         call check(error, .not. process%completed, "ping process should not complete immediately")
@@ -68,9 +68,9 @@ subroutine test_process_kill(error)
 
         ! Start a long-running process asynchronously
         if (has_win32()) then
-            process = run("ping -n 10 127.0.0.1", wait=.false.)
+            process = runasync("ping -n 10 127.0.0.1")
         else
-            process = run("ping -c 10 127.0.0.1", wait=.false.)
+            process = runasync("ping -c 10 127.0.0.1")
         endif
 
         ! Ensure the process starts running
@@ -100,7 +100,7 @@ subroutine test_process_state(error)
         type(process_type) :: process
         character(len=*), parameter :: command = "echo Testing"
 
-        process = run(command, wait=.true., want_stdout=.true., want_stderr=.true.)
+        process = run(command, want_stdout=.true., want_stderr=.true.)
 
         call update(process)
         call check(error, process%completed)
