Package 'ps'

Description

CleanupReporter takes an existing testthat Reporter object, and wraps it, so it checks for leftover child processes, at the specified place, see the proc_unit argument below.

Usage

CleanupReporter(reporter = testthat::ProgressReporter)

Arguments

Details

Child processes can be reported via a failed expectation, cleaned up silently, or cleaned up and reported (the default).

The constructor of the CleanupReporter class has options:

• file: the output file, if any, this is passed to reporter.

• proc_unit: when to perform the child process check and cleanup. Possible values:

  • "test": at the end of each testthat::test_that() block (the default),

  • "testsuite": at the end of the test suite.

• proc_cleanup: Logical scalar, whether to kill the leftover processes, TRUE by default.

• proc_fail: Whether to create an expectation, that fails if there are any processes alive, TRUE by default.

• proc_timeout: How long to wait for the processes to quit. This is sometimes needed, because even if some kill signals were sent to child processes, it might take a short time for these to take effect. It defaults to one second.

• rconn_unit: When to perform the R connection cleanup. Possible values are "test" and "testsuite", like for proc_unit.

• rconn_cleanup: Logical scalar, whether to clean up leftover R connections. TRUE by default.

• rconn_fail: Whether to fail for leftover R connections. TRUE by default.

• file_unit: When to check for open files. Possible values are "test" and "testsuite", like for proc_unit.

• file_fail: Whether to fail for leftover open files. TRUE by default.

• conn_unit: When to check for open network connections. Possible values are "test" and "testsuite", like for proc_unit.

• conn_fail: Whether to fail for leftover network connections. TRUE by default.

Value

New reporter class that behaves exactly like reporter, but it checks for, and optionally cleans up child processes, at the specified granularity.

Examples

This is how to use this reporter in testthat.R:

library(testthat)
library(mypackage)

if  (ps::ps_is_supported()) {
  reporter <- ps::CleanupReporter(testthat::ProgressReporter)$new(
    proc_unit = "test", proc_cleanup = TRUE)
} else {
  ## ps does not support this platform
  reporter <- "progress"
}

test_check("mypackage", reporter = reporter)

Note

Some IDEs, like RStudio, start child processes frequently, and sometimes crash when these are killed, only use this reporter in a terminal session. In particular, you can always use it in the idiomatic testthat.R file, that calls test_check() during ⁠R CMD check⁠.

Description

For the errors that are not used on the current platform, value is NA_integer_.

Usage

errno()

Details

A data frame with columns: name, value, description.

Examples

errno()

Description

Process table

Usage

ps(user = NULL, after = NULL)

Arguments

Value

Data frame, see columns below.

Columns:

• pid: Process ID.

• ppid: Process ID of parent process.

• name: Process name.

• username: Name of the user (real uid on POSIX).

• status: I.e. running, sleeping, etc.

• user: User CPU time.

• system: System CPU time.

• rss: Resident set size, the amount of memory the process currently uses. Does not include memory that is swapped out. It does include shared libraries.

• vms: Virtual memory size. All memory the process has access to.

• created: Time stamp when the process was created.

• ps_handle: ps_handle objects, in a list column.

Description

Boot time of the system

Usage

ps_boot_time()

Value

A POSIXct object.

Description

List of child processes (process objects) of the process. Note that this typically requires enumerating all processes on the system, so it is a costly operation.

Usage

ps_children(p = ps_handle(), recursive = FALSE)

Arguments

Value

List of ps_handle objects.

See Also

Other process handle functions: ps_cmdline(), ps_connections(), ps_cpu_times(), ps_create_time(), ps_cwd(), ps_descent(), ps_environ(), ps_exe(), ps_handle(), ps_interrupt(), ps_is_running(), ps_kill(), ps_memory_info(), ps_name(), ps_num_fds(), ps_num_threads(), ps_open_files(), ps_pid(), ps_ppid(), ps_resume(), ps_send_signal(), ps_shared_libs(), ps_status(), ps_suspend(), ps_terminal(), ps_terminate(), ps_uids(), ps_username()

Examples

p <- ps_parent(ps_handle())
ps_children(p)

Description

Command line of the process, i.e. the executable and the command line arguments, in a character vector. On Unix the program might change its command line, and some programs actually do it.

Usage

ps_cmdline(p = ps_handle())

Arguments

Details

For a zombie process it throws a zombie_process error.

Value

Character vector.

See Also

Other process handle functions: ps_children(), ps_connections(), ps_cpu_times(), ps_create_time(), ps_cwd(), ps_descent(), ps_environ(), ps_exe(), ps_handle(), ps_interrupt(), ps_is_running(), ps_kill(), ps_memory_info(), ps_name(), ps_num_fds(), ps_num_threads(), ps_open_files(), ps_pid(), ps_ppid(), ps_resume(), ps_send_signal(), ps_shared_libs(), ps_status(), ps_suspend(), ps_terminal(), ps_terminate(), ps_uids(), ps_username()

Examples

p <- ps_handle()
p
ps_name(p)
ps_exe(p)
ps_cmdline(p)

Description

For a zombie process it throws a zombie_process error.

Usage

ps_connections(p = ps_handle())

Arguments

Value

Data frame, with columns:

• fd: integer file descriptor on POSIX systems, NA on Windows.

• family: Address family, string, typically AF_UNIX, AF_INET or AF_INET6.

• type: Socket type, string, typically SOCK_STREAM (TCP) or SOCK_DGRAM (UDP).

• laddr: Local address, string, NA for UNIX sockets.

• lport: Local port, integer, NA for UNIX sockets.

• raddr: Remote address, string, NA for UNIX sockets. This is always NA for AF_INET sockets on Linux.

