Data::MessagePack(3pm)

1Data::MessagePack(3)  User Contributed Perl Documentation Data::MessagePack(3)
2
3
4

NAME

6       Data::MessagePack - MessagePack serializing/deserializing
7

SYNOPSIS

9           use Data::MessagePack;
10
11           my $mp = Data::MessagePack->new();
12           $mp->canonical->utf8->prefer_integer if $needed;
13
14           my $packed   = $mp->pack($dat);
15           my $unpacked = $mp->unpack($dat);
16

DESCRIPTION

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

ABOUT MESSAGEPACK FORMAT

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
26   ADVANTAGES
27       PORTABLE
28           The MessagePack format does not depend on language nor byte order.
29
30       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
35           The MessagePack format saves memory than JSON and Storable format.
36
37       STREAMING DESERIALIZER
38           MessagePack supports streaming deserializer. It is useful for
39           networking such as RPC.  See Data::MessagePack::Unpacker for
40           details.
41
42       If you want to get more information about the MessagePack format,
43       please visit to <http://msgpack.org/>.
44

METHODS

46       "my $packed = Data::MessagePack->pack($data[, $max_depth]);"
47           Pack the $data to messagepack format string.
48
49           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
53           Data::MessagePack->pack() throws an exception when encountering a
54           blessed perl object, because MessagePack is a language-independent
55           format.
56
57       "my $unpacked = Data::MessagePack->unpack($msgpackstr);"
58           unpack the $msgpackstr to a MessagePack format string.
59
60       "my $mp = Data::MesssagePack->new()"
61           Creates a new MessagePack instance.
62
63       "$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
68       "$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
74       "$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
79           In other words, this property tell $mp to deal with text strings.
80           See perlunifaq for the meaning of text string.
81
82       "$packed = $mp->pack($data)"
83       "$packed = $mp->encode($data)"
84           Same as "Data::MessagePack->pack()", but properties are respected.
85
86       "$data = $mp->unpack($data)"
87       "$data = $mp->decode($data)"
88           Same as "Data::MessagePack->unpack()", but properties are
89           respected.
90

Configuration Variables (DEPRECATED)

92       $Data::MessagePack::PreferInteger
93           Packs a string as an integer, when it looks like an integer.
94
95           This variable is deprecated.  Use "$msgpack->prefer_integer"
96           property instead.
97

SPEED

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
103           -- 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
116           -- 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

CAVEAT

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

TODO

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
141       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

FAQ

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

AUTHORS

155       Tokuhiro Matsuno
156
157       Makamaka Hannyaharamitu
158
159       gfx
160

THANKS TO

162       Jun Kuriyama
163
164       Dan Kogai
165
166       FURUHASHI Sadayuki
167
168       hanekomu
169
170       Kazuho Oku
171
172       syohex
173

LICENSE

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