Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/r-lib/ps

R package to query, list, manipulate system processes
https://github.com/r-lib/ps

Last synced: 4 days ago
JSON representation

R package to query, list, manipulate system processes

Awesome Lists containing this project

README 

        
---

output:

  github_document:

    toc: true

    toc_depth: 3

    includes:

      before_body: header.md

---



```{r echo = FALSE}

options(width = 100)

suppressWarnings(suppressPackageStartupMessages(suppressMessages(library(dplyr))))

suppressWarnings(suppressMessages(library(pillar)))

```



## Installation



You can install the released version of ps from

[CRAN](https://CRAN.R-project.org) with:



``` r

install.packages("ps")

```



If you need the development version, install it with



``` r

pak::pak("r-lib/ps")

```



```{r}

library(ps)

library(pillar) # nicer printing of data frames

```



## Supported platforms



ps currently supports Windows (from Vista), macOS and Linux systems.

On unsupported platforms the package can be installed and loaded, but

all of its functions fail with an error of class `"not_implemented"`.



## Listing all processes



`ps_pids()` returns all process ids on the system. This can be useful to

iterate over all processes.



```{r}

ps_pids()[1:20]

```



`ps()` returns a data frame, with data about each process. It contains a

handle to each process, in the `ps_handle` column, you can use these to

perform more queries on the processes.



```{r}

ps()

```



## Process API



This is a short summary of the API. Please see the documentation of the

various methods for details, in particular regarding handles to finished

processes and pid reuse. See also "Finished and zombie processes"

and "pid reuse" below.



`ps_handle(pid)` creates a process handle for the supplied process id.

If `pid` is omitted, a handle to the calling process is returned:



```{r}

p <- ps_handle()

p

```



### Query functions



`ps_pid(p)` returns the pid of the process.



```{r}

ps_pid(p)

```



`ps_create_time()` returns the creation time of the process (according to

the OS).



```{r}

ps_create_time(p)

```



The process id and the creation time uniquely identify a process in a

system. ps uses them to make sure that it reports information about, and

manipulates the correct process.



`ps_is_running(p)` returns whether `p` is still running. It handles pid

reuse safely.



```{r}

ps_is_running(p)

```



`ps_ppid(p)` returns the pid of the parent of `p`.



```{r}

ps_ppid(p)

```



`ps_parent(p)` returns a process handle to the parent process of `p`.



```{r}

ps_parent(p)

```



`ps_name(p)` returns the name of the program `p` is running.



```{r}

ps_name(p)

```



`ps_exe(p)` returns the full path to the executable the `p` is running.



```{r}

ps_exe(p)

```



`ps_cmdline(p)` returns the command line (executable and arguments) of `p`.



```{r}

ps_cmdline(p)

```



`ps_status(p)` returns the status of the process. Possible values are OS

dependent, but typically there is `"running"` and `"stopped"`.



```{r}

ps_status(p)

```



`ps_username(p)` returns the name of the user the process belongs to.



```{r}

ps_username(p)

```



`ps_uids(p)` and  `ps_gids(p)` return the real, effective and saved user

ids of the process. They are only implemented on POSIX systems.



```{r}

if (ps_os_type()[["POSIX"]]) ps_uids(p)

if (ps_os_type()[["POSIX"]]) ps_gids(p)

```



`ps_cwd(p)` returns the current working directory of the process.



```{r}

ps_cwd(p)

```



`ps_terminal(p)` returns the name of the terminal of the process, if any.

For processes without a terminal, and on Windows it returns `NA_character_`.



```{r}

ps_terminal(p)

```



`ps_environ(p)` returns the environment variables of the process.

`ps_environ_raw(p)` does the same, in a different form. Typically they

reflect the environment variables at the start of the process.



```{r}

ps_environ(p)[c("TERM", "USER", "SHELL", "R_HOME")]

```



`ps_num_threads(p)` returns the current number of threads of the process.



```{r}

ps_num_threads(p)

```



`ps_cpu_times(p)` returns the CPU times of the process, similarly to

`proc.time()`.



```{r}

ps_cpu_times(p)

```



`ps_memory_info(p)` returns memory usage information. See the manual for

details.



```{r}

ps_memory_info(p)

```



`ps_children(p)` lists all child processes (potentially recursively) of

the current process.



```{r}

ps_children(ps_parent(p))

```



`ps_num_fds(p)` returns the number of open file descriptors (handles on

Windows):



```{r}

ps_num_fds(p)

f <- file(tmp <- tempfile(), "w")

ps_num_fds(p)

close(f)

unlink(tmp)

```



`ps_open_files(p)` lists all open files:



```{r}

ps_open_files(p)

f <- file(tmp <- tempfile(), "w")

ps_open_files(p)

close(f)

unlink(tmp)

ps_open_files(p)

```



### Process manipulation



`ps_suspend(p)` suspends (stops) the process. On POSIX it sends a SIGSTOP

signal. On Windows it stops all threads.



`ps_resume(p)` resumes the process. On POSIX it sends a SIGCONT signal. On

Windows it resumes all stopped threads.



`ps_send_signal(p)` sends a signal to the process. It is implemented on

POSIX systems only. It makes an effort to work around pid reuse.



`ps_terminate(p)` send SIGTERM to the process. On POSIX systems only.



`ps_kill(p)` terminates the process. Sends `SIGKILL` on POSIX systems,

uses `TerminateProcess()` on Windows. It make an effort to work around

pid reuse.



`ps_interrupt(p)` interrupts a process. It sends a `SIGINT` signal on

POSIX systems, and it can send a CTRL+C or a CTRL+BREAK event on Windows.



## Finished and zombie processes



ps handles finished and Zombie processes as much as possible.



The essential `ps_pid()`, `ps_create_time()`, `ps_is_running()` functions

and the `format()` and `print()` methods work for all processes, including

finished and zombie processes. Other functions fail with an error of class

`"no_such_process"` for finished processes.



The `ps_ppid()`, `ps_parent()`, `ps_children()`, `ps_name()`,

`ps_status()`, `ps_username()`, `ps_uids()`, `ps_gids()`, `ps_terminal()`,

`ps_children()` and the signal sending functions work properly for

zombie processes. Other functions fail with `"zombie_process"` error.



## Pid reuse



ps functions handle pid reuse as well as technically possible.



The query functions never return information about the wrong process, even

if the process has finished and its process id was re-assigned.



On Windows, the process manipulation functions never manipulate the wrong

process.



On POSIX systems, this is technically impossible, it is not possible to

send a signal to a process without creating a race condition. In ps the

time window of the race condition is very small, a few microseconds, and

the process would need to finish, _and_ the OS would need to reuse its pid

within this time window to create problems. This is very unlikely to

happen.



## Recipes



In the spirit of [psutil recipes](http://psutil.readthedocs.io/en/latest/#recipes).



### Find process by name



Using `ps()` and dplyr:



```{r}

library(dplyr)

find_procs_by_name <- function(name) {

  ps() %>%

    filter(name == !!name)  %>%

    pull(ps_handle)

}



find_procs_by_name("R")

```



Without creating the full table of processes:



```{r}

find_procs_by_name <- function(name) {

  procs <- lapply(ps_pids(), function(p) {

    tryCatch({

      h <- ps_handle(p)

      if (ps_name(h) == name) h else NULL },

      no_such_process = function(e) NULL,

      access_denied = function(e) NULL

    )

  })

  procs[!vapply(procs, is.null, logical(1))]

  }



find_procs_by_name("R")

```



### Wait for a process to finish



`ps_wait()`, from ps 1.8.0, implements a new way, efficient for waiting on

a list of processes, so this is now very easy:



```{r}

px <- processx::process$new("sleep", "2")

p <- px$as_ps_handle()

ps_wait(p, 1000)

ps_wait(p)

```

### Wait for several processes to finish



Again, this is much simpler with `ps_wait()`, added in ps 1.8.0.



```{r}

px1 <- processx::process$new("sleep", "10")

px2 <- processx::process$new("sleep", "10")

px3 <- processx::process$new("sleep", "1")

px4 <- processx::process$new("sleep", "1")



p1 <- px1$as_ps_handle()

p2 <- px2$as_ps_handle()

p3 <- px3$as_ps_handle()

p4 <- px4$as_ps_handle()



ps_wait(list(p1, p2, p3, p4), timeout = 2000)

```



### Kill process tree



From ps 1.8.0, `ps_kill()` will first send `SIGTERM` signals on Unix,

and `SIGKILL` after a grace period, if needed.



Note, that some R IDEs, including RStudio, run a multithreaded R process,

and other threads may start processes as well. `reap_children()` will clean

up all these as well, potentially causing the IDE to misbehave or crash.



```{r}

kill_proc_tree <- function(pid, include_parent = TRUE, ...) {

  if (pid == Sys.getpid() && include_parent) stop("I refuse to kill myself")

  parent <- ps_handle(pid)

  children <- ps_children(parent, recursive = TRUE)

  if (include_parent) children <- c(children, list(parent))

  ps_kill(children, ...)

}



p1 <- processx::process$new("sleep", "10")

p2 <- processx::process$new("sleep", "10")

p3 <- processx::process$new("sleep", "10")

kill_proc_tree(Sys.getpid(), include_parent = FALSE)

```



### Filtering and sorting processes



Process name ending with "sh":



```{r}

ps() %>%

  filter(grepl("sh$", name))

```



Processes owned by user:



```{r}

ps() %>%

  filter(username == Sys.info()[["user"]]) %>%

  select(pid, name)

```



Processes consuming more than 100MB of memory:



```{r}

ps() %>%

  filter(rss > 100 * 1024 * 1024)

```



Top 3 memory consuming processes:



```{r}

ps() %>%

  top_n(3, rss) %>%

  arrange(desc(rss))

```



Top 3 processes which consumed the most CPU time:



```{r}

ps() %>%

  mutate(cpu_time = user + system) %>%

  top_n(3, cpu_time) %>%

  arrange(desc(cpu_time)) %>%

  select(pid, name, cpu_time)

```



## Code of Conduct



Please note that the ps project is released with a

[Contributor Code of Conduct](https://ps.r-lib.org/CODE_OF_CONDUCT.html).

By contributing to this project, you agree to abide by its terms.



## License



MIT © RStudio