• rport: Remote port, integer, NA for UNIX sockets.

• state: Socket state, e.g. CONN_ESTABLISHED, etc. It is NA for UNIX sockets.

See Also

Other process handle functions: ps_children(), ps_cmdline(), ps_cpu_times(), ps_create_time(), ps_cwd(), ps_descent(), ps_environ(), ps_exe(), ps_handle(), ps_interrupt(), ps_is_running(), ps_kill(), ps_memory_info(), ps_name(), ps_num_fds(), ps_num_threads(), ps_open_files(), ps_pid(), ps_ppid(), ps_resume(), ps_send_signal(), ps_shared_libs(), ps_status(), ps_suspend(), ps_terminal(), ps_terminate(), ps_uids(), ps_username()

Examples

p <- ps_handle()
ps_connections(p)
sc <- socketConnection("httpbin.org", port = 80)
ps_connections(p)
close(sc)
ps_connections(p)

Description

If cannot be determined, it returns NA. It also returns NA on older Windows systems, e.g. Vista or older and Windows Server 2008 or older.

Usage

ps_cpu_count(logical = TRUE)

Arguments

Value

Integer scalar.

Examples

ps_cpu_count(logical = TRUE)
ps_cpu_count(logical = FALSE)

Description

All times are measured in seconds:

• user: Amount of time that this process has been scheduled in user mode.

• system: Amount of time that this process has been scheduled in kernel mode

• children_user: On Linux, amount of time that this process's waited-for children have been scheduled in user mode.

• children_system: On Linux, Amount of time that this process's waited-for children have been scheduled in kernel mode.

Usage

ps_cpu_times(p = ps_handle())

Arguments

Details

Throws a zombie_process() error for zombie processes.

Value

Named real vector or length four: user, system, children_user, children_system. The last two are NA on non-Linux systems.

See Also

Other process handle functions: ps_children(), ps_cmdline(), ps_connections(), ps_create_time(), ps_cwd(), ps_descent(), ps_environ(), ps_exe(), ps_handle(), ps_interrupt(), ps_is_running(), ps_kill(), ps_memory_info(), ps_name(), ps_num_fds(), ps_num_threads(), ps_open_files(), ps_pid(), ps_ppid(), ps_resume(), ps_send_signal(), ps_shared_libs(), ps_status(), ps_suspend(), ps_terminal(), ps_terminate(), ps_uids(), ps_username()

Examples

p <- ps_handle()
p
ps_cpu_times(p)
proc.time()

Description

The pid and the start time pair serves as the identifier of the process, as process ids might be reused, but the chance of starting two processes with identical ids within the resolution of the timer is minimal.

Usage

ps_create_time(p = ps_handle())

Arguments

Details

This function works even if the process has already finished.

Value

POSIXct object, start time, in GMT.

See Also

Other process handle functions: ps_children(), ps_cmdline(), ps_connections(), ps_cpu_times(), ps_cwd(), ps_descent(), ps_environ(), ps_exe(), ps_handle(), ps_interrupt(), ps_is_running(), ps_kill(), ps_memory_info(), ps_name(), ps_num_fds(), ps_num_threads(), ps_open_files(), ps_pid(), ps_ppid(), ps_resume(), ps_send_signal(), ps_shared_libs(), ps_status(), ps_suspend(), ps_terminal(), ps_terminate(), ps_uids(), ps_username()

Examples

p <- ps_handle()
p
ps_create_time(p)

Description

For a zombie process it throws a zombie_process error.

Usage

ps_cwd(p = ps_handle())

Arguments

Value

String scalar.

See Also

Other process handle functions: ps_children(), ps_cmdline(), ps_connections(), ps_cpu_times(), ps_create_time(), ps_descent(), ps_environ(), ps_exe(), ps_handle(), ps_interrupt(), ps_is_running(), ps_kill(), ps_memory_info(), ps_name(), ps_num_fds(), ps_num_threads(), ps_open_files(), ps_pid(), ps_ppid(), ps_resume(), ps_send_signal(), ps_shared_libs(), ps_status(), ps_suspend(), ps_terminal(), ps_terminate(), ps_uids(), ps_username()

Examples

p <- ps_handle()
p
ps_cwd(p)

Description

Query the parent processes recursively, up to the first process. (On some platforms, like Windows, the process tree is not a tree and may contain loops, in which case ps_descent() only goes up until the first repetition.)

Usage

ps_descent(p = ps_handle())

Arguments

Value

A list of process handles, starting with p, each one is the parent process of the previous one.

See Also

Other process handle functions: ps_children(), ps_cmdline(), ps_connections(), ps_cpu_times(), ps_create_time(), ps_cwd(), ps_environ(), ps_exe(), ps_handle(), ps_interrupt(), ps_is_running(), ps_kill(), ps_memory_info(), ps_name(), ps_num_fds(), ps_num_threads(), ps_open_files(), ps_pid(), ps_ppid(), ps_resume(), ps_send_signal(), ps_shared_libs(), ps_status(), ps_suspend(), ps_terminal(), ps_terminate(), ps_uids(), ps_username()

Examples

ps_descent()

Description

The output is similar the Unix mount and df commands.

Usage

ps_disk_partitions(all = FALSE)

Arguments

Value

A data frame with columns device, mountpoint, fstype and options.

See Also

Other disk functions: ps_disk_usage()

Examples

ps_disk_partitions(all = TRUE)
ps_disk_partitions()

Description

The output is similar to the Unix df command.

Usage

ps_disk_usage(paths = ps_disk_partitions()$mountpoint)

Arguments

Details

Note that on Unix a small percentage of the disk space (5% typically) is reserved for the superuser. ps_disk_usage() returns the space available to the calling user.

Value

