added bulk of man pages

sequoiar · Sep 29, 2011 · 14bef9b · 14bef9b
1 parent cae7730
commit 14bef9b
Show file tree

Hide file tree

Showing 8 changed files with 167 additions and 279 deletions.
diff --git a/man/bind.socket.Rd b/man/bind.socket.Rd
@@ -1,34 +1,33 @@
 \name{bind.socket}
 \alias{bind.socket}
-%- Also NEED an '\alias' for EACH other topic documented here.
 \title{
-%%  ~~function to do ... ~~
+Create an endpoint for accepting connections and bind it to the socket referenced by the socket argument.
 }
 \description{
-%%  ~~ A concise (1-5 lines) description of what the function does. ~~
+The zmq_bind() function shall create an endpoint for accepting connections and bind it to the socket referenced by the socket argument.
+
+The endpoint argument is a string consisting of two parts as follows: transport ://address. The transport part specifies the underlying transport protocol to use. The meaning of the address part is specific to the underlying transport protocol selected.
+
+The following transports are defined:
+
+inproc
+local in-process (inter-thread) communication transport, see zmq_inproc(7)
+ipc
+local inter-process communication transport, see zmq_ipc(7)
+tcp
+unicast transport using TCP, see zmq_tcp(7)
+pgm, epgm
+reliable multicast transport using PGM, see zmq_pgm(7)
+With the exception of ZMQ_PAIR sockets, a single socket may be connected to multiple endpoints using zmq_connect(), while simultaneously accepting incoming connections from multiple endpoints bound to the socket using zmq_bind(). Refer to zmq_socket(3) for a description of the exact semantics involved when connecting or binding a socket to multiple endpoints.
 }
 \usage{
 bind.socket(socket, address)
 }
-%- maybe also 'usage' for other objects documented here.
 \arguments{
-  \item{socket}{
-%%     ~~Describe \code{socket} here~~
-}
-  \item{address}{
-%%     ~~Describe \code{address} here~~
-}
-}
-\details{
-%%  ~~ If necessary, more details than the description above ~~
-}
-\value{
-%%  ~Describe the value returned
-%%  If it is a LIST, use
-%%  \item{comp1 }{Description of 'comp1'}
-%%  \item{comp2 }{Description of 'comp2'}
-%% ...
+  \item{socket}{a zmq socket object.}
+  \item{address}{a transport as described above.}
 }
+\value{TRUE if operation succeeds or FALSE if the operation fails}
 \references{
 http://www.zeromq.org
 http://api.zeromq.org
@@ -38,26 +37,20 @@ http://zguide.zeromq.org/page:all
 ZMQ was written by Martin Sustrik <sustrik@250bpm.com> and Martin Lucina <mato@kotelna.sk>.
 rzmq was written by Whit Armstrong.
 }
-\note{
-%%  ~~further notes~~
-}
 
-%% ~Make other sections like Warning with \section{Warning }{....} ~
 
 \seealso{
-%% ~~objects to See Also as \code{\link{help}}, ~~~
-}
-\examples{
-##---- Should be DIRECTLY executable !! ----
-##-- ==>  Define data, use random,
-##--	or do  help(data=index)  for the standard data sets.
-
-## The function is currently defined as
-function (socket, address) 
-{
-    .Call("bindSocket", socket, address, PACKAGE = "rzmq")
-  }
+  \code{\link{connect.socket},\link{bind.socket},\link{receive.socket},\link{send.socket}}
 }
-% Add one or more standard keywords, see file 'KEYWORDS' in the
-% R documentation directory.
+\examples{\dontrun{
+
+library(rzmq)
+context = init.context()
+in.socket = init.socket(context,"ZMQ_PULL")
+bind.socket(in.socket,"tcp://*:5557")
+
+out.socket = init.socket(context,"ZMQ_PUSH")
+bind.socket(out.socket,"tcp://*:5558")
+}}
+
 \keyword{utilities}
diff --git a/man/connect.socket.Rd b/man/connect.socket.Rd
@@ -1,34 +1,34 @@
 \name{connect.socket}
 \alias{connect.socket}
