utilities - acfr/comma GitHub Wiki

Table of Contents

general-purpose utilities

Located in the util sub-directory of the source tree.

Running tests

comma-test-run, comma-test-match and peers. See the tutorial and automating test suites.

Run commands with time limit

comma-timeout-group is a drop-in replacement for the standard timeout (1) utility from coreutils. Similar to the predecessor, comma-timeout-group takes a command to run and runs it as a child process in a separate process group. If a timeout limit is reached, the child process and its group are killed. The new implementation is fully backward compatible but provides extra functionality: it can wait not only for the main child process to exit but also for all the processes in the child group. This is implemented by parsing the process tree periodically to see if comma-timeout-group itself is the only extant member of the group. The extra functionality is useful to safeguard potentially broken applications that do not wait for all their children internally. The most typical of such applications is bash itself. In bash versions of 4.3 series, processes running as part of a signal handler may be executed after the main script has finished.

Parsing the process tree is implemented through functions from the procps (also called as procps-ng) library. If the library is present during compilation time of comma-timeout-group, the support is enabled. If the library is not found, comma-timeout-group still compiles but the new functionality is not available. In this mode, the application behaves the same way as the standard timeout (1) utility. You can check if your version of comma-timeout-group is build with group-waiting capabilities by running the command

    comma-timeout-group --can-wait-for-process-group

The exit status of 0 (success) indicates support for group-waiting, while exit status of 1 (failure) shows the fallback implementation.

To run an application and wait for all processes in its group, invoke comma-timeout-group with the following syntax:

    comma-timeout-group --wait-for-process-group=10 --enforce-group 60 application arg1 arg2

Here application is the name of your application, 60 is the timeout for the application to run (in seconds), and 10 (seconds) is the timeout to wait for all the processes in the group to finish. In the example above, comma-timeout-group will start the application and wait for 60 seconds. If the application has not exited by that time, comma-timeout-group would send the application and all the other processes in its group a signal (SIGTERM by default; the signal to use is controlled by -s,--signal option, if need be) and then wait for another 10 seconds parsing the process tree and looking for any remaining members of the process group. Finally, if such processes are still found, the group is sent a KILL signal (signal 9) to terminate unconditionally.

The --enforce-group option above ensures that comma-timeout-group supports waiting for process groups. If the utility is compiled without procps support, and is invoked with new-style option --wait-for-process-group, by default it will work in backward-compatible mode and interpret --wait-for-process-group=duration as equivalent to --kill-after=duration option of the original timeout. However, if --enforce-group is also given, comma-timeout-group will exit in error.

⚠️ **GitHub.com Fallback** ⚠️