Data::MessagePack(3pm)User Contributed Perl DocumentatioData::MessagePack(3pm)
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.
ABOUT MESSAGEPACK FORMAT
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
syohex
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
perl v5.36.0 2022-10-20 Data::MessagePack(3pm)
Generated by dwww version 1.15 on Sun Jun 30 10:05:40 CEST 2024.