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.24 by root, Fri Nov 22 16:18:59 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.09; 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)])
… …
255function, C<CBOR::XS::default_filter>, is used. This function simply looks 268function, C<CBOR::XS::default_filter>, is used. This function simply looks
256up the tag in the C<%CBOR::XS::FILTER> hash. If an entry exists it must be 269up the tag in the C<%CBOR::XS::FILTER> hash. If an entry exists it must be
257a code reference that is called with tag and value, and is responsible for 270a code reference that is called with tag and value, and is responsible for
258decoding the value. If no entry exists, it returns no values. 271decoding the value. If no entry exists, it returns no values.
259 272
260Example: decode all tags not handled internally into CBOR::XS::Tagged 273Example: decode all tags not handled internally into C<CBOR::XS::Tagged>
261objects, with no other special handling (useful when working with 274objects, with no other special handling (useful when working with
262potentially "unsafe" CBOR data). 275potentially "unsafe" CBOR data).
263 276
264 CBOR::XS->new->filter (sub { })->decode ($cbor_data); 277 CBOR::XS->new->filter (sub { })->decode ($cbor_data);
265 278
… …
319CBOR integers become (numeric) perl scalars. On perls without 64 bit 332CBOR integers become (numeric) perl scalars. On perls without 64 bit
320support, 64 bit integers will be truncated or otherwise corrupted. 333support, 64 bit integers will be truncated or otherwise corrupted.
321 334
322=item byte strings 335=item byte strings
323 336
324Byte 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
325will simply become characters of the same value in Perl). 338will simply become characters of the same value in Perl).
326 339
327=item UTF-8 strings 340=item UTF-8 strings
328 341
329UTF-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
… …
352=item tagged values 365=item tagged values
353 366
354Tagged items consists of a numeric tag and another CBOR value. 367Tagged items consists of a numeric tag and another CBOR value.
355 368
356See L<TAG HANDLING AND EXTENSIONS> and the description of C<< ->filter >> 369See L<TAG HANDLING AND EXTENSIONS> and the description of C<< ->filter >>
357for details. 370for details on which tags are handled how.
358 371
359=item anything else 372=item anything else
360 373
361Anything else (e.g. unsupported simple values) will raise a decoding 374Anything else (e.g. unsupported simple values) will raise a decoding
362error. 375error.
… …
365 378
366 379
367=head2 PERL -> CBOR 380=head2 PERL -> CBOR
368 381
369The 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
370truly 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
371a Perl value. 384is meant by a perl value.
372 385
373=over 4 386=over 4
374 387
375=item hash references 388=item hash references
376 389
377Perl 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
378hash 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
379order. 392order. This order can be different each time a hahs is encoded.
380 393
381Currently, tied hashes will use the indefinite-length format, while normal 394Currently, tied hashes will use the indefinite-length format, while normal
382hashes will use the fixed-length format. 395hashes will use the fixed-length format.
383 396
384=item array references 397=item array references
385 398
386Perl array references become fixed-length CBOR arrays. 399Perl array references become fixed-length CBOR arrays.
387 400
388=item other references 401=item other references
389 402
390Other unblessed references are generally not allowed and will cause an 403Other unblessed references will be represented using
391exception to be thrown, except for references to the integers C<0> and 404the indirection tag extension (tag value C<22098>,
392C<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.
393 409
394=item CBOR::XS::Tagged objects 410=item CBOR::XS::Tagged objects
395 411
396Objects 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]>
397pair. 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
398be 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
399create such objects. 415create such objects.
400 416
401=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error 417=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error
402 418
403These special values become CBOR true, CBOR false and CBOR undefined 419These special values become CBOR true, CBOR false and CBOR undefined
… …
420 # dump as number 436 # dump as number
421 encode_cbor [2] # yields [2] 437 encode_cbor [2] # yields [2]
422 encode_cbor [-3.0e17] # yields [-3e+17] 438 encode_cbor [-3.0e17] # yields [-3e+17]
423 my $value = 5; encode_cbor [$value] # yields [5] 439 my $value = 5; encode_cbor [$value] # yields [5]
424 440
425 # used as string, so dump as string 441 # used as string, so dump as string (either byte or text)
426 print $value; 442 print $value;
427 encode_cbor [$value] # yields ["5"] 443 encode_cbor [$value] # yields ["5"]
428 444
429 # undef becomes null 445 # undef becomes null
430 encode_cbor [undef] # yields [null] 446 encode_cbor [undef] # yields [null]
… …
433 449
434 my $x = 3.1; # some variable containing a number 450 my $x = 3.1; # some variable containing a number
435 "$x"; # stringified 451 "$x"; # stringified
436 $x .= ""; # another, more awkward way to stringify 452 $x .= ""; # another, more awkward way to stringify
437 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.
438 464
439You 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:
440 466
441 my $x = "3"; # some variable containing a string 467 my $x = "3"; # some variable containing a string
442 $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
… …
455 481
456=back 482=back
457 483
458=head2 OBJECT SERIALISATION 484=head2 OBJECT SERIALISATION
459 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
460This 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
461way, and the generic way. 493way, and the generic way.
462 494
463Whenever the encoder encounters a Perl object that it cnanot serialise 495Whenever the encoder encounters a Perl object that it cannot serialise
464directly (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
465it. 497it.
466 498
467If 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
468argument, and expects exactly one return value, which it will then 500argument, and expects exactly one return value, which it will then
… …
474 506
475The 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
476more). These will be encoded as CBOR perl object, together with the 508more). These will be encoded as CBOR perl object, together with the
477classname. 509classname.
478 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
479If 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
480with an error. 516with an error.
481 517
518=head3 DECODING
519
482Objects encoded via C<TO_CBOR> cannot be automatically decoded, but 520Objects encoded via C<TO_CBOR> cannot (normally) be automatically decoded,
483objects encoded via C<FREEZE> can be decoded using the following protocol: 521but objects encoded via C<FREEZE> can be decoded using the following
522protocol:
484 523
485When 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
486look 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
487if the method cannot be found. 526if the method cannot be found.
488 527
489After 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
490as 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
491values returned by C<FREEZE> as remaining arguments. 530values returned by C<FREEZE> as remaining arguments.
492 531
493=head4 EXAMPLES 532=head3 EXAMPLES
494 533
495Here is an example C<TO_CBOR> method: 534Here is an example C<TO_CBOR> method:
496 535
497 sub My::Object::TO_CBOR { 536 sub My::Object::TO_CBOR {
498 my ($obj) = @_; 537 my ($obj) = @_;
… …
509 548
510 sub URI::TO_CBOR { 549 sub URI::TO_CBOR {
511 my ($self) = @_; 550 my ($self) = @_;
512 my $uri = "$self"; # stringify uri 551 my $uri = "$self"; # stringify uri
513 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
514 CBOR::XS::tagged 32, "$_[0]" 553 CBOR::XS::tag 32, "$_[0]"
515 } 554 }
516 555
517This 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
518URI. 557URI.
519 558
… …
675These tags are always handled when decoding, and their handling cannot be 714These tags are always handled when decoding, and their handling cannot be
676overriden by the user. 715overriden by the user.
677 716
678=over 4 717=over 4
679 718
680=item <unassigned> (perl-object, L<http://cbor.schmorp.de/perl-object>) 719=item 26 (perl-object, L<http://cbor.schmorp.de/perl-object>)
681 720
682These tags are automatically created (and decoded) for serialisable 721These tags are automatically created (and decoded) for serialisable
683objects using the C<FREEZE/THAW> methods (the L<Types::Serialier> object 722objects using the C<FREEZE/THAW> methods (the L<Types::Serialier> object
684serialisation protocol). See L<OBJECT SERIALISATION> for details. 723serialisation protocol). See L<OBJECT SERIALISATION> for details.
685 724
686=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>)
687 726
688These 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
689shared values in the decoded object. They are only encoded, however, when 729shared values in the decoded object. They are only encoded, however, when
690C<allow_sharable> is enabled. 730C<allow_sharing> is enabled.
691 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
692=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>)
693 746
694These tags are automatically decoded when encountered. They are only 747These tags are automatically decoded when encountered. They are only
695encoded, however, when C<allow_stringref> is enabled. 748encoded, however, when C<pack_strings> is enabled.
696 749
697=item 22098 (indirection, L<http://cbor.schmorp.de/indirection>) 750=item 22098 (indirection, L<http://cbor.schmorp.de/indirection>)
698 751
699This tag is automatically generated when a reference are encountered (with 752This tag is automatically generated when a reference are encountered (with
700the 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
… …
861Only 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
862long double to represent floating point values, they might not be encoded 915long double to represent floating point values, they might not be encoded
863properly. Half precision types are accepted, but not encoded. 916properly. Half precision types are accepted, but not encoded.
864 917
865Strict 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.
866 928
867 929
868=head1 THREADS 930=head1 THREADS
869 931
870This 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