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.30 by root, Sat Nov 30 16:19:59 2013 UTC vs.
Revision 1.31 by root, Sat Nov 30 18:13:53 2013 UTC

… …
48Regarding compactness, C<CBOR::XS>-encoded data structures are usually 48Regarding compactness, C<CBOR::XS>-encoded data structures are usually
49about 20% smaller than the same data encoded as (compact) JSON or 49about 20% smaller than the same data encoded as (compact) JSON or
50L<Storable>. 50L<Storable>.
51 51
52In addition to the core CBOR data format, this module implements a 52In addition to the core CBOR data format, this module implements a
53number of extensions, to support cyclic and shared data structures (see 53number of extensions, to support cyclic and shared data structures
54C<allow_sharing>), string deduplication (see C<pack_strings>) and scalar 54(see C<allow_sharing> and C<allow_cycles>), string deduplication (see
55references (always enabled). 55C<pack_strings>) and scalar references (always enabled).
56 56
57The 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
58is 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.
59 59
60See 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
… …
180reference to the earlier value. 180reference to the earlier value.
181 181
182This 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
183in 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
184sharing extension. This also makes it possible to encode cyclic data 184sharing extension. This also makes it possible to encode cyclic data
185structures. 185structures (which need C<allow_cycles> to ne enabled to be decoded by this
186module).
186 187
187It is recommended to leave it off unless you know your 188It is recommended to leave it off unless you know your
188communication partner supports the value sharing extensions to CBOR 189communication partner supports the value sharing extensions to CBOR
189(L<http://cbor.schmorp.de/value-sharing>), as without decoder support, the 190(L<http://cbor.schmorp.de/value-sharing>), as without decoder support, the
190resulting data structure might be unusable. 191resulting data structure might be unusable.
191 192
192Detecting shared values incurs a runtime overhead when values are encoded 193Detecting shared values incurs a runtime overhead when values are encoded
193that have a reference counter large than one, and might unnecessarily 194that have a reference counter large than one, and might unnecessarily
194increase the encoded size, as potentially shared values are encode as 195increase the encoded size, as potentially shared values are encode as
195sharable whether or not they are actually shared. 196shareable whether or not they are actually shared.
196 197
197At 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,
198arrays or hashes pointed to by a reference). Weirder constructs, such as 199arrays or hashes pointed to by a reference). Weirder constructs, such as
199an 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
200not 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
… …
203If C<$enable> is false (the default), then C<encode> will encode shared 204If C<$enable> is false (the default), then C<encode> will encode shared
204data structures repeatedly, unsharing them in the process. Cyclic data 205data structures repeatedly, unsharing them in the process. Cyclic data
205structures cannot be encoded in this mode. 206structures cannot be encoded in this mode.
206 207
207This 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
209references will always be decoded properly if present.
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
208references will always be decoded properly if present. 224references will always be decoded properly if present.
209 225
210=item $cbor = $cbor->pack_strings ([$enable]) 226=item $cbor = $cbor->pack_strings ([$enable])
211 227
212=item $enabled = $cbor->get_pack_strings 228=item $enabled = $cbor->get_pack_strings
… …
704 720
705These tags are automatically created (and decoded) for serialisable 721These tags are automatically created (and decoded) for serialisable
706objects using the C<FREEZE/THAW> methods (the L<Types::Serialier> object 722objects using the C<FREEZE/THAW> methods (the L<Types::Serialier> object
707serialisation protocol). See L<OBJECT SERIALISATION> for details. 723serialisation protocol). See L<OBJECT SERIALISATION> for details.
708 724
709=item 28, 29 (sharable, sharedref, L <http://cbor.schmorp.de/value-sharing>) 725=item 28, 29 (shareable, sharedref, L <http://cbor.schmorp.de/value-sharing>)
710 726
711These 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
712shared values in the decoded object. They are only encoded, however, when 729shared values in the decoded object. They are only encoded, however, when
713C<allow_sharable> is enabled. 730C<allow_sharing> is enabled.
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.
714 744
715=item 256, 25 (stringref-namespace, stringref, L <http://cbor.schmorp.de/stringref>) 745=item 256, 25 (stringref-namespace, stringref, L <http://cbor.schmorp.de/stringref>)
716 746
717These tags are automatically decoded when encountered. They are only 747These tags are automatically decoded when encountered. They are only
718encoded, however, when C<pack_strings> is enabled. 748encoded, however, when C<pack_strings> is enabled.

Diff Legend

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