File: killNode.Rd

package info (click to toggle)
r-cran-parallelly 1.42.0-1
  • links: PTS, VCS
  • area: main
  • in suites: forky, sid, trixie
  • size: 1,216 kB
  • sloc: ansic: 111; sh: 13; makefile: 2
file content (71 lines) | stat: -rw-r--r-- 2,625 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/killNode.R
\name{killNode}
\alias{killNode}
\title{Terminate one or more cluster nodes using process signaling}
\usage{
killNode(x, signal = tools::SIGTERM, ...)
}
\arguments{
\item{x}{cluster or cluster node to terminate.}

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

\item{\ldots}{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.
\emph{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.
}
\description{
Terminate one or more cluster nodes using process signaling
}
\details{
Note that the preferred way to terminate a cluster is via
\code{\link[parallel:makeCluster]{parallel::stopCluster()}}, because it terminates the cluster nodes
by kindly asking each of them to nicely shut themselves down.
Using \code{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.

\code{\link[tools:pskill]{tools::pskill()}} is used to send the signal to the R process hosting
the parallel worker.
}
\section{Known limitations}{

This function works only with cluster nodes of class \code{RichSOCKnode},
which were created by \code{\link[=makeClusterPSOCK]{makeClusterPSOCK()}}.  It does not work when
using \code{\link[parallel:makeCluster]{parallel::makeCluster()}} and friends.

Currently, it's only possible to send signals to parallel workers, that
is, cluster nodes, that run on the local machine.
If attempted to use \code{killNode()} on a remote parallel workers, \code{NA}
is returned and an informative warning is produced.
}

\examples{
\dontshow{if (.Platform$OS.type != "windows" || interactive()) \{}
cl <- makeClusterPSOCK(2)
print(isNodeAlive(cl))  ## [1] TRUE TRUE

res <- killNode(cl)
print(res)

## 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
\dontshow{\}}

}
\seealso{
Use \code{\link[=isNodeAlive]{isNodeAlive()}} to check whether one or more cluster nodes are alive.
}