Terminate one or more cluster nodes using process signaling

Usage

killNode(x, signal = tools::SIGTERM, ...)

Arguments

x

cluster or cluster node to terminate.

signal

An integer that specifies the signal level to be sent to the parallel R process. It's only tools::SIGINT (2) and tools::SIGTERM (15) that are supported on all operating systems (i.e. Unix, macOS, and MS Windows). All other signals are platform specific, cf. tools::pskill().

With the exception for MS Windows, as explained below, using SIGINT will trigger an R interrupt condition that can be caught with tryCatch() and withCallingHandlers() using an interrupt calling handler.

When using SIGTERM, there will be no interrupt condition signaled, meaning your parallel R code does not have a chance to exit gracefully. Instead, the R process terminates rather abruptly, leaving behind its temporary folder.

Importantly, contrary to Linux and macOS, it is not possible to get a cluster node running on MS Windows to exit gracefully. For example, despite using SIGINT, there is no interrupt condition signaled. As a matter of fact, on MS Windows, SIGINT works identically to SIGTERM, where they both terminate the cluster node abruptly without giving the R process a chance to exit gracefully. This means that R will not clean up after itself, e.g. there its temporary directory will remain also after R terminates.

...

Not used.

Value

TRUE if the signal was successfully applied, FALSE if not, and NA if signaling is not supported on the specific cluster or node. Warning: With R (< 3.5.0), NA is always returned. This is due to a bug in R (< 3.5.0), where the signaling result cannot be trusted.

Details

Note that the preferred way to terminate a cluster is via parallel::stopCluster(), because it terminates the cluster nodes by kindly asking each of them to nicely shut themselves down. Using killNode() is a much more sever approach. It abruptly terminates the underlying R process, possibly without giving the parallel worker a chance to terminate gracefully. For example, it might get terminated in the middle of writing to file. tools::pskill() is used to send the signal to the R process hosting the parallel worker.

If signal = tools::SIGTERM is used and success, this function will also close any existing socket connection to the node, if they exist. Moreover, if the node is running on the local host, this function will also attempt to remove the node's temporary directory, which is done because the node's R process might not have been exited gracefully.

Known limitations

This function works only with cluster nodes of class RichSOCKnode, which were created by makeClusterPSOCK(). It does not work when using parallel::makeCluster() and friends.

Examples

cl <- makeClusterPSOCK(2)
print(isNodeAlive(cl))  ## [1] TRUE TRUE
#> [1] TRUE TRUE

res <- killNode(cl)
print(res)
#> [1] TRUE TRUE

## It might take a moment before the background
## workers are shutdown after having been signaled
Sys.sleep(1.0)

print(isNodeAlive(cl))  ## [1] FALSE FALSE
#> [1] FALSE FALSE