-%- Also NEED an '\alias' for EACH other topic documented here.
 \title{
-%%  ~~function to do ... ~~
+Connect the socket referenced by the socket argument to the endpoint specified by the endpoint argument.
 }
 \description{
-%%  ~~ A concise (1-5 lines) description of what the function does. ~~
+  The zmq_connect() function shall connect the socket referenced by the socket argument to the endpoint specified by the endpoint argument.
+
+The endpoint argument is a string consisting of two parts as follows: transport ://address. The transport part specifies the underlying transport protocol to use. The meaning of the address part is specific to the underlying transport protocol selected.
+
+The following transports are defined:
+
+inproc
+local in-process (inter-thread) communication transport, see zmq_inproc(7)
+ipc
+local inter-process communication transport, see zmq_ipc(7)
+tcp
+unicast transport using TCP, see zmq_tcp(7)
+pgm, epgm
+reliable multicast transport using PGM, see zmq_pgm(7)
+With the exception of ZMQ_PAIR sockets, a single socket may be connected to multiple endpoints using zmq_connect(), while simultaneously accepting incoming connections from multiple endpoints bound to the socket using zmq_bind(). Refer to zmq_socket(3) for a description of the exact semantics involved when connecting or binding a socket to multiple endpoints.
 }
 \usage{
 connect.socket(socket, address)
 }
-%- maybe also 'usage' for other objects documented here.
+
 \arguments{
-  \item{socket}{
-%%     ~~Describe \code{socket} here~~
-}
-  \item{address}{
-%%     ~~Describe \code{address} here~~
-}
-}
-\details{
-%%  ~~ If necessary, more details than the description above ~~
-}
-\value{
-%%  ~Describe the value returned
-%%  If it is a LIST, use
-%%  \item{comp1 }{Description of 'comp1'}
-%%  \item{comp2 }{Description of 'comp2'}
-%% ...
+  \item{socket}{a zmq socket object.}
+  \item{address}{a transport as described above.}
 }
+\value{TRUE if operation succeeds or FALSE if the operation fails}
 \references{
 http://www.zeromq.org
 http://api.zeromq.org
@@ -38,26 +38,16 @@ http://zguide.zeromq.org/page:all
 ZMQ was written by Martin Sustrik <sustrik@250bpm.com> and Martin Lucina <mato@kotelna.sk>.
 rzmq was written by Whit Armstrong.
 }
-\note{
-%%  ~~further notes~~
-}
-
-%% ~Make other sections like Warning with \section{Warning }{....} ~
-
 \seealso{
-%% ~~objects to See Also as \code{\link{help}}, ~~~
+  \code{\link{connect.socket},\link{bind.socket},\link{receive.socket},\link{send.socket}}
 }
-\examples{
-##---- Should be DIRECTLY executable !! ----
-##-- ==>  Define data, use random,
-##--	or do  help(data=index)  for the standard data sets.
+\examples{\dontrun{
+library(rzmq)
+context = init.context()
+in.socket = init.socket(context,"ZMQ_PULL")
+bind.socket(in.socket,"tcp://*:5557")
 
-## The function is currently defined as
-function (socket, address) 
-{
-    .Call("connectSocket", socket, address, PACKAGE = "rzmq")
-  }
-}
-% Add one or more standard keywords, see file 'KEYWORDS' in the
-% R documentation directory.
+out.socket = init.socket(context,"ZMQ_PUSH")
+bind.socket(out.socket,"tcp://*:5558")
+}}
 \keyword{utilities}
diff --git a/man/create.sink.Rd b/man/create.sink.Rd
@@ -1,33 +1,27 @@
 \name{create.sink}
 \alias{create.sink}
-%- Also NEED an '\alias' for EACH other topic documented here.
+\alias{get.sink.results}
 \title{
-%%  ~~function to do ... ~~
+  create a sink object.
 }
 \description{
-%%  ~~ A concise (1-5 lines) description of what the function does. ~~
+  Create a sink object in a separate thread which acts as an async
+  reciever for remotely executed jobs.
+
+  The job results can be later retreived via get.sink.results.
 }
 \usage{
 create.sink(address, num_items)
+get.sink.results(sink)
 }
 %- maybe also 'usage' for other objects documented here.
 \arguments{
-  \item{address}{
-%%     ~~Describe \code{address} here~~
-}
-  \item{num_items}{
-%%     ~~Describe \code{num_items} here~~
-}
-}
-\details{
-%%  ~~ If necessary, more details than the description above ~~
+  \item{address}{the transport endpoint for the remote sink server.}
+  \item{num_items}{the number of items to indicate the remote job has completed.}
 }
 \value{
-%%  ~Describe the value returned
-%%  If it is a LIST, use
-%%  \item{comp1 }{Description of 'comp1'}
-%%  \item{comp2 }{Description of 'comp2'}
-%% ...
+  create.sink returns a sink object
+  get.sink.results returns a list of the remotely executed jobs
 }
 \references{
 http://www.zeromq.org
@@ -38,26 +32,24 @@ http://zguide.zeromq.org/page:all
 ZMQ was written by Martin Sustrik <sustrik@250bpm.com> and Martin Lucina <mato@kotelna.sk>.
 rzmq was written by Whit Armstrong.
 }
