TaskState

This class holds the state of a task deployed to an asynchronous backend (i.e., AsyncBackend). See the Details section for more information.

Details

The task state is useful to check if an asynchronous backend is free to execute other operations. A task can only be in one of the following three states at a time:

• task_not_started: When TRUE, it indicates whether the backend is free to execute another operation.

• task_is_running: When TRUE, it indicates that there is a task running on the backend.

• task_is_completed: When TRUE, it indicates that the task has been completed, but the backend is still busy because the task output has not been retrieved.

The task state is determined based on the state of the background session (i.e., see the get_state method for callr::r_session) and the state of the task execution inferred from polling the process (i.e., see the poll_process method for callr::r_session) as follows:

Session State	Execution State	Not Started	Is Running	Is Completed
idle	timeout	TRUE	FALSE	FALSE
busy	timeout	FALSE	TRUE	FALSE
busy	ready	FALSE	FALSE	TRUE

See also

SessionState, AsyncBackend and ProgressTrackingContext.

Active bindings

task_not_started

A logical value indicating whether the task has been started. It is used to determine if the backend is free to execute another operation.

task_is_running

A logical value indicating whether the task is running.

task_is_completed

A logical value indicating whether the task has been completed and the output needs to be retrieved.

Methods

Public methods

• TaskState$new()

• TaskState$clone()

---

Method new()

Create a new TaskState object and determine the state of a task on a given background session.

Usage

TaskState$new(session)

Arguments

session

A callr::r_session object.

Returns

An object of class TaskState.

---

Method clone()

The objects of this class are cloneable with this method.

Usage

TaskState$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

# Handy function to print the task states all at once.
check_state <- function(session) {
    # Create a task state object and determine the state.
    task_state <- TaskState$new(session)

    # Print the state.
    cat(
        "Task not started: ", task_state$task_not_started, "\n",
        "Task is running: ", task_state$task_is_running, "\n",
        "Task is completed: ", task_state$task_is_completed, "\n",
        sep = ""
    )
}

# Create a specification object.
specification <- Specification$new()

# Set the number of cores.
specification$set_cores(cores = 2)

# Set the cluster type.
specification$set_type(type = "psock")

# Create an asynchronous backend object.
backend <- AsyncBackend$new()

# Start the cluster on the backend.
backend$start(specification)

# Check that the task has not been started (i.e., the backend is free).
check_state(backend$cluster)
#> Task not started: TRUE
#> Task is running: FALSE
#> Task is completed: FALSE

{
    # Run a task in parallel (i.e., approx. 0.25 seconds).
    backend$sapply(
        x = 1:10,
        fun = function(x) {
            # Sleep a bit.
            Sys.sleep(0.05)

            # Compute something.
            output <- x + 1

            # Return the result.
            return(output)
        }
    )

    # And immediately check the state to see that the task is running.
    check_state(backend$cluster)
}
#> Task not started: FALSE
#> Task is running: TRUE
#> Task is completed: FALSE

# Sleep for a bit to wait for the task to complete.
Sys.sleep(1)

# Check that the task is completed (i.e., the output needs to be retrieved).
check_state(backend$cluster)
#> Task not started: FALSE
#> Task is running: TRUE
#> Task is completed: FALSE

# Get the output.
output <- backend$get_output(wait = TRUE)

# Check that the task has not been started (i.e., the backend is free again).
check_state(backend$cluster)
#> Task not started: TRUE
#> Task is running: FALSE
#> Task is completed: FALSE

# Stop the backend.
backend$stop()