NAME¶
Data::MessagePack - MessagePack serializing/deserializing
SYNOPSIS¶
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);
DESCRIPTION¶
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.
ADVANTAGES¶
- 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/>.
METHODS¶
- "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.
Configuration Variables (DEPRECATED)¶
- $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.
SPEED¶
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% --
CAVEAT¶
Unpacking 64 bit integers¶
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".
TODO¶
- 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.
FAQ¶
- 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.
AUTHORS¶
Tokuhiro Matsuno
Makamaka Hannyaharamitu
gfx
THANKS TO¶
Jun Kuriyama
Dan Kogai
FURUHASHI Sadayuki
hanekomu
Kazuho Oku
shohex
LICENSE¶
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
SEE ALSO¶
<
http://msgpack.org/> is the official web site for the MessagePack format.
Data::MessagePack::Unpacker
AnyEvent::MPRPC