-\note{
-%%  ~~further notes~~
-}
-
-%% ~Make other sections like Warning with \section{Warning }{....} ~
-
 \seealso{
-%% ~~objects to See Also as \code{\link{help}}, ~~~
-}
-\examples{
-##---- Should be DIRECTLY executable !! ----
-##-- ==>  Define data, use random,
-##--	or do  help(data=index)  for the standard data sets.
+  \code{\link{connect.socket},\link{bind.socket},\link{receive.socket},\link{send.socket}}
+}
+\examples{\dontrun{
+## an example in the spirit of lapply
+x <- as.list(1:100)
+context = init.context()
+execution.socket = init.socket(context,"ZMQ_PUSH")
+connect.socket(execution.socket,"tcp://my.remote.server:5557")
+
+## listen for results
+N <- length(x)
+sink <- create.sink("tcp://my.results.server:5558",N)
+for(i in 1:N) {
+remote.exec(execution.socket,FUN,x[[i]])
+}
+ans <- get.sink.results(sink)
+lapply(ans,unserialize)
+}}
 
-## The function is currently defined as
-function (address, num_items) 
-{
-    .Call("createSink", address, as.integer(num_items), PACKAGE = "rzmq")
-  }
-}
-% Add one or more standard keywords, see file 'KEYWORDS' in the
-% R documentation directory.
 \keyword{utilities}
diff --git a/man/get.sink.results.Rd b/man/get.sink.results.Rd
@@ -1,6 +1,5 @@
 \name{get.sink.results}
 \alias{get.sink.results}
-%- Also NEED an '\alias' for EACH other topic documented here.
 \title{
 %%  ~~function to do ... ~~
 }

diff --git a/man/init.context.Rd b/man/init.context.Rd
@@ -1,25 +1,25 @@
 \name{init.context}
 \alias{init.context}
-%- Also NEED an '\alias' for EACH other topic documented here.
+\alias{init.socket}
 \title{
-%%  ~~function to do ... ~~
+initailize zmq context and zmq socket
 }
 \description{
-%%  ~~ A concise (1-5 lines) description of what the function does. ~~
+initailize zmq context and zmq socket for to be used for further zmq operations.
 }
 \usage{
 init.context()
+init.socket(context, socket.type)
 }
-%- maybe also 'usage' for other objects documented here.
-\details{
-%%  ~~ If necessary, more details than the description above ~~
-}
+
+\arguments{
+  \item{context}{returns a zmq context object.}
+  \item{socket.type}{ The ZMQ socket type requested
+    e.g. ZMQ_REQ,ZMQ_REP,ZMQ_PULL,ZMQ_PUSH, etc.}
+
 \value{
-%%  ~Describe the value returned
-%%  If it is a LIST, use
-%%  \item{comp1 }{Description of 'comp1'}
-%%  \item{comp2 }{Description of 'comp2'}
-%% ...
+  \code{init.context} returns a zmq context object.
+  \code{init.socket} returns a zmq socket object.
 }
 \references{
 http://www.zeromq.org
@@ -30,26 +30,15 @@ http://zguide.zeromq.org/page:all
 ZMQ was written by Martin Sustrik <sustrik@250bpm.com> and Martin Lucina <mato@kotelna.sk>.
 rzmq was written by Whit Armstrong.
 }
-\note{
-%%  ~~further notes~~
-}
-
-%% ~Make other sections like Warning with \section{Warning }{....} ~
 
 \seealso{
-%% ~~objects to See Also as \code{\link{help}}, ~~~
+  \code{\link{connect.socket},\link{bind.socket},\link{receive.socket},\link{send.socket}}
 }
-\examples{
-##---- Should be DIRECTLY executable !! ----
-##-- ==>  Define data, use random,
-##--	or do  help(data=index)  for the standard data sets.
 
-## The function is currently defined as
-function () 
-{
-    .Call("initContext", PACKAGE = "rzmq")
-  }
-}
-% Add one or more standard keywords, see file 'KEYWORDS' in the
-% R documentation directory.
+\examples{\dontrun{
+
+library(rzmq)
+context = init.context()
+in.socket = init.socket(context,"ZMQ_PULL")
+}}
 \keyword{utilities}