List or kill running PiP tasks

Synopsis: pips [a][u][x] [PIPS-OPTIONS] [-] [PATTERN ..]

Parameters

a\|u\|x	similar to the aux options of the Linux ps command
--root	List PiP root(s)
--task	List PiP task(s)
--family	List PiP root(s) and PiP task(s) in family order
--mode	List PiP root(s) and PiP task(s) running in the specified execution mode. This option must be followed by excution mode(s) which is the combination of characters consisting of 'P' (process mode), 'L' (process:preload), 'C' (process:pipclone), 'G' (process:got) and 'T' (thread mode).
--kill	Send SIGTERM to PiP root(s) and task(s)
--signal	Send a signal to PiP root(s) and task(s). This option must be followed by a signal number or name.
--ps	Run the ps Linux command. This option may have `ps` command option(s) separated by comma (,)
--top	Run the top Linux command. This option may have `top` command option(s) separated by comma (,)
-	Simply ignored. This option can be used to avoid the ambiguity of the options.

Description: pips is a filter to target only PiP tasks (including PiP root) to show status like the way what the ps commands does and send signals to the selected PiP tasks.

Just like the ps command, pips can take the most familiar ps options a, u, x. Here is an example;

$ pips
PID   TID   TT       TIME     PIP COMMAND
18741 18741 pts/0    00:00:00 RT  pip-exec
18742 18742 pts/0    00:00:00 RG  pip-exec
18743 18743 pts/0    00:00:00 RL  pip-exec
18741 18744 pts/0    00:00:00 0T  a
18745 18745 pts/0    00:00:00 0G  b
18746 18746 pts/0    00:00:00 0L  c
18747 18747 pts/0    00:00:00 1L  c
18741 18748 pts/0    00:00:00 1T  a
18749 18749 pts/0    00:00:00 1G  b
18741 18750 pts/0    00:00:00 2T  a
18751 18751 pts/0    00:00:00 2G  b
18741 18752 pts/0    00:00:00 3T  a

here, there are 3 pip-exec root processes running. Four pip tasks running program 'a' with the ptherad mode, three PiP tasks running program 'b' with the process:got mode, and two PiP tasks running program 'c' with the process:preload mode.

Unlike the ps command, two columns 'TID' and 'PIP' are added. The 'TID' field is to identify PiP tasks in pthread execution mode. three PiP tasks running in the pthread mode. As for the 'PiP' field, if the first letter is 'R' then that pip task is running as a PiP root. If this letter is a number from '0' to '9' then this is a PiP task (not root). The number is the least-significant digit of the PiP ID of that PiP task. The second letter represents the PiP execution mode which is common with PiP root and task. 'L' is 'process:preload,' 'C' is 'process:pipclone,', 'G' is 'process:got,' and 'T' is 'thread.'

The last 'COMMAND' column of the pips output may be different from what the ps command shows, although it looks the same. It represents the command, not the command line consisting of a command and its argument(s). More precisely speaking, it is the first 14 letters of the command. This comes from the PiP's specificity. PiP tasks are not created by using the normal exec systemcall and the Linux assumes the same command line with the pip root process which creates the pip tasks.

If users want to have the other ps command options other than 'aux', then refer to the --ps option described below. But in this case, the command lines of PiP tasks (excepting PiP roots) are not correct.

--root (-r) Only the PiP root tasks will be shown.

$ pips --root
PID   TID   TT       TIME     PIP COMMAND
18741 18741 pts/0    00:00:00 RT  pip-exec
18742 18742 pts/0    00:00:00 RG  pip-exec
18743 18743 pts/0    00:00:00 RL  pip-exec

--task (-t) Only the PiP tasks (excluding root) will be shown. If both of --root and --task are specified, then firstly PiP roots are shown and then PiP tasks will be shown.

$ pips --tasks
PID   TID   TT       TIME     PIP COMMAND
18741 18744 pts/0    00:00:00 0T  a
18745 18745 pts/0    00:00:00 0G  b
18746 18746 pts/0    00:00:00 0L  c
18747 18747 pts/0    00:00:00 1L  c
18741 18748 pts/0    00:00:00 1T  a
18749 18749 pts/0    00:00:00 1G  b
18741 18750 pts/0    00:00:00 2T  a
18751 18751 pts/0    00:00:00 2G  b
18741 18752 pts/0    00:00:00 3T  a

--family (-f) All PiP roots and tasks of the selected PiP tasks by the PATTERN optional argument of pips.

$ pips - a
PID   TID   TT       TIME     PIP COMMAND
18741 18744 pts/0    00:00:00 0T  a
18741 18748 pts/0    00:00:00 1T  a
18741 18750 pts/0    00:00:00 2T  a
$ pips --family a
PID   TID   TT       TIME     PIP COMMAND
18741 18741 pts/0    00:00:00 RT  pip-exec
18741 18744 pts/0    00:00:00 0T  a
18741 18748 pts/0    00:00:00 1T  a
18741 18750 pts/0    00:00:00 2T  a

In this example, "pips - a" (the - is needed not to confused the command name a as the pips option) shows the PiP tasks which is derived from the program a. The second run, "pips --family a," shows the PiP tasks of a and their PiP root (pip-exec, in this example).

--kill (-k) Send SIGTERM signal to the selected PiP tasks.
--signal (-s) SIGNAL Send the specified signal to the selected PiP tasks.
--ps (-P) This option may be followed by the ps command options. When this option is specified, the PIDs of selected PiP tasks are passed to the ps command with the specified ps command options, if given.
--top (-T) This option may be followed by the top command options. When this option is specified, the PIDs of selected PiP tasks are passed to the top command with the specified top command options, if given.
PATTERN The last argument is the pattern(s) to select which PiP tasks to be selected and shown. This pattern can be a command name (only the first 14 characters are effective), PID, TID, or a Unix (Linux) filename matching pattern (if the fnmatch Python module is available).
```
$ pips - *-*
PID   TID   TT       TIME     PIP COMMAND
18741 18741 pts/0    00:00:00 RT  pip-exec
18742 18742 pts/0    00:00:00 RG  pip-exec
18743 18743 pts/0    00:00:00 RL  pip-exec
```

Note: pips collects PiP tasks' status by using the Linux's ps command. When the --ps or --top option is specified, the ps or top command is invoked after invoking the ps command for information gathering. This, however, may result some PiP tasks may not appear in the invoked ps or top command when one or more PiP tasks finished after the first ps command invocation. The same situation may also happen with the --kill or --signal option.