API Documentation

API Documentation

Below is the documentation for all MsgPack API functions. For information on MsgPack, please see the package's README.

Basic Serialization/Deserialization

MsgPack.unpack — Function.
unpack(bytes, T::Type = Any)

Return unpack(IOBuffer(bytes), T).

source
unpack(msgpack_byte_stream::IO, T::Type = Any)

Return the Julia value of type T deserialized from msgpack_byte_stream.

T is assumed to have valid msgpack_type and from_msgpack definitions.

If msgpack_type(T) === AnyType(), unpack will deserialize the next MessagePack object from msgpack_byte_stream into the default Julia representation corresponding to the object's MessagePack type. For details on default Julia representations, see AbstractMsgPackType.

See also: pack

source
MsgPack.pack — Function.
pack(x)

Serialize x to MessagePack format and return the resulting Vector{UInt8}.

This function uses msgpack_type and to_msgpack to determine the appropriate translation of the value into MessagePack format.

See also: unpack

source
pack(io::IO, x)

Like pack(x), but write the resulting bytes to io. Returns nothing.

See also: unpack

source

Julia <–> MessagePack Conversion

MsgPack.msgpack_type — Function.
msgpack_type(::Type{T}) where {T}

Return an instance of the AbstractMsgPackType subtype corresponding to T's intended MessagePack representation. For example:

msgpack_type(::Type{UUID}) = StringType()

If this method is overloaded such that msgpack_type(T) === M(), then to_msgpack(::M, ::T) and from_msgpack(::Type{T}, x) should also be overloaded to handle conversion of T instances to/from MsgPack-compatible types.

By default, this method returns AnyType(). While this fallback method need not be overloaded to support deserialization of T instances via unpack, msgpack_type(T) must be overloaded to return a non-AnyType AbstractMsgPackType instance in order to support serializing T instances via pack.

See also: from_msgpack, to_msgpack

source
MsgPack.to_msgpack — Function.
to_msgpack(::M, value_to_serialize::T) where {M<:AbstractMsgPackType,T}

Return an "M-compatible" representation of value_to_serialize (for compatibility definitions, see the docstrings for subtypes of AbstractMsgPackType).

By default, to_msgpack simply returns value_to_serialize directly.

The implementation of pack utilizes this function for every value encountered during serialization, calling it in a manner similar to the following psuedocode:

t = msgpack_type(T)
value_in_compatible_representation = to_msgpack(t, value_to_serialize::T)
_serialize_in_msgpack_format(t, value_in_compatible_representation)

For example, if msgpack_type(UUID) was defined to return StringType(), an appropriate to_msgpack implementation might be:

to_msgpack(::StringType, uuid::UUID) = string(uuid)

See also: from_msgpack, msgpack_type, AbstractMsgPackType

source
MsgPack.from_msgpack — Function.
from_msgpack(::Type{T}, value_deserialized_by_msgpack) where {T}

Return the value_deserialized_by_msgpack converted to type T. By default, this method simply calls convert(T, value_deserialized_by_msgpack).

The implementation of unpack calls this function on every deserialized value; in this case, T is generally derived from the type specified by the caller of unpack.

For example, if msgpack_type(UUID) was defined to return StringType(), an appropriate from_msgpack implementation might be:

from_msgpack(::Type{UUID}, uuid::AbstractString) = UUID(uuid)

See also: to_msgpack, msgpack_type, AbstractMsgPackType

source

Julia <–> MessagePack Interface Types

MsgPack.AbstractMsgPackType — Type.
AbstractMsgPackType

An abstract type whose subtypes define a MessagePack <–> Julia type interface.

The subtypes of AbstractMsgPackType are:

source
MsgPack.IntegerType — Type.
IntegerType <: AbstractMsgPackType

A Julia type corresponding to the MessagePack Integer type.

If msgpack_type(T) is defined to return IntegerType(), then T must support:

  • to_msgpack(::IntegerType, ::T)::S
  • from_msgpack(::Type{T}, ::S)::T
  • standard numeric comparators (>, <, ==, etc.) against values of type S

where S may be one of the following types:

  • UInt8
  • UInt16
  • UInt32
  • UInt64
  • Int8
  • Int16
  • Int32
  • Int64
source
MsgPack.NilType — Type.
NilType <: AbstractMsgPackType

A Julia type corresponding to the MessagePack Nil type.

If msgpack_type(T) is defined to return NilType(), then T must support:

  • from_msgpack(::Type{T}, ::Nothing)::T
source
MsgPack.BooleanType — Type.
BooleanType <: AbstractMsgPackType

A Julia type corresponding to the MessagePack Boolean type.

If msgpack_type(T) is defined to return BooleanType(), then T must support:

  • to_msgpack(::BooleanType, ::T)::Bool
  • from_msgpack(::Type{T}, ::Bool)::T
source
MsgPack.FloatType — Type.
FloatType <: AbstractMsgPackType

A Julia type corresponding to the MessagePack Float type.

If msgpack_type(T) is defined to return FloatType(), then T must support:

  • to_msgpack(::FloatType, ::T)::S
  • from_msgpack(::Type{T}, ::S)::T
  • standard numeric comparators (>, <, ==, etc.) against values of type S

where S may be one of the following types:

  • Float32
  • Float64
source
MsgPack.StringType — Type.
StringType <: AbstractMsgPackType

A Julia type corresponding to the MessagePack String type.

If msgpack_type(T) is defined to return StringType(), then T must support:

  • to_msgpack(::StringType, ::T)::String
  • from_msgpack(::Type{T}, ::String)::T
source
MsgPack.BinaryType — Type.
BinaryType <: AbstractMsgPackType

A Julia type corresponding to the MessagePack Binary type.

