ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/CBOR-XS/XS.pm
(Generate patch)

Comparing CBOR-XS/XS.pm (file contents):
Revision 1.23 by root, Fri Nov 22 16:00:30 2013 UTC vs.
Revision 1.31 by root, Sat Nov 30 18:13:53 2013 UTC

… …
26 substr $many_cbor_strings, 0, $length, ""; # remove decoded cbor string 26 substr $many_cbor_strings, 0, $length, ""; # remove decoded cbor string
27 } 27 }
28 28
29=head1 DESCRIPTION 29=head1 DESCRIPTION
30 30
31WARNING! This module is very new, and not very well tested (that's up
32to you to do). Furthermore, details of the implementation might change
33freely before version 1.0. And lastly, most extensions depend on an IANA
34assignment, and until that assignment is official, this implementation is
35not interoperable with other implementations (even future versions of this
36module) until the assignment is done.
37
38You are still invited to try out CBOR, and this module.
39
40This module converts Perl data structures to the Concise Binary Object 31This module converts Perl data structures to the Concise Binary Object
41Representation (CBOR) and vice versa. CBOR is a fast binary serialisation 32Representation (CBOR) and vice versa. CBOR is a fast binary serialisation
42format that aims to use a superset of the JSON data model, i.e. when you 33format that aims to use an (almost) superset of the JSON data model, i.e.
43can represent something in JSON, you should be able to represent it in 34when you can represent something useful in JSON, you should be able to
44CBOR. 35represent it in CBOR.
45 36
46In short, CBOR is a faster and very compact binary alternative to JSON, 37In short, CBOR is a faster and quite compact binary alternative to JSON,
47with the added ability of supporting serialisation of Perl objects. (JSON 38with the added ability of supporting serialisation of Perl objects. (JSON
48often compresses better than CBOR though, so if you plan to compress the 39often compresses better than CBOR though, so if you plan to compress the
49data later you might want to compare both formats first). 40data later and speed is less important you might want to compare both
41formats first).
50 42
51To give you a general idea about speed, with texts in the megabyte range, 43To give you a general idea about speed, with texts in the megabyte range,
52C<CBOR::XS> usually encodes roughly twice as fast as L<Storable> or 44C<CBOR::XS> usually encodes roughly twice as fast as L<Storable> or
53L<JSON::XS> and decodes about 15%-30% faster than those. The shorter the 45L<JSON::XS> and decodes about 15%-30% faster than those. The shorter the
54data, the worse L<Storable> performs in comparison. 46data, the worse L<Storable> performs in comparison.
55 47
56As for compactness, C<CBOR::XS> encoded data structures are usually about 48Regarding compactness, C<CBOR::XS>-encoded data structures are usually
5720% smaller than the same data encoded as (compact) JSON or L<Storable>. 49about 20% smaller than the same data encoded as (compact) JSON or
50L<Storable>.
58 51
59In addition to the core CBOR data format, this module implements a number 52In addition to the core CBOR data format, this module implements a
60of extensions, to support cyclic and self-referencing data structures 53number of extensions, to support cyclic and shared data structures
61(see C<allow_sharing>), string deduplication (see C<allow_stringref>) and 54(see C<allow_sharing> and C<allow_cycles>), string deduplication (see
62scalar references (always enabled). 55C<pack_strings>) and scalar references (always enabled).
63 56
64The primary goal of this module is to be I<correct> and the secondary goal 57The primary goal of this module is to be I<correct> and the secondary goal
65is to be I<fast>. To reach the latter goal it was written in C. 58is to be I<fast>. To reach the latter goal it was written in C.
66 59
67See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and 60See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and
… …
71 64
72package CBOR::XS; 65package CBOR::XS;
73 66
74use common::sense; 67use common::sense;
75 68
76our $VERSION = 0.08; 69our $VERSION = '1.0';
77our @ISA = qw(Exporter); 70our @ISA = qw(Exporter);
78 71
79our @EXPORT = qw(encode_cbor decode_cbor); 72our @EXPORT = qw(encode_cbor decode_cbor);
80 73
81use Exporter; 74use Exporter;
… …
186as an array, is referenced multiple times), but instead will emit a 179as an array, is referenced multiple times), but instead will emit a
187reference to the earlier value. 180reference to the earlier value.
188 181
189This means that such values will only be encoded once, and will not result 182This means that such values will only be encoded once, and will not result
190in a deep cloning of the value on decode, in decoders supporting the value 183in a deep cloning of the value on decode, in decoders supporting the value
191sharing extension. 184sharing extension. This also makes it possible to encode cyclic data
185structures (which need C<allow_cycles> to ne enabled to be decoded by this
186module).
192 187
193It is recommended to leave it off unless you know your 188It is recommended to leave it off unless you know your
194communication partner supports the value sharing extensions to CBOR 189communication partner supports the value sharing extensions to CBOR
195(http://cbor.schmorp.de/value-sharing). 190(L<http://cbor.schmorp.de/value-sharing>), as without decoder support, the
191resulting data structure might be unusable.
196 192
197Detecting shared values incurs a runtime overhead when values are encoded 193Detecting shared values incurs a runtime overhead when values are encoded
198that have a reference counter large than one, and might unnecessarily 194that have a reference counter large than one, and might unnecessarily
199increase the encoded size, as potentially shared values are encode as 195increase the encoded size, as potentially shared values are encode as
200sharable whether or not they are actually shared. 196shareable whether or not they are actually shared.
201 197
202At the moment, only targets of references can be shared (e.g. scalars, 198At the moment, only targets of references can be shared (e.g. scalars,
203arrays or hashes pointed to by a reference). Weirder constructs, such as 199arrays or hashes pointed to by a reference). Weirder constructs, such as
204an array with multiple "copies" of the I<same> string, which are hard but 200an array with multiple "copies" of the I<same> string, which are hard but
205not impossible to create in Perl, are not supported (this is the same as 201not impossible to create in Perl, are not supported (this is the same as
206for L<Storable>). 202with L<Storable>).
207 203
208If C<$enable> is false (the default), then C<encode> will encode 204If C<$enable> is false (the default), then C<encode> will encode shared
209exception when it encounters anything it cannot encode as CBOR. 205data structures repeatedly, unsharing them in the process. Cyclic data
206structures cannot be encoded in this mode.
210 207
211This option does not affect C<decode> in any way - shared values and 208This option does not affect C<decode> in any way - shared values and
212references will always be decoded properly if present. 209references will always be decoded properly if present.
213 210
211=item $cbor = $cbor->allow_cycles ([$enable])
212
213=item $enabled = $cbor->get_allow_cycles
214
215If C<$enable> is true (or missing), then C<decode> will happily decode
216self-referential (cyclic) data structures. By default these will not be
217decoded, as they need manual cleanup to avoid memory leaks, so code that
218isn't prepared for this will not leak memory.
219
220If C<$enable> is false (the default), then C<decode> will throw an error
221when it encounters a self-referential/cyclic data structure.
222
223This option does not affect C<encode> in any way - shared values and
224references will always be decoded properly if present.
225
214=item $cbor = $cbor->allow_stringref ([$enable]) 226=item $cbor = $cbor->pack_strings ([$enable])
215 227
216=item $enabled = $cbor->get_allow_stringref 228=item $enabled = $cbor->get_pack_strings
217 229
218If C<$enable> is true (or missing), then C<encode> will try not to encode 230If C<$enable> is true (or missing), then C<encode> will try not to encode
219the same string twice, but will instead encode a reference to the string 231the same string twice, but will instead encode a reference to the string
220instead. Depending on your data format. this can save a lot of space, but 232instead. Depending on your data format, this can save a lot of space, but
221also results in a very large runtime overhead (expect encoding times to be 233also results in a very large runtime overhead (expect encoding times to be
2222-4 times as high as without). 2342-4 times as high as without).
223 235
224It is recommended to leave it off unless you know your 236It is recommended to leave it off unless you know your
225communications partner supports the stringref extension to CBOR 237communications partner supports the stringref extension to CBOR
226(http://cbor.schmorp.de/stringref). 238(L<http://cbor.schmorp.de/stringref>), as without decoder support, the
239resulting data structure might not be usable.
227 240
228If C<$enable> is false (the default), then C<encode> will encode 241If C<$enable> is false (the default), then C<encode> will encode strings
229exception when it encounters anything it cannot encode as CBOR. 242the standard CBOR way.
230 243
231This option does not affect C<decode> in any way - string references will 244This option does not affect C<decode> in any way - string references will
232always be decoded properly if present. 245always be decoded properly if present.
233 246
234=item $cbor = $cbor->filter ([$cb->($tag, $value)]) 247=item $cbor = $cbor->filter ([$cb->($tag, $value)])
235 248
236=item $cb_or_undef = $cbor->get_filter 249=item $cb_or_undef = $cbor->get_filter
237 250
238TODO 251Sets or replaces the tagged value decoding filter (when C<$cb> is
252specified) or clears the filter (if no argument or C<undef> is provided).
253
254The filter callback is called only during decoding, when a non-enforced
255tagged value has been decoded (see L<TAG HANDLING AND EXTENSIONS> for a
256list of enforced tags). For specific tags, it's often better to provide a
257default converter using the C<%CBOR::XS::FILTER> hash (see below).
258
259The first argument is the numerical tag, the second is the (decoded) value
260that has been tagged.
261
262The filter function should return either exactly one value, which will
263replace the tagged value in the decoded data structure, or no values,
264which will result in default handling, which currently means the decoder
265creates a C<CBOR::XS::Tagged> object to hold the tag and the value.
266
267When the filter is cleared (the default state), the default filter
268function, C<CBOR::XS::default_filter>, is used. This function simply looks
269up the tag in the C<%CBOR::XS::FILTER> hash. If an entry exists it must be
270a code reference that is called with tag and value, and is responsible for
271decoding the value. If no entry exists, it returns no values.
272
273Example: decode all tags not handled internally into C<CBOR::XS::Tagged>
274objects, with no other special handling (useful when working with
275potentially "unsafe" CBOR data).
276
277 CBOR::XS->new->filter (sub { })->decode ($cbor_data);
278
279Example: provide a global filter for tag 1347375694, converting the value
280into some string form.
281
282 $CBOR::XS::FILTER{1347375694} = sub {
283 my ($tag, $value);
284
285 "tag 1347375694 value $value"
286 };
239 287
240=item $cbor_data = $cbor->encode ($perl_scalar) 288=item $cbor_data = $cbor->encode ($perl_scalar)
241 289
242Converts the given Perl data structure (a scalar value) to its CBOR 290Converts the given Perl data structure (a scalar value) to its CBOR
243representation. 291representation.
… …
284CBOR integers become (numeric) perl scalars. On perls without 64 bit 332CBOR integers become (numeric) perl scalars. On perls without 64 bit
285support, 64 bit integers will be truncated or otherwise corrupted. 333support, 64 bit integers will be truncated or otherwise corrupted.
286 334
287=item byte strings 335=item byte strings
288 336
289Byte strings will become octet strings in Perl (the byte values 0..255 337Byte strings will become octet strings in Perl (the Byte values 0..255
290will simply become characters of the same value in Perl). 338will simply become characters of the same value in Perl).
291 339
292=item UTF-8 strings 340=item UTF-8 strings
293 341
294UTF-8 strings in CBOR will be decoded, i.e. the UTF-8 octets will be 342UTF-8 strings in CBOR will be decoded, i.e. the UTF-8 octets will be
… …
317=item tagged values 365=item tagged values
318 366
319Tagged items consists of a numeric tag and another CBOR value. 367Tagged items consists of a numeric tag and another CBOR value.
320 368
321See L<TAG HANDLING AND EXTENSIONS> and the description of C<< ->filter >> 369See L<TAG HANDLING AND EXTENSIONS> and the description of C<< ->filter >>
322for details. 370for details on which tags are handled how.
323 371
324=item anything else 372=item anything else
325 373
326Anything else (e.g. unsupported simple values) will raise a decoding 374Anything else (e.g. unsupported simple values) will raise a decoding
327error. 375error.
… …
330 378
331 379
332=head2 PERL -> CBOR 380=head2 PERL -> CBOR
333 381
334The mapping from Perl to CBOR is slightly more difficult, as Perl is a 382The mapping from Perl to CBOR is slightly more difficult, as Perl is a
335truly typeless language, so we can only guess which CBOR type is meant by 383typeless language. That means this module can only guess which CBOR type
336a Perl value. 384is meant by a perl value.
337 385
338=over 4 386=over 4
339 387
340=item hash references 388=item hash references
341 389
342Perl hash references become CBOR maps. As there is no inherent ordering in 390Perl hash references become CBOR maps. As there is no inherent ordering in
343hash keys (or CBOR maps), they will usually be encoded in a pseudo-random 391hash keys (or CBOR maps), they will usually be encoded in a pseudo-random
344order. 392order. This order can be different each time a hahs is encoded.
345 393
346Currently, tied hashes will use the indefinite-length format, while normal 394Currently, tied hashes will use the indefinite-length format, while normal
347hashes will use the fixed-length format. 395hashes will use the fixed-length format.
348 396
349=item array references 397=item array references
350 398
351Perl array references become fixed-length CBOR arrays. 399Perl array references become fixed-length CBOR arrays.
352 400
353=item other references 401=item other references
354 402
355Other unblessed references are generally not allowed and will cause an 403Other unblessed references will be represented using
356exception to be thrown, except for references to the integers C<0> and 404the indirection tag extension (tag value C<22098>,
357C<1>, which get turned into false and true in CBOR. 405L<http://cbor.schmorp.de/indirection>). CBOR decoders are guaranteed
406to be able to decode these values somehow, by either "doing the right
407thing", decoding into a generic tagged object, simply ignoring the tag, or
408something else.
358 409
359=item CBOR::XS::Tagged objects 410=item CBOR::XS::Tagged objects
360 411
361Objects of this type must be arrays consisting of a single C<[tag, value]> 412Objects of this type must be arrays consisting of a single C<[tag, value]>
362pair. The (numerical) tag will be encoded as a CBOR tag, the value will 413pair. The (numerical) tag will be encoded as a CBOR tag, the value will
363be encoded as appropriate for the value. You cna use C<CBOR::XS::tag> to 414be encoded as appropriate for the value. You must use C<CBOR::XS::tag> to
364create such objects. 415create such objects.
365 416
366=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error 417=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error
367 418
368These special values become CBOR true, CBOR false and CBOR undefined 419These special values become CBOR true, CBOR false and CBOR undefined
… …
385 # dump as number 436 # dump as number
386 encode_cbor [2] # yields [2] 437 encode_cbor [2] # yields [2]
387 encode_cbor [-3.0e17] # yields [-3e+17] 438 encode_cbor [-3.0e17] # yields [-3e+17]
388 my $value = 5; encode_cbor [$value] # yields [5] 439 my $value = 5; encode_cbor [$value] # yields [5]
389 440
390 # used as string, so dump as string 441 # used as string, so dump as string (either byte or text)
391 print $value; 442 print $value;
392 encode_cbor [$value] # yields ["5"] 443 encode_cbor [$value] # yields ["5"]
393 444
394 # undef becomes null 445 # undef becomes null
395 encode_cbor [undef] # yields [null] 446 encode_cbor [undef] # yields [null]
… …
398 449
399 my $x = 3.1; # some variable containing a number 450 my $x = 3.1; # some variable containing a number
400 "$x"; # stringified 451 "$x"; # stringified
401 $x .= ""; # another, more awkward way to stringify 452 $x .= ""; # another, more awkward way to stringify
402 print $x; # perl does it for you, too, quite often 453 print $x; # perl does it for you, too, quite often
454
455You can force whether a string ie encoded as byte or text string by using
456C<utf8::upgrade> and C<utf8::downgrade>):
457
458 utf8::upgrade $x; # encode $x as text string
459 utf8::downgrade $x; # encode $x as byte string
460
461Perl doesn't define what operations up- and downgrade strings, so if the
462difference between byte and text is important, you should up- or downgrade
463your string as late as possible before encoding.
403 464
404You can force the type to be a CBOR number by numifying it: 465You can force the type to be a CBOR number by numifying it:
405 466
406 my $x = "3"; # some variable containing a string 467 my $x = "3"; # some variable containing a string
407 $x += 0; # numify it, ensuring it will be dumped as a number 468 $x += 0; # numify it, ensuring it will be dumped as a number
… …
420 481
421=back 482=back
422 483
423=head2 OBJECT SERIALISATION 484=head2 OBJECT SERIALISATION
424 485
486This module implements both a CBOR-specific and the generic
487L<Types::Serialier> object serialisation protocol. The following
488subsections explain both methods.
489
490=head3 ENCODING
491
425This module knows two way to serialise a Perl object: The CBOR-specific 492This module knows two way to serialise a Perl object: The CBOR-specific
426way, and the generic way. 493way, and the generic way.
427 494
428Whenever the encoder encounters a Perl object that it cnanot serialise 495Whenever the encoder encounters a Perl object that it cannot serialise
429directly (most of them), it will first look up the C<TO_CBOR> method on 496directly (most of them), it will first look up the C<TO_CBOR> method on
430it. 497it.
431 498
432If it has a C<TO_CBOR> method, it will call it with the object as only 499If it has a C<TO_CBOR> method, it will call it with the object as only
433argument, and expects exactly one return value, which it will then 500argument, and expects exactly one return value, which it will then
… …
439 506
440The C<FREEZE> method can return any number of values (i.e. zero or 507The C<FREEZE> method can return any number of values (i.e. zero or
441more). These will be encoded as CBOR perl object, together with the 508more). These will be encoded as CBOR perl object, together with the
442classname. 509classname.
443 510
511These methods I<MUST NOT> change the data structure that is being
512serialised. Failure to comply to this can result in memory corruption -
513and worse.
514
444If an object supports neither C<TO_CBOR> nor C<FREEZE>, encoding will fail 515If an object supports neither C<TO_CBOR> nor C<FREEZE>, encoding will fail
445with an error. 516with an error.
446 517
518=head3 DECODING
519
447Objects encoded via C<TO_CBOR> cannot be automatically decoded, but 520Objects encoded via C<TO_CBOR> cannot (normally) be automatically decoded,
448objects encoded via C<FREEZE> can be decoded using the following protocol: 521but objects encoded via C<FREEZE> can be decoded using the following
522protocol:
449 523
450When an encoded CBOR perl object is encountered by the decoder, it will 524When an encoded CBOR perl object is encountered by the decoder, it will
451look up the C<THAW> method, by using the stored classname, and will fail 525look up the C<THAW> method, by using the stored classname, and will fail
452if the method cannot be found. 526if the method cannot be found.
453 527
454After the lookup it will call the C<THAW> method with the stored classname 528After the lookup it will call the C<THAW> method with the stored classname
455as first argument, the constant string C<CBOR> as second argument, and all 529as first argument, the constant string C<CBOR> as second argument, and all
456values returned by C<FREEZE> as remaining arguments. 530values returned by C<FREEZE> as remaining arguments.
457 531
458=head4 EXAMPLES 532=head3 EXAMPLES
459 533
460Here is an example C<TO_CBOR> method: 534Here is an example C<TO_CBOR> method:
461 535
462 sub My::Object::TO_CBOR { 536 sub My::Object::TO_CBOR {
463 my ($obj) = @_; 537 my ($obj) = @_;
… …
474 548
475 sub URI::TO_CBOR { 549 sub URI::TO_CBOR {
476 my ($self) = @_; 550 my ($self) = @_;
477 my $uri = "$self"; # stringify uri 551 my $uri = "$self"; # stringify uri
478 utf8::upgrade $uri; # make sure it will be encoded as UTF-8 string 552 utf8::upgrade $uri; # make sure it will be encoded as UTF-8 string
479 CBOR::XS::tagged 32, "$_[0]" 553 CBOR::XS::tag 32, "$_[0]"
480 } 554 }
481 555
482This will encode URIs as a UTF-8 string with tag 32, which indicates an 556This will encode URIs as a UTF-8 string with tag 32, which indicates an
483URI. 557URI.
484 558
… …
640These tags are always handled when decoding, and their handling cannot be 714These tags are always handled when decoding, and their handling cannot be
641overriden by the user. 715overriden by the user.
642 716
643=over 4 717=over 4
644 718
645=item <unassigned> (perl-object, L<http://cbor.schmorp.de/perl-object>) 719=item 26 (perl-object, L<http://cbor.schmorp.de/perl-object>)
646 720
647These tags are automatically created (and decoded) for serialisable 721These tags are automatically created (and decoded) for serialisable
648objects using the C<FREEZE/THAW> methods (the L<Types::Serialier> object 722objects using the C<FREEZE/THAW> methods (the L<Types::Serialier> object
649serialisation protocol). See L<OBJECT SERIALISATION> for details. 723serialisation protocol). See L<OBJECT SERIALISATION> for details.
650 724
651=item <unassigned>, <unassigned> (sharable, sharedref, L <http://cbor.schmorp.de/value-sharing>) 725=item 28, 29 (shareable, sharedref, L <http://cbor.schmorp.de/value-sharing>)
652 726
653These tags are automatically decoded when encountered, resulting in 727These tags are automatically decoded when encountered (and they do not
728result in a cyclic data structure, see C<allow_cycles>), resulting in
654shared values in the decoded object. They are only encoded, however, when 729shared values in the decoded object. They are only encoded, however, when
655C<allow_sharable> is enabled. 730C<allow_sharing> is enabled.
656 731
732Not all shared values can be successfully decoded: values that reference
733themselves will I<currently> decode as C<undef> (this is not the same
734as a reference pointing to itself, which will be represented as a value
735that contains an indirect reference to itself - these will be decoded
736properly).
737
738Note that considerably more shared value data structures can be decoded
739than will be encoded - currently, only values pointed to by references
740will be shared, others will not. While non-reference shared values can be
741generated in Perl with some effort, they were considered too unimportant
742to be supported in the encoder. The decoder, however, will decode these
743values as shared values.
744
657=item <unassigned>, <unassigned> (stringref-namespace, stringref, L <http://cbor.schmorp.de/stringref>) 745=item 256, 25 (stringref-namespace, stringref, L <http://cbor.schmorp.de/stringref>)
658 746
659These tags are automatically decoded when encountered. They are only 747These tags are automatically decoded when encountered. They are only
660encoded, however, when C<allow_stringref> is enabled. 748encoded, however, when C<pack_strings> is enabled.
661 749
662=item 22098 (indirection, L<http://cbor.schmorp.de/indirection>) 750=item 22098 (indirection, L<http://cbor.schmorp.de/indirection>)
663 751
664This tag is automatically generated when a reference are encountered (with 752This tag is automatically generated when a reference are encountered (with
665the exception of hash and array refernces). It is converted to a reference 753the exception of hash and array refernces). It is converted to a reference
… …
670This value is not generated on encoding (unless explicitly requested by 758This value is not generated on encoding (unless explicitly requested by
671the user), and is simply ignored when decoding. 759the user), and is simply ignored when decoding.
672 760
673=back 761=back
674 762
675=head2 OPTIONAL TAGS 763=head2 NON-ENFORCED TAGS
676 764
677These tags have default filters provided when decoding. Their handling can 765These tags have default filters provided when decoding. Their handling can
678be overriden by changing the C<%CBOR::XS::FILTER> entry for the tag, or by 766be overriden by changing the C<%CBOR::XS::FILTER> entry for the tag, or by
679providing a custom C<filter> function when decoding. 767providing a custom C<filter> callback when decoding.
680 768
681When they result in decoding into a specific Perl class, the module 769When they result in decoding into a specific Perl class, the module
682usually provides a corresponding C<TO_CBOR> method as well. 770usually provides a corresponding C<TO_CBOR> method as well.
683 771
684When any of these need to load additional modules that are not part of the 772When any of these need to load additional modules that are not part of the
… …
826Only the double data type is supported for NV data types - when Perl uses 914Only the double data type is supported for NV data types - when Perl uses
827long double to represent floating point values, they might not be encoded 915long double to represent floating point values, they might not be encoded
828properly. Half precision types are accepted, but not encoded. 916properly. Half precision types are accepted, but not encoded.
829 917
830Strict mode and canonical mode are not implemented. 918Strict mode and canonical mode are not implemented.
919
920
921=head1 LIMITATIONS ON PERLS WITHOUT 64-BIT INTEGER SUPPORT
922
923On perls that were built without 64 bit integer support (these are rare
924nowadays, even on 32 bit architectures), support for any kind of 64 bit
925integer in CBOR is very limited - most likely, these 64 bit values will
926be truncated, corrupted, or otherwise not decoded correctly. This also
927includes string, array and map sizes that are stored as 64 bit integers.
831 928
832 929
833=head1 THREADS 930=head1 THREADS
834 931
835This module is I<not> guaranteed to be thread safe and there are no 932This module is I<not> guaranteed to be thread safe and there are no

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines