34. Processes

A process is the instance of a program that is being executed by one or many threads. The operating system keeps its processes separate and allocates the resources (memory, CPU time, file handles, network connections) they need. Each process runs in its own memory space, meaning one process cannot directly read or modify the memory of another process¹.

Running external processes allows a program to delegate work to existing tools instead of reimplementing their functionality. Communicating between processes on the same computer typically happens through standard streams (stdin, stdout, stderr), pipes, sockets, or shared files. A parent process is a process that has created one or more child processes².

In Qt, both creating external processes and communicating with them is handled by the QProcess class.

In this chapter we provide several examples of QProcess usage, starting with simple program execution and communicating via standard stream channels, before proceeding to setting a process environment, changing the process working directory, synchronous process execution, and terminating a running process.

To start a process, create an object of this class and call its start() method:

where:

• program is the executable name.
• arguments is a list of command line arguments.
• mode is a QIODevice.OpenMode, ReadWrite by default.

After creating a QProcess, it can be in one of three states:

To start an external process:

1. Create a QProcess object and connect its signals. ping command line arguments are different between Windows and Unix derived operating systems, so check on which platform the program is running and set the arguments accordingly - on Windows just set the target (‘google.com’) as the command exits automatically after four pings. Otherwise, set the target, the switch to limit the number of packets (‘-c’), and the number of packets (‘4’). Create a QProcess object and connect its signals to the slots:

   • readyReadStandardOutput() is emitted when there is data available through stdout.
   • readyReadStandardError() is emitted when there is data available through the standard error channel, stderr.
   • errorOccurred(), emitted when an error occurs with the process.
   • stateChanged(), emitted when the state of the process changed.
   • finished(), emitted when the process finishes. The difference between the readyReadStandardError() and errorOccurred() is that readyReadStandardError() is emitted when the process itself writes data to its error stream, while errorOccurred() is emitted when a process-level failure occurs, such as the executable not being found or the process crashing.

2. Start the external process. When the user clicks the ‘RunCommand’ button, disable the button, clear the log widget (a QTextBrowser), and call QProcess.start(), passing it the executable name (ping) and its command line arguments.

3. Handle signals:

   • log_stdout() reads all standard output data, decodes it and appends the output to the log widget.
   • log_stderr() reads all standard error data, decodes it and appends it to the log.
   • log_error() appends the error code and error string to the log.
   • log_state_change() logs process state changes.
   • log_finished()logs the process exit status and enables the ‘Run Command’ so the process can be run again.

When you run the application the following window is shown:

If the command runs successfully the log should look like this:

The process state changes from Starting to Running, stdout is captured, the state changes to NotRunning and the process exits.

If there is an error in the QProcess setup, like

the output is different:

The process state changes from Starting to NotRunning, and errorOccurred() is emitted with the FailedToStart error code.

If the executable exists, but you pass it an invalid command line argument:

The output is:

The process runs but the invalid argument causes the process to fail so it outputs a message through stderr and exits.

Some processes are interactive by nature: they prompt the user for input and proceed based on the responses. In such cases QProcess allows you to write data directly to a child precess stdin, so you can feed predefined values programmatically as if a user had typed them.

Suppose you have a third-party Python script that prompts the user for some values:

Instead of typing responses at a terminal, you want to feed all inputs automatically via stdin. (The above script does nothing but prints strings to the terminal, simulating actual processing with time.sleep().)

To provide a fixed input to a process:

1.Create a QProcess and connect its signals. Similarly to the previous example, connect readyReadStandardOutput(), readyReadStandardError() and errorOccurred() to the slots that log the child process output to a QTextEdit. Connect stateChanged() to on_state_changed() which is responsible for feeding the predefined input values to the child process.

2. Start the process. Use QProcess.start() to run the Python executable, passing -u as the first argument followed by the script path. The -u flag forces stdout and stderr to be unbuffered. Python buffers stdout by default when it detects it isn not attached to a real terminal -without it, all output would arrive in a single burst at process exit instead of line by line.

