1Sereal::Performance(3)User Contributed Perl DocumentationSereal::Performance(3)
2
3
4

NAME

6       Sereal::Performance - Getting the most out of the Perl-Sereal
7       implementation
8

SYNOPSIS

10         # This is different from the standard module synopsis in
11         # that it chooses performance over ease-of-use.
12         # Think twice before micro-optimizing your Sereal usage.
13         # Usually, Sereal is a lot faster than most of one's code,
14         # so unless you are doing bulk encoding/decoding, you are
15         # better off optimizing for maintainability.
16
17         use Sereal qw(sereal_encode_with_object
18                       sereal_decode_with_object);
19         my $enc = Sereal::Encoder->new();
20         my $dec = Sereal::Decoder->new();
21
22         my $big_data_structure = {...};
23
24         my $srldoc = sereal_encode_with_object($enc, $big_data_structure);
25
26         my $and_back = sereal_decode_with_object($dec, $srldoc);
27

DESCRIPTION

29       Using Sereal in the way that is optimally performant for your use case
30       can make quite a significant difference in performance. Broadly
31       speaking, there are two classes of tweaks you can do: choosing the
32       right options during encoding (sometimes incurring trade-offs in output
33       size) and calling the Sereal encode/decode functions in the most
34       efficient way.
35
36       If you are not yet using re-usable Sereal::Encoder and Sereal::Decoder
37       objects, then read no further. By switching from the "encode_sereal"
38       and "decode_sereal" functions to either the OO interface or the
39       advanced functional interface, you will get a noticeable speed boost as
40       encoder and decoder structures can be reused.  This is particularly
41       significant for the encoder, which can re-use its output buffer. In
42       some cases, such a warmed-up encoder can avoid most memory allocations.
43
44       I repeat, if you care about performance, then do not use the
45       "encode_sereal" and "decode_sereal" interface.
46
47       The exact performance in time and space depends heavily on the data
48       structure to be (de-)serialized. Often there is a trade-off between
49       space and time. If in doubt, do your own testing and most importantly
50       ALWAYS TEST WITH REAL DATA. If you care purely about speed at the
51       expense of output size, you can use the "no_shared_hashkeys" option for
52       a small speed-up, see below.  If you need smaller output at the cost of
53       higher CPU load and more memory used during encoding/decoding, try the
54       "dedupe_strings" option and enable Snappy compression.
55
56       For ready-made comparison scripts, see the author_tools/bench.pl and
57       author_tools/dbench.pl programs that are part of this distribution.
58       Suffice to say that this library is easily competitive in both time and
59       space efficiency with the best alternatives.
60
61       If switching to the OO interface is not enough, you may consider
62       switching to the advanced functional interface that avoids method
63       lookup overhead, and by inlining as custom Perl OPs, may also avoid
64       some of the Perl function call overhead (Perl 5.14 and up). This
65       additional speed-up is only a constant-offset, avoiding said
66       method/function call, rather than speeding up encoding itself and so
67       will be most significant if you are working with very small data sets.
68
69       "sereal_encode_with_object" and "sereal_decode_with_object" are
70       optionally exported from the Sereal module (or "Sereal::Encoder" and
71       "Sereal::Decoder" respectively).  They work the same as the object-
72       oriented interface except that they are invoked differently:
73
74         $srl_doc = $encoder->encode($data);
75
76       becomes
77
78         $srl_doc = sereal_encode_with_object($encoder, $data);
79
80       and
81
82         $data = $decoder->decode($srl_doc);
83
84       becomes
85
86         $data = sereal_decode_with_object($decoder, $srl_doc);
87
88       On Perl versions before 5.14, this will be marginally faster than the
89       OO interface as it avoids method lookup. This should rarely matter.  On
90       Perl versions starting from 5.14, the function call to
91       "sereal_encode_with_object" or "sereal_decode_with_object" will also be
92       replaced with a custom Perl OP, thus avoiding most of the function call
93       overhead as well.
94
95   Tuning the "Sereal::Encoder"
96       Several of the "Sereal::Encoder" options add or remove useful behaviour
97       and some of them come at a runtime performance cost.
98
99       "no_shared_hashkeys"
100         By default, Sereal will emit a "repetition" marker for hash keys that
101         were already previously encountered. Depending on your data
102         structure, this can save quite a bit of space in the generated
103         document. Consider, for example, encoding an array of many objects of
104         the same class. But it may not save anything if you don't have a lot
105         of repeated hash keys or don't even encode any hashes to begin with.
106
107         In those cases, you can turn this feature off with the
108         "no_shared_hashkeys" option for a small but measurable speed-up.
109
110       "dedupe_strings"
111         If set, this option will apply the de-duplication logic to all
112         strings that is only applied to hash keys by default. This can be
113         quite expensive in both memory and performance.  The same is true for
114         "aliased_dedupe_strings".
115
116       "snappy" and "snappy_incr"
117         Enabling Snappy compression can (but doesn't have to) make your
118         Sereal documents significantly smaller. How effective this
119         compression is for you depends entirely on the nature of your data.
120         Snappy compression is designed to be very fast. The additional space
121         savings are very often worth the small overhead.
122
123       "freeze_callbacks"
124         Using custom Perl "FREEZE" callbacks is very expensive. If enabled,
125         the encoder has to do a method lookup at least once per class of an
126         object being serialized. If a "FREEZE" hook actually exists, calling
127         it will be even more expensive. If you care about ultimate
128         performance, use with care.
129
130       "sort_keys"
131         This option forces the encoder to always "sort" the entries in a hash
132         by its keys before writing them to the Sereal document. This can be
133         somewhat expensive for large hashes.
134
135   General Considerations
136       Perl variables (scalars specifically) can, at the same time, hold
137       multiple representations of the same data. If you create and integer
138       and use it as a string, it will be cached in its string form. Sereal
139       attempts to detect the most compact of these representations for
140       encoding, but can not always succeed. For example, if a data structure
141       was previously also traversed by certain other serialization modules
142       (such as Storable), then the scalars in the structure may have been
143       irrevocably upgraded to a more complex (and bigger) type. This is only
144       an issue in crude benchmarks.  So if you plan to benchmark
145       serialization, take care not to re-use the test data structure between
146       serializers for results that do not depend on the order of operations.
147

BUGS, CONTACT AND SUPPORT

149       For reporting bugs, please use the github bug tracker at
150       <http://github.com/Sereal/Sereal/issues>.
151
152       For support and discussion of Sereal, there are two Google Groups:
153
154       Announcements around Sereal (extremely low volume):
155       <https://groups.google.com/forum/?fromgroups#!forum/sereal-announce>
156
157       Sereal development list:
158       <https://groups.google.com/forum/?fromgroups#!forum/sereal-dev>
159

AUTHORS AND CONTRIBUTORS

161       Yves Orton <demerphq@gmail.com>
162
163       Damian Gryski
164
165       Steffen Mueller <smueller@cpan.org>
166
167       Rafaël Garcia-Suarez
168
169       Ævar Arnfjörð Bjarmason <avar@cpan.org>
170
171       Tim Bunce
172
173       Daniel Dragan <bulkdd@cpan.org> (Windows support and bugfixes)
174
175       Zefram
176
177       Some inspiration and code was taken from Marc Lehmann's excellent
178       JSON::XS module due to obvious overlap in problem domain.
179

ACKNOWLEDGMENT

181       This module was originally developed for Booking.com.  With approval
182       from Booking.com, this module was generalized and published on CPAN,
183       for which the authors would like to express their gratitude.
184
186       Copyright (C) 2012, 2013, 2014 by Steffen Mueller Copyright (C) 2012,
187       2013, 2014 by Yves Orton
188
189       The license for the code in this distribution is the following, with
190       the exceptions listed below:
191
192       This library is free software; you can redistribute it and/or modify it
193       under the same terms as Perl itself.
194
195       Except portions taken from Marc Lehmann's code for the JSON::XS module,
196       which is licensed under the same terms as this module.  (Many thanks to
197       Marc for inspiration, and code.)
198
199       Also except the code for Snappy compression library, whose license is
200       reproduced below and which, to the best of our knowledge, is compatible
201       with this module's license. The license for the enclosed Snappy code
202       is:
203
204         Copyright 2011, Google Inc.
205         All rights reserved.
206
207         Redistribution and use in source and binary forms, with or without
208         modification, are permitted provided that the following conditions are
209         met:
210
211           * Redistributions of source code must retain the above copyright
212         notice, this list of conditions and the following disclaimer.
213           * Redistributions in binary form must reproduce the above
214         copyright notice, this list of conditions and the following disclaimer
215         in the documentation and/or other materials provided with the
216         distribution.
217           * Neither the name of Google Inc. nor the names of its
218         contributors may be used to endorse or promote products derived from
219         this software without specific prior written permission.
220
221         THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
222         "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
223         LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
224         A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
225         OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
226         SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
227         LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
228         DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
229         THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
230         (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
231         OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
232
233
234
235perl v5.34.0                      2022-02-20            Sereal::Performance(3)
Impressum