GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Data::MessagePack(3) User Contributed Perl Documentation Data::MessagePack(3)

Data::MessagePack - MessagePack serializing/deserializing

    use Data::MessagePack;

    my $mp = Data::MessagePack->new();
    $mp->canonical->utf8->prefer_integer if $needed;

    my $packed   = $mp->pack($dat);
    my $unpacked = $mp->unpack($dat);

This module converts Perl data structures to MessagePack and vice versa.

MessagePack is a binary-based efficient object serialization format. It enables to exchange structured objects between many languages like JSON. But unlike JSON, it is very fast and small.

PORTABLE
The MessagePack format does not depend on language nor byte order.
SMALL IN SIZE
    say length(JSON::XS::encode_json({a=>1, b=>2}));   # => 13
    say length(Storable::nfreeze({a=>1, b=>2}));       # => 21
    say length(Data::MessagePack->pack({a=>1, b=>2})); # => 7
    

The MessagePack format saves memory than JSON and Storable format.

STREAMING DESERIALIZER
MessagePack supports streaming deserializer. It is useful for networking such as RPC. See Data::MessagePack::Unpacker for details.

If you want to get more information about the MessagePack format, please visit to <http://msgpack.org/>.

"my $packed = Data::MessagePack->pack($data[, $max_depth]);"
Pack the $data to messagepack format string.

This method throws an exception when the perl structure is nested more than $max_depth levels(default: 512) in order to detect circular references.

Data::MessagePack->pack() throws an exception when encountering a blessed perl object, because MessagePack is a language-independent format.

"my $unpacked = Data::MessagePack->unpack($msgpackstr);"
unpack the $msgpackstr to a MessagePack format string.
"my $mp = Data::MesssagePack->new()"
Creates a new MessagePack instance.
"$mp = $mp->prefer_integer([ $enable ])"
"$enabled = $mp->get_prefer_integer()"
If $enable is true (or missing), then the "pack" method tries a string as an integer if the string looks like an integer.
"$mp = $mp->canonical([ $enable ])"
"$enabled = $mp->get_canonical()"
If $enable is true (or missing), then the "pack" method will output packed data by sorting their keys. This is adding a comparatively high overhead.
"$mp = $mp->utf8([ $enable ])"
"$enabled = $mp->get_utf8()"
If $enable is true (or missing), then the "pack" method will apply "utf8::encode()" to all the string values.

In other words, this property tell $mp to deal with text strings. See perlunifaq for the meaning of text string.

"$packed = $mp->pack($data)"
"$packed = $mp->encode($data)"
Same as "Data::MessagePack->pack()", but properties are respected.
"$data = $mp->unpack($data)"
"$data = $mp->decode($data)"
Same as "Data::MessagePack->unpack()", but properties are respected.

$Data::MessagePack::PreferInteger
Packs a string as an integer, when it looks like an integer.

This variable is deprecated. Use "$msgpack->prefer_integer" property instead.

This is a result of benchmark/serialize.pl and benchmark/deserialize.pl on my SC440(Linux 2.6.32-23-server #37-Ubuntu SMP). (You should benchmark them with your data if the speed matters, of course.)

    -- serialize
    JSON::XS: 2.3
    Data::MessagePack: 0.24
    Storable: 2.21
    Benchmark: running json, mp, storable for at least 1 CPU seconds...
          json:  1 wallclock secs ( 1.00 usr +  0.01 sys =  1.01 CPU) @ 141939.60/s (n=143359)
            mp:  1 wallclock secs ( 1.06 usr +  0.00 sys =  1.06 CPU) @ 355500.94/s (n=376831)
      storable:  1 wallclock secs ( 1.12 usr +  0.00 sys =  1.12 CPU) @ 38399.11/s (n=43007)
                 Rate storable     json       mp
    storable  38399/s       --     -73%     -89%
    json     141940/s     270%       --     -60%
    mp       355501/s     826%     150%       --

    -- deserialize
    JSON::XS: 2.3
    Data::MessagePack: 0.24
    Storable: 2.21
    Benchmark: running json, mp, storable for at least 1 CPU seconds...
          json:  0 wallclock secs ( 1.05 usr +  0.00 sys =  1.05 CPU) @ 179442.86/s (n=188415)
            mp:  0 wallclock secs ( 1.01 usr +  0.00 sys =  1.01 CPU) @ 212909.90/s (n=215039)
      storable:  2 wallclock secs ( 1.14 usr +  0.00 sys =  1.14 CPU) @ 114974.56/s (n=131071)
                 Rate storable     json       mp
    storable 114975/s       --     -36%     -46%
    json     179443/s      56%       --     -16%
    mp       212910/s      85%      19%       --

This module can unpack 64 bit integers even if your perl does not support them (i.e. where "perl -V:ivsize" is 4), but you cannot calculate these values unless you use "Math::BigInt".

Error handling
MessagePack cannot deal with complex scalars such as object references, filehandles, and code references. We should report the errors more kindly.
Streaming deserializer
The current implementation of the streaming deserializer does not have internal buffers while some other bindings (such as Ruby binding) does. This limitation will astonish those who try to unpack byte streams with an arbitrary buffer size (e.g. "while(read($socket, $buffer, $arbitrary_buffer_size)) { ... }"). We should implement the internal buffer for the unpacker.

Why does Data::MessagePack have pure perl implementations?
msgpack C library uses C99 feature, VC++6 does not support C99. So pure perl version is needed for VC++ users.

Tokuhiro Matsuno

Makamaka Hannyaharamitu

gfx

Jun Kuriyama

Dan Kogai

FURUHASHI Sadayuki

hanekomu

Kazuho Oku

shohex

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

<http://msgpack.org/> is the official web site for the MessagePack format.

Data::MessagePack::Unpacker

AnyEvent::MPRPC

2013-09-01 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.