3. Write the predefined input values. In on_state_changed() check whether the process state is Running, then use QProcess.write() to write each input value to the child process stdin. The values must be bytes objects with a trailing newline (b'my_app\n', b'Joe\n', b'12\n'), matching what a user would type at a terminal. Each input() call in the child script reads the next line from the stdin buffer as it is needed - all values can be written upfront because the OS buffers them untill they are consumed. Finally, call QProcess.closeWriteChannel() to signal EOF.

When you run the application and start the child process, the end result should look like this:

Python, like many other languages, buffers its stdout differently depending on whether it is writing to a terminal or to a pipe. When stdout is connected to a real terminal, Python uses line buffering, flushing after each newline. When connected to a pipe, it uses block buffering, holding output untill the buffer fills up or the process exits. When you launch a child process via QProcess Qt sets up two pipes automatically: one connecting your application to the child process stdin, and another connecting the child’s stdout back to your application. This means that you can not expect the child process output to arrive in complete, newline-separated chunks.

You are dealing with a program that sends long strings to its stdout:

The full output is close to 800 characters spread across five repeated sentences. It deliberately splits its output into 20-byte chunks, calling sys.stdout.flush(), which forces readyReadStandardOutput() to be emitted on every chunk. When you read the output in the main application you need to buffer those chunks untill you encounter a newline character and only then display the complete line.

To handle chunked output from an external process:

1. Create a QProcess object, connect the signals, and run the child process. When the user clicks the ‘Run with Buffering’ button:

   • Initialize an empty string buffer to accumulate incoming output chunks.
   • Create a QProcess.
   • Connect the readyReadStandardOutput() to handle_stdout_buffered() and finished() to finished_buffered().
   • Start the process.

2. Read the child process stdout data, decode it, and append it to the buffer. When new data is available, use readAllStandardOutput() to read all currently available bytes , decode from UTF-8, and the result to the buffer string.

3. Check whether the buffer contains any complete lines and display them. Split the buffer os.linesep. Every element except the last one is a complete line so you append it to the text box and discard it. Keep the last element in the buffer, as it is a partial line that has not yet been terminated by a newline.

4. When the child process finishes, flush any remaining content from the buffer. If the buffer is not empty, after the process exits, append it to the text edit as there won’t be no further output from the child process.

For comparison, running the same child process without buffering produces output like this, where each readyReadStandardOutput() signal delivers a raw 20-byte chunk, splitting sentences at arbitrary boundaries:

The previous two sections covered one-directional communication - feeding a process predefined input or reading its output as it arrives. Some processes, however, are designed to stay alive and accept input repeatedly, responding to each command before waiting for the next one. Communicating with such a process requires keeping the write channel open and writing to stdin on demand, in response to user actions.

To establish interactive process communication:

1. Create the process object, connect the signals, and start the process. Add a QLineEdit to the main window to let the user send commands to the Python shell, and a QTextBrowser to display the shell output. Connect QLineEdit.returnPressed() to send_input(). Connect readyReadStandardOutput() and readyReadStandardError() signals to the slots. Start the Python executable with the following flags:

   • -u to force the stdout and stderr streams to be unbuffered.
   • -i to enter interactive mode, keeping the shell alive and waiting for input.
   • q to suppress the copyright and version banner on startup. Once the started signal is emitted, the Python interactive shell is ready to accept commands. Enable the QLineEdit and give it focus.

2. Send user input to the process. In send_input(), read the command from QLineEdit.text(). Send the command to the process via QProcess.write(), appending a newline to submit it, then clear the line edit.

3. Handle the process output. in handle_stdout() and handle_stderr(), read and decode the available data and apply the same line-buffering technique from the previous section - accumulate chunks until a newline is found, then display the complete line. Display stderr output in red using an HTML <font> tag.

4. Terminate the process cleanly. In closeEvent(), if the process is still running, send exit() to the shell and give it a short time to finish with waitForFinished(). If it has not exited by then, call QProcess.kill() to terminate it before allowing the window to close.

Note that communication is asynchronous in both directions. If you send the shell a long-running command, the UI remains responsive and you are still able to continue sending commands to it. Output lines appear in the text browser as they arrive rather than all at once when the command completes.

Bu default, a child process launched via QProcess inherits the environment of the parent process. Sometimes this is not whast you want - you may need to set additional environment variables or isolate the process from the parent’s environment entirely. QProcess lets you construct a custom environment assign it to the process before it starts.

To set the process environment:

1. Get the system environment. QProcessEnvironment holds the set environment variables that can be passed to the child process. Use its systemEnvironment() static method to obtain a copy of the current process environment. Add two checkboxes to the main window: one to override the Qt style to Windows, and one to set the scale factor to 1.5.

2. Update environment variables when the checkboxes change. A process environment is a set of key=value pairs. Use QProcessEnvironment.insert() to set a variable and QProcessEnvironment.remove() to clear it:

   • Insert QT_STYLE_OVERRIDE=windows when the style checkbox is checked, remove it when unchecked.
   • Insert QT_SCALE_FACTOR=1.5 when the scale checkbox is checked, remove it when unchecked.

3. Apply the environment to the process. Call QProcess.setProcessEnvironment() to assign the environment before starting the process.

With this the user is able to launch the child Qt application with a different style and scale factor.

We are using this simple PySide6 demo for testing the application:

When you change the environment variables from the main application and run it, the test app should reflect the changes - appearing with the Windows style when the style checkbox is checked, rendered at 1.5x size when the scale checkbox is checked, or both at once if both are checked.

All the previous examples in this chapter use asynchronous process exexution: start a process, connect signals and let the event loop handle the rest. Sometimes, however, you want to vait for a process to finish before proceeding. Common scenarios include:

• Checking for external tool availability - verifying that git, ffmpeg, or some other dependency present before your application continues.
• Sequential operations - step B depends on the output or exit code of step A.
• Short fast operations - the process is known to complete in milliseconds.

All of the above can also be achieved asynchronously, but synchronous execution trades UI responsiveness for simpler code.

To execute a process synchronously:

1. Start the process and wait for it to start. Call QProcess.start() to launch the process, then immediatelly call QProcess.waitForStarted(). QProcess.start() is not guaranteed to be synchronous - on Linux, process creation does fork() and exec(), which makes it asynchronous, so the process may still be in the Starting state by the time start() returns. On Windows the transition to Running (or NotRunning) may happen before start() returns, but this is not guaranteed either. waitForStarted() is a reliable way to know the process has either started or failed to start, regardless of the platform. If it returns False, the process failed to start.

2. Wait for the process to finish. Call QProcess.waitForFinished() to block until the process exits. At this point the output is available and the exit code can be checked.

Note that both waitForStarted() and waitForFinished() block the event loop and the UI will become non-responsive while waiting. This is acceptable for fast operations like a version check, but for anythong that might take more than that, the asynchronous approach is preferred.

A long-running child process may need to be stopped before it finishes normally, maybe if the user wants to cancel it or the process has hung. QProcess provides two ways to stop a running process:

• QProcess.terminate() asks the process to stop gracefully. On Linux it sends SIGTERM, giving the process a chance to clean up before exiting. On Windows it posts a WM_CLOSE message, which terminal processes like ping typically ignore.
• QProcess.kill(). Kills the process, causing it to exit immediatelly. On WIndows, kill() uses TerminateProcess, and on Linux, the SIGKILL signal is sent to the process.

To terminate a running process:

1. Start the process and track its state.

2. Try to terminate the process gracefully. When the user clicks the ‘Stop’ button, call QProcess.terminate() torequest a graceful shutdown, then call waitForFinished() with a short timeout to give the process a chance to exit cleanly.

3. If necessary, kill the process. If waitFOrFinish() returns False, the process did not exit within the timeout. Call QProcess.kill() and waitForFinished() to make sure the process has ended.

4. Handle process termination on window close. Override closeEvent() to apply the same pattern to make sure no orphaned child processes are left running after the application exits.