API Documentation

unpack(bytes, T::Type = Any; strict::Tuple=())

Return unpack(IOBuffer(bytes), T; strict=strict).

unpack(msgpack_byte_stream::IO, T::Type = Any; strict::Tuple=())

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.

The strict keyword argument is a Tuple of DataTypes where each element S must obey msgpack_type(S) === StructType(). unpack will assume that encountered MessagePack Maps to be deserialized to e.g. S will always contain fields that correspond strictly to the fields of S. In other words, the ith key in the Map must correspond to fieldname(S, i), and the ith value must correspond to getfield(::S, i).

See also: pack, construct

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

pack(io::IO, x)

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

See also: unpack

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

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

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

construct(T::Type, args...)

Return an instance of T given args; defaults to T(args...).

This function is meant to be overloaded for types T where msgpack_type(T) === StructType().

This function is called by unpack when deserializing T objects. When called for this purpose, args are field values for the given T instance and are passed in the order specified by fieldname(T, i). If a given field of T wasn't found in the object's MessagePack Map representation, the corresponding value in args will be MsgPack.FieldNotFound().

AbstractMsgPackType

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

The subtypes of AbstractMsgPackType are:

• IntegerType
• NilType
• BooleanType
• FloatType
• StringType
• BinaryType
• ArrayType
• MapType
• ExtensionType
• AnyType
• StructType

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

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

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

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

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

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

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

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

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

AnyType <: AbstractMsgPackType

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

StructType <: AbstractMsgPackType

If msgpack_type(T) is defined to return StructType, T will be (de)serialized as a MessagePack Map type, where each key-value pair corresponds to a field of T.

• T must be an instantiable Julia type that supports fieldcount, fieldtype,

fieldname, and getfield.

• T must support a valid construct definition (supported by default

if T supports e.g. T((getfield(::T, i) for i in 1:fieldcount(T))...))

• pack will always serialize T's fields in the order specified by

fieldname. In other words, it is generally guaranteed that bytes written by pack(x::T) can be unpacked via unpack(bytes, T; strict=(T,)).

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.

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.

struct Extension
    type::Int8
    data::Vector{UInt8}
end

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

See also: extserialize, extdeserialize

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

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