If msgpack_type(T) is defined to return BinaryType(), then T must support:

  • to_msgpack(::BinaryType, ::T)::Vector{UInt8}
  • from_msgpack(::Type{T}, ::Vector{UInt8})::T
source
MsgPack.ArrayType — Type.
ArrayType <: AbstractMsgPackType

A Julia type corresponding to the MessagePack Array type.

If msgpack_type(T) is defined to return ArrayType(), then T must support:

  • length
  • iterate
  • MsgPack._eltype(T) (falls back to eltype(T))

and/or must support:

  • to_msgpack(::ArrayType, ::T)::AbstractArray
  • from_msgpack(::Type{T}, ::Vector)::T
source
MsgPack.MapType — Type.
MapType <: AbstractMsgPackType

A Julia type corresponding to the MessagePack Map type.

If msgpack_type(T) is defined to return MapType(), then T must support:

  • length
  • iterate
  • MsgPack._keytype(T) (falls back to keytype(T))
  • MsgPack._valtype(T) (falls back to valtype(T))

and/or must support:

  • to_msgpack(::ArrayType, ::T)::AbstractDict
  • from_msgpack(::Type{T}, ::Dict)::T
source
MsgPack.ExtensionType — Type.
ExtensionType <: AbstractMsgPackType

A Julia type corresponding to the MessagePack Extension type.

If msgpack_type(T) is defined to return ExtensionType(), then T must support:

  • to_msgpack(::ExtensionType, ::T)::Extension
  • from_msgpack(::Type{T}, ::Extension)::T

See also: Extension

source
MsgPack.AnyType — Type.
AnyType <: AbstractMsgPackType

The fallback return type of msgpack_type(::Type), indicating that the given Julia type does not have a known corresponding MessagePack type.

source
MsgPack.ImmutableStructType — Type.
ImmutableStructType <: AbstractMsgPackType

If msgpack_type(T) is defined to return ImmutableStructType, T will be (de)serialized as a MessagePack Map type assuming certain constraints that enable additional optimizations:

  • T supports fieldcount, fieldtype, fieldname, getfield, and a constructor

that can be called as T((getfield(x::T, i) for i in 1:fieldcount(T))...) for any T instance x.

  • unpack will assume that incoming bytes to be deserialized to T

will always be formmatted as a MessagePack Map whose fields correspond exactly to the fields of T. In other words, the ith key in the Map must correspond to fieldname(T, i), and the ith value must correspond to getfield(::T, i).

This type is similar to MutableStructType, but generally achieves greater (de)serialization performance by imposing tighter constraints.

source
MsgPack.MutableStructType — Type.
MutableStructType <: AbstractMsgPackType

If msgpack_type(T) is defined to return MutableStructType, T will be (de)serialized as a MessagePack Map type assuming certain constraints that enable additional optimizations:

  • T supports fieldcount, fieldtype, fieldname, getfield, setfield!,

and has the inner constructor T() = new().

  • unpack will assume that incoming bytes to be deserialized to T

will always be formmatted as a MessagePack Map whose fields are an unordered subset of the fields of T. If a given field is not present in the MessagePack Map, the corresponding field of the returned T instance will be left uninitialized.

This type is similar to ImmutableStructType, but imposes fewer constraints at the cost of (de)serialization performance.

source

View Types

MsgPack.ArrayView — Type.
ArrayView{T} <: AbstractVector{T}

A Julia struct that wraps a MessagePack byte buffer to provide an immutable view of the MessagePack Array stored within the wrapped byte buffer.

This type is intended to be utilized via unpack. For example, a call to arr = unpack(bytes, ArrayView{Dict{String,Int32}}) will generally return a value more quickly than arr = unpack(bytes, Vector{Dict{String,Int32}}); the latter will perform full deserialization immediately while the former will only scan over bytes to tag the positions of arr's elements, deferring the actual deserialization of these elements to the time of their access via arr[index].

Note that ArrayView does not implement any form of caching - repeat accesses of the same element will re-deserialize the element upon every access.

source
MsgPack.MapView — Type.
MapView{K,V} <: AbstractDict{K,V}

Similar to ArrayView, but provides an immutable view to a MessagePack Map rather than a MessagePack Array.

This type is intended to be utilized via unpack in the same manner as ArrayView, and is similarly implements a "delay-deserialization-until-access" mechanism.

source

MessagePack Extension Functionality

MsgPack.Extension — Type.
struct Extension
    type::Int8
    data::Vector{UInt8}
end

A wrapper for bytes formatted to the MessagePack Extension type specification.

See also: extserialize, extdeserialize

source
MsgPack.extserialize — Function.
extserialize(type, x)

Return Extension(type, data) where data is the result of calling Julia's built-in serialize function on x, facilitating direct serialization Julia values to MessagePack format:

julia> struct Point{T}
           x::T
           y::T
       end

julia> val = [Point(rand(), rand()) for _ in 1:100];

julia> bytes = MsgPack.pack(MsgPack.extserialize(123, x));

julia> type, new_val = MsgPack.extdeserialize(MsgPack.unpack(bytes));

julia> type == 123
true

julia> new_val == val
true

Note that extserialize/extdeserialize are subject to the same caveat as Julia's built-in serialize/deserialize functions: "In general, this process will not work if the reading and writing are done by different versions of Julia, or an instance of Julia with a different system image.".

See also: Extension, extdeserialize

source
MsgPack.extdeserialize — Function.
extdeserialize(x::Extension)

Return (x.type, value) where value is the result of calling Julia's built-in deserialize function on x.data.

This function is meant to be used in conjuction with extserialize; see that function's docstring for more details.

See also: Extension, extserialize

source