options(width = 100) suppressWarnings(suppressPackageStartupMessages(suppressMessages(library(dplyr)))) suppressWarnings(suppressMessages(library(pillar)))
You can install the released version of ps from CRAN with:
install.packages("ps")
If you need the development version, install it with
pak::pak("r-lib/ps")
library(ps) library(pillar) # nicer printing of data frames
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"
.
ps_pids()
returns all process ids on the system. This can be useful to
iterate over all processes.
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.
ps()
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:
p <- ps_handle() p
ps_pid(p)
returns the pid of the process.
ps_pid(p)
ps_create_time()
returns the creation time of the process (according to
the OS).
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.
ps_is_running(p)
ps_ppid(p)
returns the pid of the parent of p
.
ps_ppid(p)
ps_parent(p)
returns a process handle to the parent process of p
.
ps_parent(p)
ps_name(p)
returns the name of the program p
is running.
ps_name(p)
ps_exe(p)
returns the full path to the executable the p
is running.
ps_exe(p)
ps_cmdline(p)
returns the command line (executable and arguments) of p
.
ps_cmdline(p)
ps_status(p)
returns the status of the process. Possible values are OS
dependent, but typically there is "running"
and "stopped"
.
ps_status(p)
ps_username(p)
returns the name of the user the process belongs to.
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.
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.
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_
.
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.
ps_environ(p)[c("TERM", "USER", "SHELL", "R_HOME")]
ps_num_threads(p)
returns the current number of threads of the process.
ps_num_threads(p)
ps_cpu_times(p)
returns the CPU times of the process, similarly to
proc.time()
.
ps_cpu_times(p)
ps_memory_info(p)
returns memory usage information. See the manual for
details.
ps_memory_info(p)
ps_children(p)
lists all child processes (potentially recursively) of
the current process.
ps_children(ps_parent(p))
ps_num_fds(p)
returns the number of open file descriptors (handles on
Windows):
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:
ps_open_files(p) f <- file(tmp <- tempfile(), "w") ps_open_files(p) close(f) unlink(tmp) ps_open_files(p)
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.
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.
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.
In the spirit of psutil recipes.
Using ps()
and dplyr:
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:
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")
On POSIX, there is no good way to wait for non-child processes to finish, so we need to write a sleep-wait loop to do it. (On Windows, and BSD systems, including macOS, there are better solutions.)
as_secs <- function(x) as.numeric(x, units = "secs") wait_for_process <- function(proc, timeout = Inf, sleep = 0.1) { sleep <- as_secs(sleep) deadline <- Sys.time() + timeout while (ps_is_running(proc) && (timeout == Inf || Sys.time() < deadline)) { to <- min(as_secs(deadline - Sys.time()), sleep) Sys.sleep(to) } ! ps_is_running(proc) } px <- processx::process$new("sleep", "2") p <- ps_handle(px$get_pid()) wait_for_process(p, 1) wait_for_process(p)
This is similar, but we need to wait on all processes in a loop.
wait_for_processes <- function(procs, timeout = Inf) { gone <- list() alive <- procs deadline <- Sys.time() + timeout check_gone <- function(proc, timeout) { proc_gone <- wait_for_process(proc, timeout = timeout) if (proc_gone) { gone <<- c(gone, list(proc)) alive <<- setdiff(alive, list(proc)) } } while (length(alive)) { if (timeout <= 0) break for (proc in alive) { max_timeout <- 1 / length(alive) if (timeout != Inf) { timeout <- min(as_secs(deadline - Sys.time()), max_timeout) if (timeout <= 0) break check_gone(proc, timeout) } else { check_gone(proc, max_timeout) } } } list(gone = gone, alive = alive) } 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 <- ps_handle(px1$get_pid()) p2 <- ps_handle(px2$get_pid()) p3 <- ps_handle(px3$get_pid()) p4 <- ps_handle(px4$get_pid()) wait_for_processes(list(p1, p2, p3, p4), timeout = 2)
This sends a signal, so it'll only work on Unix. Use ps_kill()
instead of ps_send_signal()
on Windows.
kill_proc_tree <- function(pid, sig = signals()$SIGTERM, 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, parent) for (p in children) ps_send_signal(p, sig) wait_for_processes(children, timeout = 0.1) } 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)
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.
reap_children <- function(timeout = 3) { procs <- ps_children(ps_handle()) ## SIGTERM lapply(procs, ps_terminate) ga <- wait_for_processes(procs, timeout = timeout) ## SIGKILL to the survivers if (length(ga$alive)) lapply(ga$alive, ps_kill) ga2 <- wait_for_processes(ga$alive, timeout = timeout) ## Some might still survive list(gone = c(ga$gone, ga2$gone), alive = ga2$alive) } pxs <- replicate(3, processx::process$new("sleep", "3")) reap_children()
Process name ending with "sh":
ps() %>% filter(grepl("sh$", name))
Processes owned by user:
ps() %>% filter(username == Sys.info()[["user"]]) %>% select(pid, name)
Processes consuming more than 100MB of memory:
ps() %>% filter(rss > 100 * 1024 * 1024)
Top 3 memory consuming processes:
ps() %>% top_n(3, rss) %>% arrange(desc(rss))
Top 3 processes which consumed the most CPU time:
ps() %>% mutate(cpu_time = user + system) %>% top_n(3, cpu_time) %>% arrange(desc(cpu_time)) %>% select(pid, name, cpu_time)
Please note that the ps project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.
MIT © RStudio
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.