A data frame with columns mountpoint, total, used, available and capacity.

See Also

Other disk functions: ps_disk_partitions()

Examples

ps_disk_usage()

Description

ps_environ() returns the environment variables of the process, in a named vector, similarly to the return value of Sys.getenv() (without arguments).

Usage

ps_environ(p = ps_handle())

ps_environ_raw(p = ps_handle())

Arguments

Details

Note: this usually does not reflect changes made after the process started.

ps_environ_raw() is similar to p$environ() but returns the unparsed "var=value" strings. This is faster, and sometimes good enough.

These functions throw a zombie_process error for zombie processes.

Value

ps_environ() returns a named character vector (that has a Dlist class, so it is printed nicely), ps_environ_raw() returns a character vector.

See Also

Other process handle functions: ps_children(), ps_cmdline(), ps_connections(), ps_cpu_times(), ps_create_time(), ps_cwd(), ps_descent(), ps_exe(), ps_handle(), ps_interrupt(), ps_is_running(), ps_kill(), ps_memory_info(), ps_name(), ps_num_fds(), ps_num_threads(), ps_open_files(), ps_pid(), ps_ppid(), ps_resume(), ps_send_signal(), ps_shared_libs(), ps_status(), ps_suspend(), ps_terminal(), ps_terminate(), ps_uids(), ps_username()

Examples

p <- ps_handle()
p
env <- ps_environ(p)
env[["R_HOME"]]

Description

Path to the executable of the process. May also be an empty string or NA if it cannot be determined.

Usage

ps_exe(p = ps_handle())

Arguments

Details

For a zombie process it throws a zombie_process error.

Value

Character scalar.

See Also

Other process handle functions: ps_children(), ps_cmdline(), ps_connections(), ps_cpu_times(), ps_create_time(), ps_cwd(), ps_descent(), ps_environ(), ps_handle(), ps_interrupt(), ps_is_running(), ps_kill(), ps_memory_info(), ps_name(), ps_num_fds(), ps_num_threads(), ps_open_files(), ps_pid(), ps_ppid(), ps_resume(), ps_send_signal(), ps_shared_libs(), ps_status(), ps_suspend(), ps_terminal(), ps_terminate(), ps_uids(), ps_username()

Examples

p <- ps_handle()
p
ps_name(p)
ps_exe(p)
ps_cmdline(p)

Description

ps_get_cpu_affinity() queries the CPU affinity of a process. ps_set_cpu_affinity() sets the CPU affinity of a process.

Usage

ps_get_cpu_affinity(p = ps_handle())

ps_set_cpu_affinity(p = ps_handle(), affinity)

Arguments

Details

CPU affinity consists in telling the OS to run a process on a limited set of CPUs only (on Linux cmdline, the taskset command is typically used).

These functions are only supported on Linux and Windows. They error on macOS.

Value

ps_get_cpu_affinity() returns an integer vector of CPU numbers, starting with zero.

ps_set_cpu_affinity() returns NULL, invisibly.

Examples

# current
orig <- ps_get_cpu_affinity()
orig

# restrict
ps_set_cpu_affinity(affinity = 0:0)
ps_get_cpu_affinity()

# restore
ps_set_cpu_affinity(affinity = orig)
ps_get_cpu_affinity()

Description

Create a process handle

Usage

ps_handle(pid = NULL, time = NULL)

## S3 method for class 'ps_handle'
as.character(x, ...)

## S3 method for class 'ps_handle'
format(x, ...)

## S3 method for class 'ps_handle'
print(x, ...)

Arguments

Value

ps_handle() returns a process handle (class ps_handle).

See Also

Other process handle functions: ps_children(), ps_cmdline(), ps_connections(), ps_cpu_times(), ps_create_time(), ps_cwd(), ps_descent(), ps_environ(), ps_exe(), ps_interrupt(), ps_is_running(), ps_kill(), ps_memory_info(), ps_name(), ps_num_fds(), ps_num_threads(), ps_open_files(), ps_pid(), ps_ppid(), ps_resume(), ps_send_signal(), ps_shared_libs(), ps_status(), ps_suspend(), ps_terminal(), ps_terminate(), ps_uids(), ps_username()

Examples

p <- ps_handle()
p

Description

Sends SIGINT on POSIX, and 'CTRL+C' or 'CTRL+BREAK' on Windows.

Usage

ps_interrupt(p = ps_handle(), ctrl_c = TRUE)

Arguments

See Also

Other process handle functions: ps_children(), ps_cmdline(), ps_connections(), ps_cpu_times(), ps_create_time(), ps_cwd(), ps_descent(), ps_environ(), ps_exe(), ps_handle(), ps_is_running(), ps_kill(), ps_memory_info(), ps_name(), ps_num_fds(), ps_num_threads(), ps_open_files(), ps_pid(), ps_ppid(), ps_resume(), ps_send_signal(), ps_shared_libs(), ps_status(), ps_suspend(), ps_terminal(), ps_terminate(), ps_uids(), ps_username()

Description

It returns FALSE if the process has already finished.

Usage

ps_is_running(p = ps_handle())

Arguments

Details

It uses the start time of the process to work around pid reuse. I.e.

Value

Logical scalar.

See Also

Other process handle functions: ps_children(), ps_cmdline(), ps_connections(), ps_cpu_times(), ps_create_time(), ps_cwd(), ps_descent(), ps_environ(), ps_exe(), ps_handle(), ps_interrupt(), ps_kill(), ps_memory_info(), ps_name(), ps_num_fds(), ps_num_threads(), ps_open_files(), ps_pid(), ps_ppid(), ps_resume(), ps_send_signal(), ps_shared_libs(), ps_status(), ps_suspend(), ps_terminal(), ps_terminate(), ps_uids(), ps_username()

