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.85 by root, Thu Nov 4 16:49:35 2021 UTC vs.
Revision 1.89 by root, Fri Sep 8 20:03:06 2023 UTC

… …
64 64
65package CBOR::XS; 65package CBOR::XS;
66 66
67use common::sense; 67use common::sense;
68 68
69our $VERSION = 1.86; 69our $VERSION = 1.87;
70our @ISA = qw(Exporter); 70our @ISA = qw(Exporter);
71 71
72our @EXPORT = qw(encode_cbor decode_cbor); 72our @EXPORT = qw(encode_cbor decode_cbor);
73 73
74use Exporter; 74use Exporter;
… …
216communication partner supports the value sharing extensions to CBOR 216communication partner supports the value sharing extensions to CBOR
217(L<http://cbor.schmorp.de/value-sharing>), as without decoder support, the 217(L<http://cbor.schmorp.de/value-sharing>), as without decoder support, the
218resulting data structure might be unusable. 218resulting data structure might be unusable.
219 219
220Detecting shared values incurs a runtime overhead when values are encoded 220Detecting shared values incurs a runtime overhead when values are encoded
221that have a reference counter large than one, and might unnecessarily 221that have a reference counter larger than one, and might unnecessarily
222increase the encoded size, as potentially shared values are encoded as 222increase the encoded size, as potentially shared values are encoded as
223shareable whether or not they are actually shared. 223shareable whether or not they are actually shared.
224 224
225At the moment, only targets of references can be shared (e.g. scalars, 225At the moment, only targets of references can be shared (e.g. scalars,
226arrays or hashes pointed to by a reference). Weirder constructs, such as 226arrays or hashes pointed to by a reference). Weirder constructs, such as
… …
245isn't prepared for this will not leak memory. 245isn't prepared for this will not leak memory.
246 246
247If C<$enable> is false (the default), then C<decode> will throw an error 247If C<$enable> is false (the default), then C<decode> will throw an error
248when it encounters a self-referential/cyclic data structure. 248when it encounters a self-referential/cyclic data structure.
249 249
250FUTURE DIRECTION: the motivation behind this option is to avoid I<real> 250This option does not affect C<encode> in any way - shared values and
251cycles - future versions of this module might chose to decode cyclic data 251references will always be encoded properly if present.
252structures using weak references when this option is off, instead of 252
253throwing an error. 253=item $cbor = $cbor->allow_weak_cycles ([$enable])
254
255=item $enabled = $cbor->get_allow_weak_cycles
256
257This works like C<allow_cycles> in that it allows the resulting data
258structures to contain cycles, but unlike C<allow_cycles>, those cyclic
259rreferences will be weak. That means that code that recurrsively walks
260the data structure must be prepared with cycles, but at least not special
261precautions must be implemented to free these data structures.
262
263Only those references leading to actual cycles will be weakened - other
264references, e.g. when the same hash or arrray is referenced multiple times
265in an arrray, will be normal references.
254 266
255This option does not affect C<encode> in any way - shared values and 267This option does not affect C<encode> in any way - shared values and
256references will always be encoded properly if present. 268references will always be encoded properly if present.
257 269
258=item $cbor = $cbor->forbid_objects ([$enable]) 270=item $cbor = $cbor->forbid_objects ([$enable])
… …
473Perl data structure in memory at one time, it does allow you to parse a 485Perl data structure in memory at one time, it does allow you to parse a
474CBOR stream incrementally, using a similar to using "decode_prefix" to see 486CBOR stream incrementally, using a similar to using "decode_prefix" to see
475if a full CBOR object is available, but is much more efficient. 487if a full CBOR object is available, but is much more efficient.
476 488
477It basically works by parsing as much of a CBOR string as possible - if 489It basically works by parsing as much of a CBOR string as possible - if
478the CBOR data is not complete yet, the pasrer will remember where it was, 490the CBOR data is not complete yet, the parser will remember where it was,
479to be able to restart when more data has been accumulated. Once enough 491to be able to restart when more data has been accumulated. Once enough
480data is available to either decode a complete CBOR value or raise an 492data is available to either decode a complete CBOR value or raise an
481error, a real decode will be attempted. 493error, a real decode will be attempted.
482 494
483A typical use case would be a network protocol that consists of sending 495A typical use case would be a network protocol that consists of sending
… …
635create such objects. 647create such objects.
636 648
637=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error 649=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error
638 650
639These special values become CBOR true, CBOR false and CBOR undefined 651These special values become CBOR true, CBOR false and CBOR undefined
640values, respectively. You can also use C<\1>, C<\0> and C<\undef> directly 652values, respectively.
641if you want.
642 653
643=item other blessed objects 654=item other blessed objects
644 655
645Other blessed objects are serialised via C<TO_CBOR> or C<FREEZE>. See 656Other blessed objects are serialised via C<TO_CBOR> or C<FREEZE>. See
646L<TAG HANDLING AND EXTENSIONS> for specific classes handled by this 657L<TAG HANDLING AND EXTENSIONS> for specific classes handled by this

Diff Legend

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