From 8b0e9ac1e8e3fb5f44f3d8a06a9cc19237d737a2 Mon Sep 17 00:00:00 2001
From: Kevin Ushey <kevinushey@gmail.com>
Date: Fri, 9 Feb 2024 14:07:12 -0800
Subject: [PATCH] add jobGetState / jobList (#144)

---
 NAMESPACE             |  2 +
 R/jobs.R              | 88 +++++++++++++++++++++----------------------
 man/jobAdd.Rd         | 15 ++++++--
 man/jobAddOutput.Rd   | 13 +++++--
 man/jobAddProgress.Rd | 13 +++++--
 man/jobGetState.Rd    | 27 +++++++++++++
 man/jobList.Rd        | 24 ++++++++++++
 man/jobRemove.Rd      | 15 ++++++--
 man/jobRunScript.Rd   | 15 ++++++--
 man/jobSetProgress.Rd | 15 ++++++--
 man/jobSetState.Rd    | 15 ++++++--
 man/jobSetStatus.Rd   | 15 ++++++--
 12 files changed, 183 insertions(+), 74 deletions(-)
 create mode 100644 man/jobGetState.Rd
 create mode 100644 man/jobList.Rd

diff --git a/NAMESPACE b/NAMESPACE
index 8322171..2d584aa 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -62,6 +62,8 @@ export(isWorkbenchJob)
 export(jobAdd)
 export(jobAddOutput)
 export(jobAddProgress)
+export(jobGetState)
+export(jobList)
 export(jobRemove)
 export(jobRunScript)
 export(jobSetProgress)
diff --git a/R/jobs.R b/R/jobs.R
index f94d79a..2c9db17 100644
--- a/R/jobs.R
+++ b/R/jobs.R
@@ -1,3 +1,4 @@
+
 #' Add a Job
 #' 
 #' Inform RStudio's Background Jobs pane that a job has been added.
@@ -32,11 +33,9 @@
 #' \item{replay}{If there is an action named \code{replay}, then the job will
 #' have a Replay button that displays when the job has finished running. Clicking
 #' the button will invoke the \code{replay} action.}}
-#' @seealso Other jobs: \code{\link{jobAddOutput}()},
-#' \code{\link{jobAddProgress}()}, \code{\link{jobRemove}()},
-#' \code{\link{jobRunScript}()}, \code{\link{jobSetProgress}()},
-#' \code{\link{jobSetState}()}, \code{\link{jobSetStatus}()}
-#' @export jobAdd
+#' 
+#' @family jobs
+#' @export
 jobAdd <- function(name, status = "", progressUnits = 0L, actions = NULL, running = FALSE,
                    autoRemove = TRUE, show = TRUE) {
     callFun("addJob", name          = name,
@@ -54,13 +53,10 @@ jobAdd <- function(name, status = "", progressUnits = 0L, actions = NULL, runnin
 #' 
 #' Remove a background job from RStudio's Background Jobs pane.
 #' 
-#' 
 #' @param job The ID of the job to remove.
-#' @seealso Other jobs: \code{\link{jobAddOutput}()},
-#' \code{\link{jobAddProgress}()}, \code{\link{jobAdd}()},
-#' \code{\link{jobRunScript}()}, \code{\link{jobSetProgress}()},
-#' \code{\link{jobSetState}()}, \code{\link{jobSetStatus}()}
-#' @export jobRemove
+#' 
+#' @family jobs
+#' @export
 jobRemove <- function(job) {
     callFun("removeJob", job = job)
 }
@@ -71,14 +67,11 @@ jobRemove <- function(job) {
 #' 
 #' Updates the progress for a background job.
 #' 
-#' 
 #' @param job The ID of the job to set progress for.
 #' @param units The integer number of total units of work completed so far.
-#' @seealso Other jobs: \code{\link{jobAddOutput}()},
-#' \code{\link{jobAddProgress}()}, \code{\link{jobAdd}()},
-#' \code{\link{jobRemove}()}, \code{\link{jobRunScript}()},
-#' \code{\link{jobSetState}()}, \code{\link{jobSetStatus}()}
-#' @export jobSetProgress
+#' 
+#' @family jobs
+#' @export
 jobSetProgress <- function(job, units) {
     callFun("setJobProgress", job = job, units = units)
 }
@@ -92,11 +85,9 @@ jobSetProgress <- function(job, units) {
 #' 
 #' @param job The ID of the job to update progress for.
 #' @param units The integer number of new progress units completed.
-#' @seealso Other jobs: \code{\link{jobAddOutput}()}, \code{\link{jobAdd}()},
-#' \code{\link{jobRemove}()}, \code{\link{jobRunScript}()},
-#' \code{\link{jobSetProgress}()}, \code{\link{jobSetState}()},
-#' \code{\link{jobSetStatus}()}
-#' @export jobAddProgress
+#'
+#' @family jobs
+#' @export
 jobAddProgress <- function(job, units) {
     callFun("addJobProgress", job = job, units = units)
 }
@@ -110,17 +101,22 @@ jobAddProgress <- function(job, units) {
 #' 
 #' @param job The ID of the job to update.
 #' @param status Text describing job's new status.
-#' @seealso Other jobs: \code{\link{jobAddOutput}()},
-#' \code{\link{jobAddProgress}()}, \code{\link{jobAdd}()},
-#' \code{\link{jobRemove}()}, \code{\link{jobRunScript}()},
-#' \code{\link{jobSetProgress}()}, \code{\link{jobSetState}()}
-#' @export jobSetStatus
+#'
+#' @family jobs
+#' @export
 jobSetStatus <- function(job, status) {
     callFun("setJobStatus", job = job, status = status)
 }
 
-
-
+#' Get Background Job State
+#' 
+#' @param job The ID of the job.
+#' 
+#' @family jobs
+#' @export
+jobGetState <- function(job) {
+    callFun("getJobState", job = job)
+}
 
 #' Set Background Job State
 #' 
@@ -135,11 +131,9 @@ jobSetStatus <- function(job, status) {
 #' waiting to run.} \item{running}{The job is actively running.}
 #' \item{succeeded}{The job has finished successfully.} \item{cancelled}{The
 #' job was cancelled.} \item{failed}{The job finished but did not succeed.} }
-#' @seealso Other jobs: \code{\link{jobAddOutput}()},
-#' \code{\link{jobAddProgress}()}, \code{\link{jobAdd}()},
-#' \code{\link{jobRemove}()}, \code{\link{jobRunScript}()},
-#' \code{\link{jobSetProgress}()}, \code{\link{jobSetStatus}()}
-#' @export jobSetState
+#' 
+#' @family jobs
+#' @export
 jobSetState <- function(job, state = c("idle", "running", "succeeded", "cancelled", "failed")) {
     callFun("setJobState", job = job, state = state)
 }
@@ -155,11 +149,9 @@ jobSetState <- function(job, state = c("idle", "running", "succeeded", "cancelle
 #' @param job The ID of the job that has emitted text.
 #' @param output The text output emitted by the job.
 #' @param error Whether the output represents an error.
-#' @seealso Other jobs: \code{\link{jobAddProgress}()}, \code{\link{jobAdd}()},
-#' \code{\link{jobRemove}()}, \code{\link{jobRunScript}()},
-#' \code{\link{jobSetProgress}()}, \code{\link{jobSetState}()},
-#' \code{\link{jobSetStatus}()}
-#' @export jobAddOutput
+#'
+#' @family jobs
+#' @export
 jobAddOutput <- function(job, output, error = FALSE) {
     callFun("addJobOutput", job = job, output = output, error = error)
 }
@@ -183,11 +175,9 @@ jobAddOutput <- function(job, output, error = FALSE) {
 #' objects created by the job. Use \code{""} (the default) to skip export,
 #' \code{"R_GlobalEnv"}` to export to the global environment, or the name of an
 #' environment object to create an object with that name.
-#' @seealso Other jobs: \code{\link{jobAddOutput}()},
-#' \code{\link{jobAddProgress}()}, \code{\link{jobAdd}()},
-#' \code{\link{jobRemove}()}, \code{\link{jobSetProgress}()},
-#' \code{\link{jobSetState}()}, \code{\link{jobSetStatus}()}
-#' @export jobRunScript
+#'
+#' @family jobs
+#' @export
 jobRunScript <- function(path, name = NULL, encoding = "unknown", workingDir = NULL,
                          importEnv = FALSE, exportEnv = "") {
     path <- normalizePath(path, winslash = "/", mustWork = TRUE)
@@ -198,3 +188,13 @@ jobRunScript <- function(path, name = NULL, encoding = "unknown", workingDir = N
                             importEnv  = importEnv,
                             exportEnv  = exportEnv)
 }
+
+#' List Background Jobs
+#' 
+#' List any registered background jobs.
+#' 
+#' @family jobs
+#' @export
+jobList <- function() {
+    callFun("listJobs")
+}
diff --git a/man/jobAdd.Rd b/man/jobAdd.Rd
index ea08354..e2d47a4 100644
--- a/man/jobAdd.Rd
+++ b/man/jobAdd.Rd
@@ -60,8 +60,15 @@ the button will invoke the \code{replay} action.}}
 }
 
 \seealso{
-Other jobs: \code{\link{jobAddOutput}()},
-\code{\link{jobAddProgress}()}, \code{\link{jobRemove}()},
-\code{\link{jobRunScript}()}, \code{\link{jobSetProgress}()},
-\code{\link{jobSetState}()}, \code{\link{jobSetStatus}()}
+Other jobs: 
+\code{\link{jobAddOutput}()},
+\code{\link{jobAddProgress}()},
+\code{\link{jobGetState}()},
+\code{\link{jobList}()},
+\code{\link{jobRemove}()},
+\code{\link{jobRunScript}()},
+\code{\link{jobSetProgress}()},
+\code{\link{jobSetState}()},
+\code{\link{jobSetStatus}()}
 }
+\concept{jobs}
diff --git a/man/jobAddOutput.Rd b/man/jobAddOutput.Rd
index c89fff3..e0dc5e6 100644
--- a/man/jobAddOutput.Rd
+++ b/man/jobAddOutput.Rd
@@ -17,8 +17,15 @@ jobAddOutput(job, output, error = FALSE)
 Adds text output to a background job.
 }
 \seealso{
-Other jobs: \code{\link{jobAddProgress}()}, \code{\link{jobAdd}()},
-\code{\link{jobRemove}()}, \code{\link{jobRunScript}()},
-\code{\link{jobSetProgress}()}, \code{\link{jobSetState}()},
+Other jobs: 
+\code{\link{jobAdd}()},
+\code{\link{jobAddProgress}()},
+\code{\link{jobGetState}()},
+\code{\link{jobList}()},
+\code{\link{jobRemove}()},
+\code{\link{jobRunScript}()},
+\code{\link{jobSetProgress}()},
+\code{\link{jobSetState}()},
 \code{\link{jobSetStatus}()}
 }
+\concept{jobs}
diff --git a/man/jobAddProgress.Rd b/man/jobAddProgress.Rd
index fec7af4..348aa96 100644
--- a/man/jobAddProgress.Rd
+++ b/man/jobAddProgress.Rd
@@ -15,8 +15,15 @@ jobAddProgress(job, units)
 Adds incremental progress units to a background job.
 }
 \seealso{
-Other jobs: \code{\link{jobAddOutput}()}, \code{\link{jobAdd}()},
-\code{\link{jobRemove}()}, \code{\link{jobRunScript}()},
-\code{\link{jobSetProgress}()}, \code{\link{jobSetState}()},
+Other jobs: 
+\code{\link{jobAdd}()},
+\code{\link{jobAddOutput}()},
+\code{\link{jobGetState}()},
+\code{\link{jobList}()},
+\code{\link{jobRemove}()},
+\code{\link{jobRunScript}()},
+\code{\link{jobSetProgress}()},
+\code{\link{jobSetState}()},
 \code{\link{jobSetStatus}()}
 }
+\concept{jobs}
diff --git a/man/jobGetState.Rd b/man/jobGetState.Rd
new file mode 100644
index 0000000..b2fbb1e
--- /dev/null
+++ b/man/jobGetState.Rd
@@ -0,0 +1,27 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/jobs.R
+\name{jobGetState}
+\alias{jobGetState}
+\title{Get Background Job State}
+\usage{
+jobGetState(job)
+}
+\arguments{
+\item{job}{The ID of the job.}
+}
+\description{
+Get Background Job State
+}
+\seealso{
+Other jobs: 
+\code{\link{jobAdd}()},
+\code{\link{jobAddOutput}()},
+\code{\link{jobAddProgress}()},
+\code{\link{jobList}()},
+\code{\link{jobRemove}()},
+\code{\link{jobRunScript}()},
+\code{\link{jobSetProgress}()},
+\code{\link{jobSetState}()},
+\code{\link{jobSetStatus}()}
+}
+\concept{jobs}
diff --git a/man/jobList.Rd b/man/jobList.Rd
new file mode 100644
index 0000000..67129c8
--- /dev/null
+++ b/man/jobList.Rd
@@ -0,0 +1,24 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/jobs.R
+\name{jobList}
+\alias{jobList}
+\title{List Background Jobs}
+\usage{
+jobList()
+}
+\description{
+List any registered background jobs.
+}
+\seealso{
+Other jobs: 
+\code{\link{jobAdd}()},
+\code{\link{jobAddOutput}()},
+\code{\link{jobAddProgress}()},
+\code{\link{jobGetState}()},
+\code{\link{jobRemove}()},
+\code{\link{jobRunScript}()},
+\code{\link{jobSetProgress}()},
+\code{\link{jobSetState}()},
+\code{\link{jobSetStatus}()}
+}
+\concept{jobs}
diff --git a/man/jobRemove.Rd b/man/jobRemove.Rd
index 76a380d..9e55bb9 100644
--- a/man/jobRemove.Rd
+++ b/man/jobRemove.Rd
@@ -13,8 +13,15 @@ jobRemove(job)
 Remove a background job from RStudio's Background Jobs pane.
 }
 \seealso{
-Other jobs: \code{\link{jobAddOutput}()},
-\code{\link{jobAddProgress}()}, \code{\link{jobAdd}()},
-\code{\link{jobRunScript}()}, \code{\link{jobSetProgress}()},
-\code{\link{jobSetState}()}, \code{\link{jobSetStatus}()}
+Other jobs: 
+\code{\link{jobAdd}()},
+\code{\link{jobAddOutput}()},
+\code{\link{jobAddProgress}()},
+\code{\link{jobGetState}()},
+\code{\link{jobList}()},
+\code{\link{jobRunScript}()},
+\code{\link{jobSetProgress}()},
+\code{\link{jobSetState}()},
+\code{\link{jobSetStatus}()}
 }
+\concept{jobs}
diff --git a/man/jobRunScript.Rd b/man/jobRunScript.Rd
index 55d5558..aa28654 100644
--- a/man/jobRunScript.Rd
+++ b/man/jobRunScript.Rd
@@ -35,8 +35,15 @@ environment object to create an object with that name.}
 Starts an R script as a background job.
 }
 \seealso{
-Other jobs: \code{\link{jobAddOutput}()},
-\code{\link{jobAddProgress}()}, \code{\link{jobAdd}()},
-\code{\link{jobRemove}()}, \code{\link{jobSetProgress}()},
-\code{\link{jobSetState}()}, \code{\link{jobSetStatus}()}
+Other jobs: 
+\code{\link{jobAdd}()},
+\code{\link{jobAddOutput}()},
+\code{\link{jobAddProgress}()},
+\code{\link{jobGetState}()},
+\code{\link{jobList}()},
+\code{\link{jobRemove}()},
+\code{\link{jobSetProgress}()},
+\code{\link{jobSetState}()},
+\code{\link{jobSetStatus}()}
 }
+\concept{jobs}
diff --git a/man/jobSetProgress.Rd b/man/jobSetProgress.Rd
index 4c44edf..7f435fc 100644
--- a/man/jobSetProgress.Rd
+++ b/man/jobSetProgress.Rd
@@ -15,8 +15,15 @@ jobSetProgress(job, units)
 Updates the progress for a background job.
 }
 \seealso{
-Other jobs: \code{\link{jobAddOutput}()},
-\code{\link{jobAddProgress}()}, \code{\link{jobAdd}()},
-\code{\link{jobRemove}()}, \code{\link{jobRunScript}()},
-\code{\link{jobSetState}()}, \code{\link{jobSetStatus}()}
+Other jobs: 
+\code{\link{jobAdd}()},
+\code{\link{jobAddOutput}()},
+\code{\link{jobAddProgress}()},
+\code{\link{jobGetState}()},
+\code{\link{jobList}()},
+\code{\link{jobRemove}()},
+\code{\link{jobRunScript}()},
+\code{\link{jobSetState}()},
+\code{\link{jobSetStatus}()}
 }
+\concept{jobs}
diff --git a/man/jobSetState.Rd b/man/jobSetState.Rd
index 2eb85c2..e38a86b 100644
--- a/man/jobSetState.Rd
+++ b/man/jobSetState.Rd
@@ -27,8 +27,15 @@ job was cancelled.} \item{failed}{The job finished but did not succeed.} }
 }
 
 \seealso{
-Other jobs: \code{\link{jobAddOutput}()},
-\code{\link{jobAddProgress}()}, \code{\link{jobAdd}()},
-\code{\link{jobRemove}()}, \code{\link{jobRunScript}()},
-\code{\link{jobSetProgress}()}, \code{\link{jobSetStatus}()}
+Other jobs: 
+\code{\link{jobAdd}()},
+\code{\link{jobAddOutput}()},
+\code{\link{jobAddProgress}()},
+\code{\link{jobGetState}()},
+\code{\link{jobList}()},
+\code{\link{jobRemove}()},
+\code{\link{jobRunScript}()},
+\code{\link{jobSetProgress}()},
+\code{\link{jobSetStatus}()}
 }
+\concept{jobs}
diff --git a/man/jobSetStatus.Rd b/man/jobSetStatus.Rd
index 69db2d9..53a57e8 100644
--- a/man/jobSetStatus.Rd
+++ b/man/jobSetStatus.Rd
@@ -15,8 +15,15 @@ jobSetStatus(job, status)
 Update a background job's informational status text.
 }
 \seealso{
-Other jobs: \code{\link{jobAddOutput}()},
-\code{\link{jobAddProgress}()}, \code{\link{jobAdd}()},
-\code{\link{jobRemove}()}, \code{\link{jobRunScript}()},
-\code{\link{jobSetProgress}()}, \code{\link{jobSetState}()}
+Other jobs: 
+\code{\link{jobAdd}()},
+\code{\link{jobAddOutput}()},
+\code{\link{jobAddProgress}()},
+\code{\link{jobGetState}()},
+\code{\link{jobList}()},
+\code{\link{jobRemove}()},
+\code{\link{jobRunScript}()},
+\code{\link{jobSetProgress}()},
+\code{\link{jobSetState}()}
 }
+\concept{jobs}