Examples

p <- ps_handle()
p
ps_is_running(p)

Description

Kill the current process with SIGKILL preemptively checking whether PID has been reused. On Windows it uses TerminateProcess().

Usage

ps_kill(p = ps_handle())

Arguments

See Also

Other process handle functions: ps_children(), ps_cmdline(), ps_connections(), ps_cpu_times(), ps_create_time(), ps_cwd(), ps_descent(), ps_environ(), ps_exe(), ps_handle(), ps_interrupt(), ps_is_running(), ps_memory_info(), ps_name(), ps_num_fds(), ps_num_threads(), ps_open_files(), ps_pid(), ps_ppid(), ps_resume(), ps_send_signal(), ps_shared_libs(), ps_status(), ps_suspend(), ps_terminal(), ps_terminate(), ps_uids(), ps_username()

Examples

px <- processx::process$new("sleep", "10")
p <- ps_handle(px$get_pid())
p
ps_kill(p)
p
ps_is_running(p)
px$get_exit_status()

Description

The “load” represents the processes which are in a runnable state, either using the CPU or waiting to use the CPU (e.g. waiting for disk I/O). On Windows this is emulated by using a Windows API that spawns a thread which keeps running in background and updates results every 5 seconds, mimicking the UNIX behavior. Thus, on Windows, the first time this is called and for the next 5 seconds it will return a meaningless (0.0, 0.0, 0.0) vector. The numbers returned only make sense if related to the number of CPU cores installed on the system. So, for instance, a value of 3.14 on a system with 10 logical CPUs means that the system load was 31.4% percent over the last N minutes.

Usage

ps_loadavg()

Value

Numeric vector of length 3.

Examples

ps_loadavg()

Description

ps_mark_tree() generates a random environment variable name and sets it in the current R process. This environment variable will be (by default) inherited by all child (and grandchild, etc.) processes, and will help finding these processes, even if and when they are (no longer) related to the current R process. (I.e. they are not connected in the process tree.)

Usage

ps_mark_tree()

with_process_cleanup(expr)

ps_find_tree(marker)

ps_kill_tree(marker, sig = signals()$SIGKILL)

Arguments

Details

ps_find_tree() finds the processes that set the supplied environment variable and returns them in a list.

ps_kill_tree() finds the processes that set the supplied environment variable, and kills them (or sends them the specified signal on Unix).

with_process_cleanup() evaluates an R expression, and cleans up all external processes that were started by the R process while evaluating the expression. This includes child processes of child processes, etc., recursively. It returns a list with entries: result is the result of the expression, visible is TRUE if the expression should be printed to the screen, and process_cleanup is a named integer vector of the cleaned pids, names are the process names.

If expr throws an error, then so does with_process_cleanup(), the same error. Nevertheless processes are still cleaned up.

Value

ps_mark_tree() returns the name of the environment variable, which can be used as the marker in ps_kill_tree().

ps_find_tree() returns a list of ps_handle objects.

ps_kill_tree() returns the pids of the killed processes, in a named integer vector. The names are the file names of the executables, when available.

with_process_cleanup() returns the value of the evaluated expression.

Note

Note that with_process_cleanup() is problematic if the R process is multi-threaded and the other threads start subprocesses. with_process_cleanup() cleans up those processes as well, which is probably not what you want. This is an issue for example in RStudio. Do not use with_process_cleanup(), unless you are sure that the R process is single-threaded, or the other threads do not start subprocesses. E.g. using it in package test cases is usually fine, because RStudio runs these in a separate single-threaded process.

The same holds for manually running ps_mark_tree() and then ps_find_tree() or ps_kill_tree().

A safe way to use process cleanup is to use the processx package to start subprocesses, and set the cleanup_tree = TRUE in processx::run() or the processx::process constructor.

Description

Memory usage information

Usage

ps_memory_info(p = ps_handle())

ps_memory_full_info(p = ps_handle())

Arguments

Details

ps_memory_info() returns information about memory usage.

It returns a named list. Portable fields:

• rss: "Resident Set Size", this is the non-swapped physical memory a process has used (bytes). On UNIX it matches "top"‘s 'RES' column (see doc). On Windows this is an alias for wset field and it matches "Memory" column of taskmgr.exe.

• vmem: "Virtual Memory Size", this is the total amount of virtual memory used by the process (bytes). On UNIX it matches "top"‘s 'VIRT' column (see doc). On Windows this is an alias for the pagefile field and it matches the "Working set (memory)" column of taskmgr.exe.

Non-portable fields:

• shared: (Linux) memory that could be potentially shared with other processes (bytes). This matches "top"‘s 'SHR' column (see doc).

• text: (Linux): aka 'TRS' (text resident set) the amount of memory devoted to executable code (bytes). This matches "top"‘s 'CODE' column (see doc).

• data: (Linux): aka 'DRS' (data resident set) the amount of physical memory devoted to other than executable code (bytes). It matches "top"‘s 'DATA' column (see doc).

• lib: (Linux): the memory used by shared libraries (bytes).

• dirty: (Linux): the amount of memory in dirty pages (bytes).

• pfaults: (macOS): number of page faults.

• pageins: (macOS): number of actual pageins.

For the explanation of Windows fields see the PROCESS_MEMORY_COUNTERS_EX structure.

ps_memory_full_info() returns all fields as ps_memory_info(), plus additional information, but typically takes slightly longer to run, and might not have access to some processes that ps_memory_info() can query:

• uss: Unique Set Size, this is the memory which is unique to a process and which would be freed if the process was terminated right now.

