SessionState

This class holds the state of a background session used by an asynchronous backend (i.e., AsyncBackend). See the Details section for more information.

Details

The session state is useful to check if an asynchronous backend is ready for certain operations. A session can only be in one of the following four states at a time:

• session_is_starting: When TRUE, it indicates that the session is starting.

• session_is_idle: When TRUE, it indicates that the session is idle and ready to execute operations.

• session_is_busy: When TRUE, it indicates that the session is busy (i.e., see the TaskState class for more information about a task's state).

• session_is_finished: When TRUE, it indicates that the session is closed and no longer available for operations.

See also

TaskState, AsyncBackend and ProgressTrackingContext.

Active bindings

session_is_starting

A logical value indicating whether the session is starting.

session_is_idle

A logical value indicating whether the session is idle and ready to execute operations.

session_is_busy

A logical value indicating whether the session is busy.

session_is_finished

A logical value indicating whether the session is closed and no longer available for operations.

Methods

Public methods

• SessionState$new()

• SessionState$clone()

---

Method new()

Create a new SessionState object and determine the state of a given background session.

Usage

SessionState$new(session)

Arguments

session

A callr::r_session object.

Returns

An object of class SessionState.

---

Method clone()

The objects of this class are cloneable with this method.

Usage

SessionState$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

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

    # Print the state.
    cat(
        "Session is starting: ", session_state$session_is_starting, "\n",
        "Session is idle: ", session_state$session_is_idle, "\n",
        "Session is busy: ", session_state$session_is_busy, "\n",
        "Session is finished: ", session_state$session_is_finished, "\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 session is idle.
check_state(backend$cluster)
#> Session is starting: FALSE
#> Session is idle: TRUE
#> Session is busy: FALSE
#> Session is finished: 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 that the session is busy.
    check_state(backend$cluster)
}
#> Session is starting: FALSE
#> Session is idle: FALSE
#> Session is busy: TRUE
#> Session is finished: FALSE

# Get the output and wait for the task to complete.
output <- backend$get_output(wait = TRUE)

# Check that the session is idle again.
check_state(backend$cluster)
#> Session is starting: FALSE
#> Session is idle: TRUE
#> Session is busy: FALSE
#> Session is finished: FALSE

# Manually close the session.
backend$cluster$close()

# Check that the session is finished.
check_state(backend$cluster)
#> Session is starting: FALSE
#> Session is idle: FALSE
#> Session is busy: FALSE
#> Session is finished: TRUE

# Stop the backend.
backend$stop()