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.28 by root, Thu Nov 28 16:09:04 2013 UTC vs.
Revision 1.29 by root, Sat Nov 30 15:23:59 2013 UTC

… …
465 465
466=back 466=back
467 467
468=head2 OBJECT SERIALISATION 468=head2 OBJECT SERIALISATION
469 469
470This module implements both a CBOR-specific and the generic
471L<Types::Serialier> object serialisation protocol. The following
472subsections explain both methods.
473
474=head3 ENCODING
475
470This module knows two way to serialise a Perl object: The CBOR-specific 476This module knows two way to serialise a Perl object: The CBOR-specific
471way, and the generic way. 477way, and the generic way.
472 478
473Whenever the encoder encounters a Perl object that it cnanot serialise 479Whenever the encoder encounters a Perl object that it cannot serialise
474directly (most of them), it will first look up the C<TO_CBOR> method on 480directly (most of them), it will first look up the C<TO_CBOR> method on
475it. 481it.
476 482
477If it has a C<TO_CBOR> method, it will call it with the object as only 483If it has a C<TO_CBOR> method, it will call it with the object as only
478argument, and expects exactly one return value, which it will then 484argument, and expects exactly one return value, which it will then
… …
484 490
485The C<FREEZE> method can return any number of values (i.e. zero or 491The C<FREEZE> method can return any number of values (i.e. zero or
486more). These will be encoded as CBOR perl object, together with the 492more). These will be encoded as CBOR perl object, together with the
487classname. 493classname.
488 494
495These methods I<MUST NOT> change the data structure that is being
496serialised. Failure to comply to this can result in memory corruption -
497and worse.
498
489If an object supports neither C<TO_CBOR> nor C<FREEZE>, encoding will fail 499If an object supports neither C<TO_CBOR> nor C<FREEZE>, encoding will fail
490with an error. 500with an error.
491 501
502=head3 DECODING
503
492Objects encoded via C<TO_CBOR> cannot be automatically decoded, but 504Objects encoded via C<TO_CBOR> cannot (normally) be automatically decoded,
493objects encoded via C<FREEZE> can be decoded using the following protocol: 505but objects encoded via C<FREEZE> can be decoded using the following
506protocol:
494 507
495When an encoded CBOR perl object is encountered by the decoder, it will 508When an encoded CBOR perl object is encountered by the decoder, it will
496look up the C<THAW> method, by using the stored classname, and will fail 509look up the C<THAW> method, by using the stored classname, and will fail
497if the method cannot be found. 510if the method cannot be found.
498 511
499After the lookup it will call the C<THAW> method with the stored classname 512After the lookup it will call the C<THAW> method with the stored classname
500as first argument, the constant string C<CBOR> as second argument, and all 513as first argument, the constant string C<CBOR> as second argument, and all
501values returned by C<FREEZE> as remaining arguments. 514values returned by C<FREEZE> as remaining arguments.
502 515
503=head4 EXAMPLES 516=head3 EXAMPLES
504 517
505Here is an example C<TO_CBOR> method: 518Here 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) = @_;

Diff Legend

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