• pss (Linux only): Proportional Set Size, is the amount of memory shared with other processes, accounted in a way that the amount is divided evenly between the processes that share it. I.e. if a process has 10 MBs all to itself and 10 MBs shared with another process its PSS will be 15 MBs.

• swap (Linux only): amount of memory that has been swapped out to disk.

They both throw a zombie_process() error for zombie processes.

Value

Named real vector.

See Also

Other process handle functions: ps_children(), ps_cmdline(), ps_connections(), ps_cpu_times(), ps_create_time(), ps_cwd(), ps_descent(), ps_environ(), ps_exe(), ps_handle(), ps_interrupt(), ps_is_running(), ps_kill(), ps_name(), ps_num_fds(), ps_num_threads(), ps_open_files(), ps_pid(), ps_ppid(), ps_resume(), ps_send_signal(), ps_shared_libs(), ps_status(), ps_suspend(), ps_terminal(), ps_terminate(), ps_uids(), ps_username()

Examples

p <- ps_handle()
p
ps_memory_info(p)
ps_memory_full_info(p)

Description

The name of the program, which is typically the name of the executable.

Usage

ps_name(p = ps_handle())

Arguments

Details

On Unix this can change, e.g. via an exec*() system call.

ps_name() works on zombie processes.

Value

Character scalar.

See Also

Other process handle functions: ps_children(), ps_cmdline(), ps_connections(), ps_cpu_times(), ps_create_time(), ps_cwd(), ps_descent(), ps_environ(), ps_exe(), ps_handle(), ps_interrupt(), ps_is_running(), ps_kill(), ps_memory_info(), ps_num_fds(), ps_num_threads(), ps_open_files(), ps_pid(), ps_ppid(), ps_resume(), ps_send_signal(), ps_shared_libs(), ps_status(), ps_suspend(), ps_terminal(), ps_terminate(), ps_uids(), ps_username()

Examples

p <- ps_handle()
p
ps_name(p)
ps_exe(p)
ps_cmdline(p)

Description

Note that in some IDEs, e.g. RStudio or R.app on macOS, the IDE itself opens files from other threads, in addition to the files opened from the main R thread.

Usage

ps_num_fds(p = ps_handle())

Arguments

Details

For a zombie process it throws a zombie_process error.

Value

Integer scalar.

See Also

Other process handle functions: ps_children(), ps_cmdline(), ps_connections(), ps_cpu_times(), ps_create_time(), ps_cwd(), ps_descent(), ps_environ(), ps_exe(), ps_handle(), ps_interrupt(), ps_is_running(), ps_kill(), ps_memory_info(), ps_name(), ps_num_threads(), ps_open_files(), ps_pid(), ps_ppid(), ps_resume(), ps_send_signal(), ps_shared_libs(), ps_status(), ps_suspend(), ps_terminal(), ps_terminate(), ps_uids(), ps_username()

Examples

p <- ps_handle()
ps_num_fds(p)
f <- file(tmp <- tempfile(), "w")
ps_num_fds(p)
close(f)
unlink(tmp)
ps_num_fds(p)

Description

Throws a zombie_process() error for zombie processes.

Usage

ps_num_threads(p = ps_handle())

Arguments

Value

Integer scalar.

See Also

Other process handle functions: ps_children(), ps_cmdline(), ps_connections(), ps_cpu_times(), ps_create_time(), ps_cwd(), ps_descent(), ps_environ(), ps_exe(), ps_handle(), ps_interrupt(), ps_is_running(), ps_kill(), ps_memory_info(), ps_name(), ps_num_fds(), ps_open_files(), ps_pid(), ps_ppid(), ps_resume(), ps_send_signal(), ps_shared_libs(), ps_status(), ps_suspend(), ps_terminal(), ps_terminate(), ps_uids(), ps_username()

Examples

p <- ps_handle()
p
ps_num_threads(p)

Description

Note that in some IDEs, e.g. RStudio or R.app on macOS, the IDE itself opens files from other threads, in addition to the files opened from the main R thread.

Usage

ps_open_files(p = ps_handle())

Arguments

Details

For a zombie process it throws a zombie_process error.

Value

Data frame with columns: fd and path. fd is numeric file descriptor on POSIX systems, NA on Windows. path is an absolute path to the file.

See Also

Other process handle functions: ps_children(), ps_cmdline(), ps_connections(), ps_cpu_times(), ps_create_time(), ps_cwd(), ps_descent(), ps_environ(), ps_exe(), ps_handle(), ps_interrupt(), ps_is_running(), ps_kill(), ps_memory_info(), ps_name(), ps_num_fds(), ps_num_threads(), ps_pid(), ps_ppid(), ps_resume(), ps_send_signal(), ps_shared_libs(), ps_status(), ps_suspend(), ps_terminal(), ps_terminate(), ps_uids(), ps_username()

Examples

p <- ps_handle()
ps_open_files(p)
f <- file(tmp <- tempfile(), "w")
ps_open_files(p)
close(f)
unlink(tmp)
ps_open_files(p)

Description

Query the type of the OS

Usage

ps_os_type()

ps_is_supported()

Value

ps_os_type returns a named logical vector. The rest of the functions return a logical scalar.

ps_is_supported() returns TRUE if ps supports the current platform.

Examples

ps_os_type()
ps_is_supported()

Description

This function works even if the process has already finished.

Usage

ps_pid(p = ps_handle())

Arguments

Value

Process id.

See Also

Other process handle functions: ps_children(), ps_cmdline(), ps_connections(), ps_cpu_times(), ps_create_time(), ps_cwd(), ps_descent(), ps_environ(), ps_exe(), ps_handle(), ps_interrupt(), ps_is_running(), ps_kill(), ps_memory_info(), ps_name(), ps_num_fds(), ps_num_threads(), ps_open_files(), ps_ppid(), ps_resume(), ps_send_signal(), ps_shared_libs(), ps_status(), ps_suspend(), ps_terminal(), ps_terminate(), ps_uids(), ps_username()

