1Data::MessagePack(3pm)User Contributed Perl DocumentationData::MessagePack(3pm)
2
6 Data::MessagePack - MessagePack serializing/deserializing
7
9 use Data::MessagePack;
10 my $mp = Data::MessagePack->new();
12 $mp->canonical->utf8->prefer_integer if $needed;
13 my $packed = $mp->pack($dat);
15 my $unpacked = $mp->unpack($dat);
16
18 This module converts Perl data structures to MessagePack and vice
19 versa.
20
22 MessagePack is a binary-based efficient object serialization format.
23 It enables to exchange structured objects between many languages like
24 JSON. But unlike JSON, it is very fast and small.
25 ADVANTAGES
27 PORTABLE
28 The MessagePack format does not depend on language nor byte order.
29 SMALL IN SIZE
31 say length(JSON::XS::encode_json({a=>1, b=>2})); # => 13
32 say length(Storable::nfreeze({a=>1, b=>2})); # => 21
33 say length(Data::MessagePack->pack({a=>1, b=>2})); # => 7
34 The MessagePack format saves memory than JSON and Storable format.
36 STREAMING DESERIALIZER
38 MessagePack supports streaming deserializer. It is useful for
39 networking such as RPC. See Data::MessagePack::Unpacker for
40 details.
41 If you want to get more information about the MessagePack format,
43 please visit to <http://msgpack.org/>.
44
46 "my $packed = Data::MessagePack->pack($data[, $max_depth]);"
47 Pack the $data to messagepack format string.
48 This method throws an exception when the perl structure is nested
50 more than $max_depth levels(default: 512) in order to detect
51 circular references.
52 Data::MessagePack->pack() throws an exception when encountering a
54 blessed perl object, because MessagePack is a language-independent
55 format.
56 "my $unpacked = Data::MessagePack->unpack($msgpackstr);"
58 unpack the $msgpackstr to a MessagePack format string.
59 "my $mp = Data::MesssagePack->new()"
61 Creates a new MessagePack instance.
62 "$mp = $mp->prefer_integer([ $enable ])"
64 "$enabled = $mp->get_prefer_integer()"
65 If $enable is true (or missing), then the "pack" method tries a
66 string as an integer if the string looks like an integer.
67 "$mp = $mp->canonical([ $enable ])"
69 "$enabled = $mp->get_canonical()"
70 If $enable is true (or missing), then the "pack" method will output
71 packed data by sorting their keys. This is adding a comparatively
72 high overhead.
73 "$mp = $mp->utf8([ $enable ])"
75 "$enabled = $mp->get_utf8()"
76 If $enable is true (or missing), then the "pack" method will apply
77 utf8::encode() to all the string values.
78 In other words, this property tell $mp to deal with text strings.
80 See perlunifaq for the meaning of text string.
81 "$packed = $mp->pack($data)"
83 "$packed = $mp->encode($data)"
84 Same as "Data::MessagePack->pack()", but properties are respected.
85 "$data = $mp->unpack($data)"
87 "$data = $mp->decode($data)"
88 Same as "Data::MessagePack->unpack()", but properties are
89 respected.
90
92 $Data::MessagePack::PreferInteger
93 Packs a string as an integer, when it looks like an integer.
94 This variable is deprecated. Use "$msgpack->prefer_integer"
96 property instead.
97
99 This is a result of benchmark/serialize.pl and benchmark/deserialize.pl
100 on my SC440(Linux 2.6.32-23-server #37-Ubuntu SMP). (You should
101 benchmark them with your data if the speed matters, of course.)
102 -- serialize
104 JSON::XS: 2.3
105 Data::MessagePack: 0.24
106 Storable: 2.21
107 Benchmark: running json, mp, storable for at least 1 CPU seconds...
108 json: 1 wallclock secs ( 1.00 usr + 0.01 sys = 1.01 CPU) @ 141939.60/s (n=143359)
109 mp: 1 wallclock secs ( 1.06 usr + 0.00 sys = 1.06 CPU) @ 355500.94/s (n=376831)
110 storable: 1 wallclock secs ( 1.12 usr + 0.00 sys = 1.12 CPU) @ 38399.11/s (n=43007)
111 Rate storable json mp
112 storable 38399/s -- -73% -89%
113 json 141940/s 270% -- -60%
114 mp 355501/s 826% 150% --
115 -- deserialize
117 JSON::XS: 2.3
118 Data::MessagePack: 0.24
119 Storable: 2.21
120 Benchmark: running json, mp, storable for at least 1 CPU seconds...
121 json: 0 wallclock secs ( 1.05 usr + 0.00 sys = 1.05 CPU) @ 179442.86/s (n=188415)
122 mp: 0 wallclock secs ( 1.01 usr + 0.00 sys = 1.01 CPU) @ 212909.90/s (n=215039)
123 storable: 2 wallclock secs ( 1.14 usr + 0.00 sys = 1.14 CPU) @ 114974.56/s (n=131071)
124 Rate storable json mp
125 storable 114975/s -- -36% -46%
126 json 179443/s 56% -- -16%
127 mp 212910/s 85% 19% --
128
130 Unpacking 64 bit integers
131 This module can unpack 64 bit integers even if your perl does not
132 support them (i.e. where "perl -V:ivsize" is 4), but you cannot
133 calculate these values unless you use "Math::BigInt".
134
136 Error handling
137 MessagePack cannot deal with complex scalars such as object
138 references, filehandles, and code references. We should report the
139 errors more kindly.
140 Streaming deserializer
142 The current implementation of the streaming deserializer does not
143 have internal buffers while some other bindings (such as Ruby
144 binding) does. This limitation will astonish those who try to
145 unpack byte streams with an arbitrary buffer size (e.g.
146 "while(read($socket, $buffer, $arbitrary_buffer_size)) { ... }").
147 We should implement the internal buffer for the unpacker.
148
150 Why does Data::MessagePack have pure perl implementations?
151 msgpack C library uses C99 feature, VC++6 does not support C99. So
152 pure perl version is needed for VC++ users.
153
155 Tokuhiro Matsuno
156 Makamaka Hannyaharamitu
158 gfx
160
162 Jun Kuriyama
163 Dan Kogai
165 FURUHASHI Sadayuki
167 hanekomu
169 Kazuho Oku
171 syohex
173
175 This library is free software; you can redistribute it and/or modify it
176 under the same terms as Perl itself.
177
179 <http://msgpack.org/> is the official web site for the MessagePack
180 format.
181 Data::MessagePack::Unpacker
183 AnyEvent::MPRPC
185perl v5.38.0 2023-07-20 Data::MessagePack(3pm)