… | |
… | |
465 | |
465 | |
466 | =back |
466 | =back |
467 | |
467 | |
468 | =head2 OBJECT SERIALISATION |
468 | =head2 OBJECT SERIALISATION |
469 | |
469 | |
|
|
470 | This module implements both a CBOR-specific and the generic |
|
|
471 | L<Types::Serialier> object serialisation protocol. The following |
|
|
472 | subsections explain both methods. |
|
|
473 | |
|
|
474 | =head3 ENCODING |
|
|
475 | |
470 | This module knows two way to serialise a Perl object: The CBOR-specific |
476 | This module knows two way to serialise a Perl object: The CBOR-specific |
471 | way, and the generic way. |
477 | way, and the generic way. |
472 | |
478 | |
473 | Whenever the encoder encounters a Perl object that it cnanot serialise |
479 | Whenever the encoder encounters a Perl object that it cannot serialise |
474 | directly (most of them), it will first look up the C<TO_CBOR> method on |
480 | directly (most of them), it will first look up the C<TO_CBOR> method on |
475 | it. |
481 | it. |
476 | |
482 | |
477 | If it has a C<TO_CBOR> method, it will call it with the object as only |
483 | If it has a C<TO_CBOR> method, it will call it with the object as only |
478 | argument, and expects exactly one return value, which it will then |
484 | argument, and expects exactly one return value, which it will then |
… | |
… | |
484 | |
490 | |
485 | The C<FREEZE> method can return any number of values (i.e. zero or |
491 | The C<FREEZE> method can return any number of values (i.e. zero or |
486 | more). These will be encoded as CBOR perl object, together with the |
492 | more). These will be encoded as CBOR perl object, together with the |
487 | classname. |
493 | classname. |
488 | |
494 | |
|
|
495 | These methods I<MUST NOT> change the data structure that is being |
|
|
496 | serialised. Failure to comply to this can result in memory corruption - |
|
|
497 | and worse. |
|
|
498 | |
489 | If an object supports neither C<TO_CBOR> nor C<FREEZE>, encoding will fail |
499 | If an object supports neither C<TO_CBOR> nor C<FREEZE>, encoding will fail |
490 | with an error. |
500 | with an error. |
491 | |
501 | |
|
|
502 | =head3 DECODING |
|
|
503 | |
492 | Objects encoded via C<TO_CBOR> cannot be automatically decoded, but |
504 | Objects encoded via C<TO_CBOR> cannot (normally) be automatically decoded, |
493 | objects encoded via C<FREEZE> can be decoded using the following protocol: |
505 | but objects encoded via C<FREEZE> can be decoded using the following |
|
|
506 | protocol: |
494 | |
507 | |
495 | When an encoded CBOR perl object is encountered by the decoder, it will |
508 | When an encoded CBOR perl object is encountered by the decoder, it will |
496 | look up the C<THAW> method, by using the stored classname, and will fail |
509 | look up the C<THAW> method, by using the stored classname, and will fail |
497 | if the method cannot be found. |
510 | if the method cannot be found. |
498 | |
511 | |
499 | After the lookup it will call the C<THAW> method with the stored classname |
512 | After the lookup it will call the C<THAW> method with the stored classname |
500 | as first argument, the constant string C<CBOR> as second argument, and all |
513 | as first argument, the constant string C<CBOR> as second argument, and all |
501 | values returned by C<FREEZE> as remaining arguments. |
514 | values returned by C<FREEZE> as remaining arguments. |
502 | |
515 | |
503 | =head4 EXAMPLES |
516 | =head3 EXAMPLES |
504 | |
517 | |
505 | Here is an example C<TO_CBOR> method: |
518 | Here is an example C<TO_CBOR> method: |
506 | |
519 | |
507 | sub My::Object::TO_CBOR { |
520 | sub My::Object::TO_CBOR { |
508 | my ($obj) = @_; |
521 | my ($obj) = @_; |
… | |
… | |
871 | Only the double data type is supported for NV data types - when Perl uses |
884 | Only the double data type is supported for NV data types - when Perl uses |
872 | long double to represent floating point values, they might not be encoded |
885 | long double to represent floating point values, they might not be encoded |
873 | properly. Half precision types are accepted, but not encoded. |
886 | properly. Half precision types are accepted, but not encoded. |
874 | |
887 | |
875 | Strict mode and canonical mode are not implemented. |
888 | Strict mode and canonical mode are not implemented. |
|
|
889 | |
|
|
890 | |
|
|
891 | =head1 LIMITATIONS ON PERLS WITHOUT 64-BIT INTEGER SUPPORT |
|
|
892 | |
|
|
893 | On perls that were built without 64 bit integer support (these are rare |
|
|
894 | nowadays, even on 32 bit architectures), support for any kind of 64 bit |
|
|
895 | integer in CBOR is very limited - most likely, these 64 bit values will |
|
|
896 | be truncated, corrupted, or otherwise not decoded correctly. This also |
|
|
897 | includes string, array and map sizes that are stored as 64 bit integers. |
876 | |
898 | |
877 | |
899 | |
878 | =head1 THREADS |
900 | =head1 THREADS |
879 | |
901 | |
880 | This module is I<not> guaranteed to be thread safe and there are no |
902 | This module is I<not> guaranteed to be thread safe and there are no |