Examples

p <- ps_handle()
p
ps_pid(p)
ps_pid(p) == Sys.getpid()

Description

Ids of all processes on the system

Usage

ps_pids()

Value

Integer vector of process ids.

Description

ps_ppid() returns the parent pid, ps_parent() returns a ps_handle of the parent.

Usage

ps_ppid(p = ps_handle())

ps_parent(p = ps_handle())

Arguments

Details

On POSIX systems, if the parent process terminates, another process (typically the pid 1 process) is marked as parent. ps_ppid() and ps_parent() will return this process then.

Both ps_ppid() and ps_parent() work for zombie processes.

Value

ps_ppid() returns and integer scalar, the pid of the parent of p. ps_parent() returns a ps_handle.

See Also

Other process handle functions: ps_children(), ps_cmdline(), ps_connections(), ps_cpu_times(), ps_create_time(), ps_cwd(), ps_descent(), ps_environ(), ps_exe(), ps_handle(), ps_interrupt(), ps_is_running(), ps_kill(), ps_memory_info(), ps_name(), ps_num_fds(), ps_num_threads(), ps_open_files(), ps_pid(), ps_resume(), ps_send_signal(), ps_shared_libs(), ps_status(), ps_suspend(), ps_terminal(), ps_terminate(), ps_uids(), ps_username()

Examples

p <- ps_handle()
p
ps_ppid(p)
ps_parent(p)

Description

Resume process execution with SIGCONT preemptively checking whether PID has been reused. On Windows this has the effect of resuming all process threads.

Usage

ps_resume(p = ps_handle())

Arguments

See Also

Other process handle functions: ps_children(), ps_cmdline(), ps_connections(), ps_cpu_times(), ps_create_time(), ps_cwd(), ps_descent(), ps_environ(), ps_exe(), ps_handle(), ps_interrupt(), ps_is_running(), ps_kill(), ps_memory_info(), ps_name(), ps_num_fds(), ps_num_threads(), ps_open_files(), ps_pid(), ps_ppid(), ps_send_signal(), ps_shared_libs(), ps_status(), ps_suspend(), ps_terminal(), ps_terminate(), ps_uids(), ps_username()

Examples

px <- processx::process$new("sleep", "10")
p <- ps_handle(px$get_pid())
p
ps_suspend(p)
ps_status(p)
ps_resume(p)
ps_status(p)
ps_kill(p)

Description

Send a signal to the process. Not implemented on Windows. See signals() for the list of signals on the current platform.

Usage

ps_send_signal(p = ps_handle(), sig)

Arguments

Details

It checks if the process is still running, before sending the signal, to avoid signalling the wrong process, because of pid reuse.

See Also

Other process handle functions: ps_children(), ps_cmdline(), ps_connections(), ps_cpu_times(), ps_create_time(), ps_cwd(), ps_descent(), ps_environ(), ps_exe(), ps_handle(), ps_interrupt(), ps_is_running(), ps_kill(), ps_memory_info(), ps_name(), ps_num_fds(), ps_num_threads(), ps_open_files(), ps_pid(), ps_ppid(), ps_resume(), ps_shared_libs(), ps_status(), ps_suspend(), ps_terminal(), ps_terminate(), ps_uids(), ps_username()

Examples

px <- processx::process$new("sleep", "10")
p <- ps_handle(px$get_pid())
p
ps_send_signal(p, signals()$SIGINT)
p
ps_is_running(p)
px$get_exit_status()

Description

List all processes that loaded a shared library

Usage

ps_shared_lib_users(paths, user = ps_username(), filter = NULL)

Arguments

Details

Notes:

This function currently only works on Windows.

On Windows, a 32 bit R process can only list other 32 bit processes. Similarly, a 64 bit R process can only list other 64 bit processes. This is a limitation of the Windows API.

Even though Windows file systems are (almost always) case insensitive, the matching of paths, user and also filter are case sensitive. This might change in the future.

This function can be very slow on Windows, because it needs to enumerate all shared libraries of all processes in the system, unless the filter argument is set. Make sure you set filter if you can.

If you want to look up multiple shared libraries, list all of them in paths, instead of calling ps_shared_lib_users for each individually.

If you are after libraries loaded by R processes, you might want to set filter to c("Rgui.exe", "Rterm.exe", "rsession.exe") The last one is for RStudio.

Value

A data frame with columns:

• dll: the file name of the dll file, without the path,

• path: path to the shared library,

• pid: process ID of the process,

• name: name of the process,

• username: username of process owner,

• ps_handle: ps_handle object, that can be used to further query and manipulate the process.

See Also

Other shared library tools: ps_shared_libs()

Examples

dlls <- vapply(getLoadedDLLs(), "[[", character(1), "path")
psdll <- dlls[["ps"]][[1]]
r_procs <- c("Rgui.exe", "Rterm.exe", "rsession.exe")
ps_shared_lib_users(psdll, filter = r_procs)

Description

Note: this function currently only works on Windows.

Usage

ps_shared_libs(p = ps_handle())

Arguments

Value

Data frame with one column currently: path, the absolute path to the loaded module or shared library. On Windows the list includes the executable file itself.

See Also

Other process handle functions: ps_children(), ps_cmdline(), ps_connections(), ps_cpu_times(), ps_create_time(), ps_cwd(), ps_descent(), ps_environ(), ps_exe(), ps_handle(), ps_interrupt(), ps_is_running(), ps_kill(), ps_memory_info(), ps_name(), ps_num_fds(), ps_num_threads(), ps_open_files(), ps_pid(), ps_ppid(), ps_resume(), ps_send_signal(), ps_status(), ps_suspend(), ps_terminal(), ps_terminate(), ps_uids(), ps_username()

