msgpack (version 1.0)

msgConnection: Read and write msgpack formatted messages over R connections.

Description

A msgConnection object decodes msgpack messages from an underlying R raw connection.

readMsg(con) reads exactly one message from a msgConnection, or throws an error.

writeMsg(x, con) writes a single message to a msgConnection.

writeMsg will work with any R connection in raw mode, but reading requires a msgConnection object.

Usage

msgConnection(con, read_size = 2^16, max_size = NA, ...)
# S3 method for msgConnection
close(con, ...)
partial(con)
# S3 method for msgConnection
partial(con)
readMsgs(con, n = NA, ...)
status(con)
# S3 method for msgConnection
status(con)
# S3 method for msgConnection
seek(con, rw = summary(con)$mode, ...)
readMsg(con, ...)
writeMsg(obj, con, ...)
writeMsgs(objs, con, ...)

Arguments

con

A connection object open in binary mode.

read_size

How many bytes to read at a time.

max_size

The largest partial message to store, in bytes. NA means do not enforce a limit.

...

Unpacking options (see unpackMsg).

n

The maximum number of messages to read. A value of NA means to parse all available messages until end of input.

rw

See seek().

obj

An R object.

objs

A list of R objects.

Value

msgConnection() returns an object of class msgConnection.

partial(con) returns any data that has been read ahead of the last decoded message.

readMsgs(con, n) returns a list of up to n decoded messages.

status(con) returns the status of msgpack decoding on the connection. A value of "ok" indicates all requested messages were read, "buffer underflow" for a non-blocking connection indicates that only part of a message has been received, and "end of input" means the last available message has been read. Other values indicate errors encountered in decoding, which will effectively halt reading.

seek(con) returns the number of bytes that have been successfully read or written, depending on the mode of the connection. (Repositioning is not supported.)

readMsg(con) returns one decoded message.

Details

Because msgpack messages have unpredictable length, the decoder reads ahead in chunks, then finds the boundaries between messages. Therefore when reading over a socket or a fifo it is best to use a nonblocking connection, and it will not work to mix readMsg and readBin on the same connection.

If you are reading data from a not completely trusted source you should specify options max_size and max_depth (see unpackOpts). Without it, some deeply nested or cleverly designed messages can cause a stack overflow or out-of-memory error. With these options set, you will get an R exception instead.

Examples

# NOT RUN {
out <- rawConnection(raw(0), open="wb")
apply(quakes, 1, function(x) writeMsg(x, out))
length(rawConnectionValue(out))
inn <- msgConnection(rawConnection(rawConnectionValue(out), open="rb"))
readMsg(inn)
readMsgs(inn, 3)
# }