{"id":13705961,"url":"https://github.com/r-lib/ps","last_synced_at":"2025-05-15T12:03:47.218Z","repository":{"id":38848726,"uuid":"137484217","full_name":"r-lib/ps","owner":"r-lib","description":"R package to query, list, manipulate system processes","archived":false,"fork":false,"pushed_at":"2025-04-28T09:14:34.000Z","size":9234,"stargazers_count":80,"open_issues_count":7,"forks_count":21,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-03T03:09:57.820Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://ps.r-lib.org/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/r-lib.png","metadata":{"files":{"readme":"README.Rmd","changelog":"NEWS.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":".github/SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-06-15T12:19:35.000Z","updated_at":"2025-04-28T09:11:40.000Z","dependencies_parsed_at":"2023-10-04T07:27:09.555Z","dependency_job_id":"bec1a553-500b-41c6-b68c-a31567e8e879","html_url":"https://github.com/r-lib/ps","commit_stats":{"total_commits":567,"total_committers":13,"mean_commits":43.61538461538461,"dds":0.04585537918871252,"last_synced_commit":"0f04d123e8dc71f1f8fe2195b5616a7e7512af65"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-lib%2Fps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-lib%2Fps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-lib%2Fps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-lib%2Fps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/r-lib","download_url":"https://codeload.github.com/r-lib/ps/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254049484,"owners_count":22006073,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T22:00:50.421Z","updated_at":"2025-05-15T12:03:42.200Z","avatar_url":"https://github.com/r-lib.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"---\noutput:\n  github_document:\n    toc: true\n    toc_depth: 3\n    includes:\n      before_body: header.md\n---\n\n```{r echo = FALSE}\noptions(width = 100)\nsuppressWarnings(suppressPackageStartupMessages(suppressMessages(library(dplyr))))\nsuppressWarnings(suppressMessages(library(pillar)))\n```\n\n## Installation\n\nYou can install the released version of ps from\n[CRAN](https://CRAN.R-project.org) with:\n\n``` r\ninstall.packages(\"ps\")\n```\n\nIf you need the development version, install it with\n\n``` r\npak::pak(\"r-lib/ps\")\n```\n\n```{r}\nlibrary(ps)\nlibrary(pillar) # nicer printing of data frames\n```\n\n## Supported platforms\n\nps currently supports Windows (from Vista), macOS and Linux systems.\nOn unsupported platforms the package can be installed and loaded, but\nall of its functions fail with an error of class `\"not_implemented\"`.\n\n## Listing all processes\n\n`ps_pids()` returns all process ids on the system. This can be useful to\niterate over all processes.\n\n```{r}\nps_pids()[1:20]\n```\n\n`ps()` returns a data frame, with data about each process. It contains a\nhandle to each process, in the `ps_handle` column, you can use these to\nperform more queries on the processes.\n\n```{r}\nps()\n```\n\n## Process API\n\nThis is a short summary of the API. Please see the documentation of the\nvarious methods for details, in particular regarding handles to finished\nprocesses and pid reuse. See also \"Finished and zombie processes\"\nand \"pid reuse\" below.\n\n`ps_handle(pid)` creates a process handle for the supplied process id.\nIf `pid` is omitted, a handle to the calling process is returned:\n\n```{r}\np \u003c- ps_handle()\np\n```\n\n### Query functions\n\n`ps_pid(p)` returns the pid of the process.\n\n```{r}\nps_pid(p)\n```\n\n`ps_create_time()` returns the creation time of the process (according to\nthe OS).\n\n```{r}\nps_create_time(p)\n```\n\nThe process id and the creation time uniquely identify a process in a\nsystem. ps uses them to make sure that it reports information about, and\nmanipulates the correct process.\n\n`ps_is_running(p)` returns whether `p` is still running. It handles pid\nreuse safely.\n\n```{r}\nps_is_running(p)\n```\n\n`ps_ppid(p)` returns the pid of the parent of `p`.\n\n```{r}\nps_ppid(p)\n```\n\n`ps_parent(p)` returns a process handle to the parent process of `p`.\n\n```{r}\nps_parent(p)\n```\n\n`ps_name(p)` returns the name of the program `p` is running.\n\n```{r}\nps_name(p)\n```\n\n`ps_exe(p)` returns the full path to the executable the `p` is running.\n\n```{r}\nps_exe(p)\n```\n\n`ps_cmdline(p)` returns the command line (executable and arguments) of `p`.\n\n```{r}\nps_cmdline(p)\n```\n\n`ps_status(p)` returns the status of the process. Possible values are OS\ndependent, but typically there is `\"running\"` and `\"stopped\"`.\n\n```{r}\nps_status(p)\n```\n\n`ps_username(p)` returns the name of the user the process belongs to.\n\n```{r}\nps_username(p)\n```\n\n`ps_uids(p)` and  `ps_gids(p)` return the real, effective and saved user\nids of the process. They are only implemented on POSIX systems.\n\n```{r}\nif (ps_os_type()[[\"POSIX\"]]) ps_uids(p)\nif (ps_os_type()[[\"POSIX\"]]) ps_gids(p)\n```\n\n`ps_cwd(p)` returns the current working directory of the process.\n\n```{r}\nps_cwd(p)\n```\n\n`ps_terminal(p)` returns the name of the terminal of the process, if any.\nFor processes without a terminal, and on Windows it returns `NA_character_`.\n\n```{r}\nps_terminal(p)\n```\n\n`ps_environ(p)` returns the environment variables of the process.\n`ps_environ_raw(p)` does the same, in a different form. Typically they\nreflect the environment variables at the start of the process.\n\n```{r}\nps_environ(p)[c(\"TERM\", \"USER\", \"SHELL\", \"R_HOME\")]\n```\n\n`ps_num_threads(p)` returns the current number of threads of the process.\n\n```{r}\nps_num_threads(p)\n```\n\n`ps_cpu_times(p)` returns the CPU times of the process, similarly to\n`proc.time()`.\n\n```{r}\nps_cpu_times(p)\n```\n\n`ps_memory_info(p)` returns memory usage information. See the manual for\ndetails.\n\n```{r}\nps_memory_info(p)\n```\n\n`ps_children(p)` lists all child processes (potentially recursively) of\nthe current process.\n\n```{r}\nps_children(ps_parent(p))\n```\n\n`ps_num_fds(p)` returns the number of open file descriptors (handles on\nWindows):\n\n```{r}\nps_num_fds(p)\nf \u003c- file(tmp \u003c- tempfile(), \"w\")\nps_num_fds(p)\nclose(f)\nunlink(tmp)\n```\n\n`ps_open_files(p)` lists all open files:\n\n```{r}\nps_open_files(p)\nf \u003c- file(tmp \u003c- tempfile(), \"w\")\nps_open_files(p)\nclose(f)\nunlink(tmp)\nps_open_files(p)\n```\n\n### Process manipulation\n\n`ps_suspend(p)` suspends (stops) the process. On POSIX it sends a SIGSTOP\nsignal. On Windows it stops all threads.\n\n`ps_resume(p)` resumes the process. On POSIX it sends a SIGCONT signal. On\nWindows it resumes all stopped threads.\n\n`ps_send_signal(p)` sends a signal to the process. It is implemented on\nPOSIX systems only. It makes an effort to work around pid reuse.\n\n`ps_terminate(p)` send SIGTERM to the process. On POSIX systems only.\n\n`ps_kill(p)` terminates the process. Sends `SIGKILL` on POSIX systems,\nuses `TerminateProcess()` on Windows. It make an effort to work around\npid reuse.\n\n`ps_interrupt(p)` interrupts a process. It sends a `SIGINT` signal on\nPOSIX systems, and it can send a CTRL+C or a CTRL+BREAK event on Windows.\n\n## Finished and zombie processes\n\nps handles finished and Zombie processes as much as possible.\n\nThe essential `ps_pid()`, `ps_create_time()`, `ps_is_running()` functions\nand the `format()` and `print()` methods work for all processes, including\nfinished and zombie processes. Other functions fail with an error of class\n`\"no_such_process\"` for finished processes.\n\nThe `ps_ppid()`, `ps_parent()`, `ps_children()`, `ps_name()`,\n`ps_status()`, `ps_username()`, `ps_uids()`, `ps_gids()`, `ps_terminal()`,\n`ps_children()` and the signal sending functions work properly for\nzombie processes. Other functions fail with `\"zombie_process\"` error.\n\n## Pid reuse\n\nps functions handle pid reuse as well as technically possible.\n\nThe query functions never return information about the wrong process, even\nif the process has finished and its process id was re-assigned.\n\nOn Windows, the process manipulation functions never manipulate the wrong\nprocess.\n\nOn POSIX systems, this is technically impossible, it is not possible to\nsend a signal to a process without creating a race condition. In ps the\ntime window of the race condition is very small, a few microseconds, and\nthe process would need to finish, _and_ the OS would need to reuse its pid\nwithin this time window to create problems. This is very unlikely to\nhappen.\n\n## Recipes\n\nIn the spirit of [psutil recipes](http://psutil.readthedocs.io/en/latest/#recipes).\n\n### Find process by name\n\nUsing `ps()` and dplyr:\n\n```{r}\nlibrary(dplyr)\nfind_procs_by_name \u003c- function(name) {\n  ps() %\u003e%\n    filter(name == !!name)  %\u003e%\n    pull(ps_handle)\n}\n\nfind_procs_by_name(\"R\")\n```\n\nWithout creating the full table of processes:\n\n```{r}\nfind_procs_by_name \u003c- function(name) {\n  procs \u003c- lapply(ps_pids(), function(p) {\n    tryCatch({\n      h \u003c- ps_handle(p)\n      if (ps_name(h) == name) h else NULL },\n      no_such_process = function(e) NULL,\n      access_denied = function(e) NULL\n    )\n  })\n  procs[!vapply(procs, is.null, logical(1))]\n  }\n\nfind_procs_by_name(\"R\")\n```\n\n### Wait for a process to finish\n\n`ps_wait()`, from ps 1.8.0, implements a new way, efficient for waiting on\na list of processes, so this is now very easy:\n\n```{r}\npx \u003c- processx::process$new(\"sleep\", \"2\")\np \u003c- px$as_ps_handle()\nps_wait(p, 1000)\nps_wait(p)\n```\n### Wait for several processes to finish\n\nAgain, this is much simpler with `ps_wait()`, added in ps 1.8.0.\n\n```{r}\npx1 \u003c- processx::process$new(\"sleep\", \"10\")\npx2 \u003c- processx::process$new(\"sleep\", \"10\")\npx3 \u003c- processx::process$new(\"sleep\", \"1\")\npx4 \u003c- processx::process$new(\"sleep\", \"1\")\n\np1 \u003c- px1$as_ps_handle()\np2 \u003c- px2$as_ps_handle()\np3 \u003c- px3$as_ps_handle()\np4 \u003c- px4$as_ps_handle()\n\nps_wait(list(p1, p2, p3, p4), timeout = 2000)\n```\n\n### Kill process tree\n\nFrom ps 1.8.0, `ps_kill()` will first send `SIGTERM` signals on Unix,\nand `SIGKILL` after a grace period, if needed.\n\nNote, that some R IDEs, including RStudio, run a multithreaded R process,\nand other threads may start processes as well. `reap_children()` will clean\nup all these as well, potentially causing the IDE to misbehave or crash.\n\n```{r}\nkill_proc_tree \u003c- function(pid, include_parent = TRUE, ...) {\n  if (pid == Sys.getpid() \u0026\u0026 include_parent) stop(\"I refuse to kill myself\")\n  parent \u003c- ps_handle(pid)\n  children \u003c- ps_children(parent, recursive = TRUE)\n  if (include_parent) children \u003c- c(children, list(parent))\n  ps_kill(children, ...)\n}\n\np1 \u003c- processx::process$new(\"sleep\", \"10\")\np2 \u003c- processx::process$new(\"sleep\", \"10\")\np3 \u003c- processx::process$new(\"sleep\", \"10\")\nkill_proc_tree(Sys.getpid(), include_parent = FALSE)\n```\n\n### Filtering and sorting processes\n\nProcess name ending with \"sh\":\n\n```{r}\nps() %\u003e%\n  filter(grepl(\"sh$\", name))\n```\n\nProcesses owned by user:\n\n```{r}\nps() %\u003e%\n  filter(username == Sys.info()[[\"user\"]]) %\u003e%\n  select(pid, name)\n```\n\nProcesses consuming more than 100MB of memory:\n\n```{r}\nps() %\u003e%\n  filter(rss \u003e 100 * 1024 * 1024)\n```\n\nTop 3 memory consuming processes:\n\n```{r}\nps() %\u003e%\n  top_n(3, rss) %\u003e%\n  arrange(desc(rss))\n```\n\nTop 3 processes which consumed the most CPU time:\n\n```{r}\nps() %\u003e%\n  mutate(cpu_time = user + system) %\u003e%\n  top_n(3, cpu_time) %\u003e%\n  arrange(desc(cpu_time)) %\u003e%\n  select(pid, name, cpu_time)\n```\n\n## Code of Conduct\n\nPlease note that the ps project is released with a\n[Contributor Code of Conduct](https://ps.r-lib.org/CODE_OF_CONDUCT.html).\nBy contributing to this project, you agree to abide by its terms.\n\n## License\n\nMIT © RStudio\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr-lib%2Fps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fr-lib%2Fps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr-lib%2Fps/lists"}