Other shared library tools: ps_shared_lib_users()

Examples

# The loaded DLLs of the current process
ps_shared_libs()

Description

One of the following:

• "idle": Process being created by fork, macOS only.

• "running": Currently runnable on macOS and Windows. Actually running on Linux.

• "sleeping" Sleeping on a wait or poll.

• "disk_sleep" Uninterruptible sleep, waiting for an I/O operation (Linux only).

• "stopped" Stopped, either by a job control signal or because it is being traced.

• "tracing_stop" Stopped for tracing (Linux only).

• "zombie" Zombie. Finished, but parent has not read out the exit status yet.

• "dead" Should never be seen (Linux).

• "wake_kill" Received fatal signal (Linux only).

• "waking" Paging (Linux only, not valid since the 2.6.xx kernel).

Usage

ps_status(p = ps_handle())

Arguments

Details

Works for zombie processes.

Value

Character scalar.

See Also

Other process handle functions: ps_children(), ps_cmdline(), ps_connections(), ps_cpu_times(), ps_create_time(), ps_cwd(), ps_descent(), ps_environ(), ps_exe(), ps_handle(), ps_interrupt(), ps_is_running(), ps_kill(), ps_memory_info(), ps_name(), ps_num_fds(), ps_num_threads(), ps_open_files(), ps_pid(), ps_ppid(), ps_resume(), ps_send_signal(), ps_shared_libs(), ps_suspend(), ps_terminal(), ps_terminate(), ps_uids(), ps_username()

Examples

p <- ps_handle()
p
ps_status(p)

Description

Suspend process execution with SIGSTOP preemptively checking whether PID has been reused. On Windows this has the effect of suspending all process threads.

Usage

ps_suspend(p = ps_handle())

Arguments

See Also

Other process handle functions: ps_children(), ps_cmdline(), ps_connections(), ps_cpu_times(), ps_create_time(), ps_cwd(), ps_descent(), ps_environ(), ps_exe(), ps_handle(), ps_interrupt(), ps_is_running(), ps_kill(), ps_memory_info(), ps_name(), ps_num_fds(), ps_num_threads(), ps_open_files(), ps_pid(), ps_ppid(), ps_resume(), ps_send_signal(), ps_shared_libs(), ps_status(), ps_terminal(), ps_terminate(), ps_uids(), ps_username()

Examples

px <- processx::process$new("sleep", "10")
p <- ps_handle(px$get_pid())
p
ps_suspend(p)
ps_status(p)
ps_resume(p)
ps_status(p)
ps_kill(p)

Description

Every attribute represents the seconds the CPU has spent in the given mode. The attributes availability varies depending on the platform:

• user: time spent by normal processes executing in user mode; on Linux this also includes guest time.

• system: time spent by processes executing in kernel mode.

• idle: time spent doing nothing.

Usage

ps_system_cpu_times()

Details

Platform-specific fields:

• nice (UNIX): time spent by niced (prioritized) processes executing in user mode; on Linux this also includes guest_nice time.

• iowait (Linux): time spent waiting for I/O to complete. This is not accounted in idle time counter.

• irq (Linux): time spent for servicing hardware interrupts.

• softirq (Linux): time spent for servicing software interrupts.

• steal (Linux 2.6.11+): time spent by other operating systems running in a virtualized environment.

• guest (Linux 2.6.24+): time spent running a virtual CPU for guest operating systems under the control of the Linux kernel.

• guest_nice (Linux 3.2.0+): time spent running a niced guest (virtual CPU for guest operating systems under the control of the Linux kernel).

Value

Named list

Examples

ps_system_cpu_times()

Description

Statistics about system memory usage

Usage

ps_system_memory()

Value

Named list. All numbers are in bytes:

• total: total physical memory (exclusive swap).

• avail the memory that can be given instantly to processes without the system going into swap. This is calculated by summing different memory values depending on the platform and it is supposed to be used to monitor actual memory usage in a cross platform fashion.

• percent: Percentage of memory that is taken.

• used: memory used, calculated differently depending on the platform and designed for informational purposes only. total - free does not necessarily match used.

• free: memory not being used at all (zeroed) that is readily available; note that this doesn’t reflect the actual memory available (use available instead). total - used does not necessarily match free.

• active: (Unix only) memory currently in use or very recently used, and so it is in RAM.

• inactive: (Unix only) memory that is marked as not used.

• wired: (macOS only) memory that is marked to always stay in RAM. It is never moved to disk.

• buffers: (Linux only) cache for things like file system metadata.

• cached: (Linux only) cache for various things.

• shared: (Linux only) memory that may be simultaneously accessed by multiple processes.

• slab: (Linux only) in-kernel data structures cache.

See Also

Other memory functions: ps_system_swap()

Examples

ps_system_memory()

Description

System swap memory statistics

Usage

ps_system_swap()

Value

Named list. All numbers are in bytes:

• total: total swap memory.

• used: used swap memory.

• free: free swap memory.

• percent: the percentage usage.

• sin: the number of bytes the system has swapped in from disk (cumulative). This is NA on Windows.

• sout: the number of bytes the system has swapped out from disk (cumulative). This is NA on Windows.

See Also

Other memory functions: ps_system_memory()

Examples

ps_system_swap()

Description

Returns the terminal of the process. Not implemented on Windows, always returns NA_character_. On Unix it returns NA_character_ if the process has no terminal.

Usage

ps_terminal(p = ps_handle())

Arguments

Details

