|
| 1 | +% File src/library/parallel/man/sendData.Rd |
| 2 | +% Part of the R package, https://www.R-project.org |
| 3 | +% Copyright 2003-2025 R Core Team |
| 4 | +% Distributed under GPL 2 or later |
| 5 | + |
| 6 | +\name{sendData} |
| 7 | +\alias{closeNode} |
| 8 | +\alias{recvData} |
| 9 | +\alias{recvOneData} |
| 10 | +\alias{sendData} |
| 11 | +\title{Cluster Back-end Interface} |
| 12 | +\description{ |
| 13 | + The communication primitives used by the \pkg{parallel} package to |
| 14 | + handle the state and communicate with nodes in the clusters. |
| 15 | +} |
| 16 | +\usage{ |
| 17 | + sendData(node, data) |
| 18 | + recvData(node) |
| 19 | + recvOneData(cl) |
| 20 | + closeNode(node) |
| 21 | +} |
| 22 | +\arguments{ |
| 23 | + \item{cl}{ |
| 24 | + The cluster object, visible to the user. Should be a list inheriting |
| 25 | + from class \code{cluster}, containing the node objects. |
| 26 | + } |
| 27 | + \item{node}{ |
| 28 | + The node object corresponding to one execution unit inside the |
| 29 | + cluster. |
| 30 | + } |
| 31 | + \item{data}{ |
| 32 | + The data structure containing a message to the node. |
| 33 | + } |
| 34 | +} |
| 35 | +\details{ |
| 36 | + A \code{`[.cluster`} method is provided, which retains the classes of the |
| 37 | + cluster when subset. The cluster back-end should either rely on this method or |
| 38 | + supply its own method that also invokes this method through \code{NextMethod} |
| 39 | + or calls \code{.subset} directly. |
| 40 | + |
| 41 | + The \code{data} messages sent to the nodes are lists containing the |
| 42 | + following elements: \describe{ |
| 43 | + \item{type}{ |
| 44 | + A short string describing the type of packet: \describe{ |
| 45 | + \item{DONE}{ |
| 46 | + Sent by the default \code{stopCluster} implementation before |
| 47 | + calling \code{closeNode}. |
| 48 | + } |
| 49 | + \item{EXEC}{ |
| 50 | + The packet contains a job to execute. |
| 51 | + } |
| 52 | + } |
| 53 | + } |
| 54 | + \item{value}{ |
| 55 | + For messages of type \dQuote{EXEC}, a list with the following |
| 56 | + elements: \describe{ |
| 57 | + \item{fun}{ |
| 58 | + The function to execute. |
| 59 | + } |
| 60 | + \item{args}{ |
| 61 | + The arguments for \code{fun} above as a list. |
| 62 | + } |
| 63 | + \item{return}{ |
| 64 | + Defaults to \code{TRUE}. Not currently used by \pkg{parallel}. |
| 65 | + } |
| 66 | + \item{tag}{ |
| 67 | + The same tag must be returned back from the worker. Used to |
| 68 | + identify individual elements of a larger job when using |
| 69 | + dynamic load balancing. |
| 70 | + } |
| 71 | + } |
| 72 | + } |
| 73 | + } |
| 74 | + |
| 75 | + If the \dQuote{DONE} messages are used (for example when calling |
| 76 | + \code{stopCluster.default}), the node can close the connection upon |
| 77 | + receipt. |
| 78 | + |
| 79 | + The response to an \dQuote{EXEC} message that should be returned by |
| 80 | + \code{recvData} is a list with the following elements: \describe{ |
| 81 | + \item{type}{A string, \code{"VALUE"}.} |
| 82 | + \item{value}{ |
| 83 | + The value of \code{do.call(fun, args, quote = TRUE)}. If the |
| 84 | + evaluation raised an error, the value of the error. |
| 85 | + } |
| 86 | + \item{success}{ |
| 87 | + A logical scalar indicating whether the evaluation completed |
| 88 | + without raising an error. |
| 89 | + } |
| 90 | + \item{time}{ |
| 91 | + The time it took to complete the job, an object of class |
| 92 | + \code{proc_time}. Can be obtained using |
| 93 | + \code{\link[base]{system.time}} or by subtracting outputs of |
| 94 | + \code{\link[base]{proc.time}}. |
| 95 | + } |
| 96 | + \item{tag}{ |
| 97 | + The original \code{tag} from the \dQuote{EXEC} message. |
| 98 | + } |
| 99 | + } |
| 100 | + |
| 101 | + \code{recvData} can block if the job is not yet complete, and |
| 102 | + \code{recvOneData} should block until at least one node is able to |
| 103 | + return a complete job result. |
| 104 | + |
| 105 | + The default \code{closeNode} method does nothing. It is envisaged that |
| 106 | + \code{stopCluster} is used to shut down the entire cluster, although other |
| 107 | + back-ends may use this to implement node-specific logic. |
| 108 | +} |
| 109 | +\value{ |
| 110 | + \item{sendData}{ |
| 111 | + Ignored. Called for the side effect of sending the \code{data} to the |
| 112 | + node. |
| 113 | + } |
| 114 | + \item{recvData}{ |
| 115 | + The result of the job previously submitted to the node. |
| 116 | + } |
| 117 | + \item{recvOneData}{ |
| 118 | + A list with the following items: \describe{ |
| 119 | + \item{node}{The index of the node returning the data.} |
| 120 | + \item{value}{The result of \code{recvData(cluster[[node]])}.} |
| 121 | + } |
| 122 | + } |
| 123 | + \item{closeNode}{ |
| 124 | + Ignored. Called for the side effect of cleaning up the connection to |
| 125 | + the node. |
| 126 | + } |
| 127 | +} |
| 128 | +\seealso{ |
| 129 | + \code{\link{stopCluster}} should also be implemented, but is a user |
| 130 | + interface and documented separately. The default method will post |
| 131 | + termination messages to individual nodes and then call |
| 132 | + \code{closeNode} on them. |
| 133 | +} |
| 134 | +\examples{\dontrun{ |
| 135 | + # A toy cluster consisting of one connection. |
| 136 | + sendData.mynode <- function(node, data) serialize(data, node) |
| 137 | + recvData.mynode <- function(node) unserialize(node) |
| 138 | + recvOneData.mycluster <- function(cl) list( |
| 139 | + node = 1, value = recvData(cl[[1]]) |
| 140 | + ) |
| 141 | + closeNode.mynode <- function(node) close(node) |
| 142 | + |
| 143 | + # Not shown: R starting a serverSocket on the other end, ready to |
| 144 | + # accept connections and evaluate jobs |
| 145 | + cl <- structure(list( |
| 146 | + structure( |
| 147 | + socketConnection(..., blocking = TRUE, open = 'a+b'), |
| 148 | + class = 'mynode' |
| 149 | + ) |
| 150 | + ), class = c('mycluster', 'cluster')) |
| 151 | + clusterEvalQ(cl, Sys.getpid()) |
| 152 | + stopCluster(cl) |
| 153 | + rm(cl) |
| 154 | +}} |
| 155 | +\keyword{internal} |
0 commit comments