Works for zombie processes.

Value

Character scalar.

See Also

Other process handle functions: ps_children(), ps_cmdline(), ps_connections(), ps_cpu_times(), ps_create_time(), ps_cwd(), ps_descent(), ps_environ(), ps_exe(), ps_handle(), ps_interrupt(), ps_is_running(), ps_kill(), ps_memory_info(), ps_name(), ps_num_fds(), ps_num_threads(), ps_open_files(), ps_pid(), ps_ppid(), ps_resume(), ps_send_signal(), ps_shared_libs(), ps_status(), ps_suspend(), ps_terminate(), ps_uids(), ps_username()

Examples

p <- ps_handle()
p
ps_terminal(p)

Description

Send a SIGTERM signal to the process. Not implemented on Windows.

Usage

ps_terminate(p = ps_handle())

Arguments

Details

Checks if the process is still running, to work around pid reuse.

See Also

Other process handle functions: ps_children(), ps_cmdline(), ps_connections(), ps_cpu_times(), ps_create_time(), ps_cwd(), ps_descent(), ps_environ(), ps_exe(), ps_handle(), ps_interrupt(), ps_is_running(), ps_kill(), ps_memory_info(), ps_name(), ps_num_fds(), ps_num_threads(), ps_open_files(), ps_pid(), ps_ppid(), ps_resume(), ps_send_signal(), ps_shared_libs(), ps_status(), ps_suspend(), ps_terminal(), ps_uids(), ps_username()

Examples

px <- processx::process$new("sleep", "10")
p <- ps_handle(px$get_pid())
p
ps_terminate(p)
p
ps_is_running(p)
px$get_exit_status()

Description

If the standard output of the current R process is not a terminal, e.g. because it is redirected to a file, or the R process is running in a GUI, then it will throw an error. You need to handle this error if you want to use this function in a package.

Usage

ps_tty_size()

Details

If an error happens, the error message is different depending on what type of device the standard output is. Some common error messages are:

• "Inappropriate ioctl for device."

• "Operation not supported on socket."

• "Operation not supported by device."

Whatever the error message, ps_tty_size always fails with an error of class ps_unknown_tty_size, which you can catch.

Examples

# An example that falls back to the 'width' option
tryCatch(
  ps_tty_size(),
  ps_unknown_tty_size = function(err) {
    c(width = getOption("width"), height = NA_integer_)
  }
)

Description

User ids and group ids of the process. Both return integer vectors with names: real, effective and saved.

Usage

ps_uids(p = ps_handle())

ps_gids(p = ps_handle())

Arguments

Details

Both work for zombie processes.

They are not implemented on Windows, they throw a not_implemented error.

Value

Named integer vector of length 3, with names: real, effective and saved.

See Also

ps_username() returns a user name and works on all platforms.

Other process handle functions: ps_children(), ps_cmdline(), ps_connections(), ps_cpu_times(), ps_create_time(), ps_cwd(), ps_descent(), ps_environ(), ps_exe(), ps_handle(), ps_interrupt(), ps_is_running(), ps_kill(), ps_memory_info(), ps_name(), ps_num_fds(), ps_num_threads(), ps_open_files(), ps_pid(), ps_ppid(), ps_resume(), ps_send_signal(), ps_shared_libs(), ps_status(), ps_suspend(), ps_terminal(), ps_terminate(), ps_username()

Examples

p <- ps_handle()
p
ps_uids(p)
ps_gids(p)

Description

The name of the user that owns the process. On Unix it is calculated from the real user id.

Usage

ps_username(p = ps_handle())

Arguments

Details

On Unix, a numeric uid id returned if the uid is not in the user database, thus a username cannot be determined.

Works for zombie processes.

Value

String scalar.

See Also

Other process handle functions: ps_children(), ps_cmdline(), ps_connections(), ps_cpu_times(), ps_create_time(), ps_cwd(), ps_descent(), ps_environ(), ps_exe(), ps_handle(), ps_interrupt(), ps_is_running(), ps_kill(), ps_memory_info(), ps_name(), ps_num_fds(), ps_num_threads(), ps_open_files(), ps_pid(), ps_ppid(), ps_resume(), ps_send_signal(), ps_shared_libs(), ps_status(), ps_suspend(), ps_terminal(), ps_terminate(), ps_uids()

Examples

p <- ps_handle()
p
ps_username(p)

Description

List users connected to the system

Usage

ps_users()

Value

A data frame with columns username, tty, hostname, start_time, pid. tty and pid are NA on Windows. pid is the process id of the login process. For local users the hostname column is the empty string.

Description

ps_get_nice() returns the current priority, ps_set_nice() sets a new priority, ps_windows_nice_values() list the possible priority values on Windows.

Usage

ps_windows_nice_values()

ps_get_nice(p = ps_handle())

ps_set_nice(p = ps_handle(), value)

Arguments

Details

Priority values are different on Windows and Unix.

On Unix, priority is an integer, which is maximum 20. 20 is the lowest priority.

Rules:

• On Windows you can only set the priority of the processes the current user has PROCESS_SET_INFORMATION access rights to. This typically means your own processes.

• On Unix you can only set the priority of the your own processes. The superuser can set the priority of any process.

• On Unix you cannot set a higher priority, unless you are the superuser. (I.e. you cannot set a lower number.)

• On Unix the default priority of a process is zero.

Value

ps_windows_nice_values() return a character vector of possible priority values on Windows.

ps_get_nice() returns a string from ps_windows_nice_values() on Windows. On Unix it returns an integer smaller than or equal to 20.

ps_set_nice() return NULL invisibly.

Description

Only the signals supported by the current platform are included.

Usage

signals()

Value

List of integers, named by signal names.