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.19 by root, Wed Nov 20 01:09:46 2013 UTC vs.
Revision 1.20 by root, Wed Nov 20 02:03:08 2013 UTC

… …
171exception when it encounters anything it cannot encode as CBOR. 171exception when it encounters anything it cannot encode as CBOR.
172 172
173This option does not affect C<decode> in any way, and it is recommended to 173This option does not affect C<decode> in any way, and it is recommended to
174leave it off unless you know your communications partner. 174leave it off unless you know your communications partner.
175 175
176=item $cbor = $cbor->allow_sharable ([$enable]) 176=item $cbor = $cbor->allow_sharing ([$enable])
177 177
178=item $enabled = $cbor->get_allow_sharable 178=item $enabled = $cbor->get_allow_sharing
179 179
180If C<$enable> is true (or missing), then C<encode> will not double-encode 180If C<$enable> is true (or missing), then C<encode> will not double-encode
181values that have been seen before (e.g. when the same object, such as an 181values that have been referenced before (e.g. when the same object, such
182array, is referenced multiple times), but instead will emit a reference to 182as an array, is referenced multiple times), but instead will emit a
183the earlier value. 183reference to the earlier value.
184 184
185This means that such values will only be encoded once, and will not result 185This means that such values will only be encoded once, and will not result
186in a deep cloning of the value on decode, in decoders supporting the value 186in a deep cloning of the value on decode, in decoders supporting the value
187sharing extension. 187sharing extension.
188 188
189Detecting shared values incurs a runtime overhead when values are encoded 189Detecting shared values incurs a runtime overhead when values are encoded
190that have a reference counter large than one, and might unnecessarily 190that have a reference counter large than one, and might unnecessarily
191increase the encoded size, as potentially shared values are encode as 191increase the encoded size, as potentially shared values are encode as
192sharable whether or not they are actually shared. 192sharable whether or not they are actually shared.
193 193
194At the moment, all shared values will be detected, even weird and unusual 194At the moment, only targets of references can be shared (e.g. scalars,
195cases, such as an array with multiple "copies" of the I<same> scalar, 195arrays or hashes pointed to by a reference). Weirder constructs, such as
196which are hard but not impossible to create in Perl (L<Storable> for 196an array with multiple "copies" of the I<same> string, which are hard but
197example doesn't handle these cases). If this turns out ot be a performance 197not impossible to create in Perl, are not supported (this is the same as
198issue then future versions might limit the shared value detection to 198for L<Storable>).
199references only.
200 199
201If C<$enable> is false (the default), then C<encode> will encode 200If C<$enable> is false (the default), then C<encode> will encode
202exception when it encounters anything it cannot encode as CBOR. 201exception when it encounters anything it cannot encode as CBOR.
203 202
204This option does not affect C<decode> in any way - shared values and 203This option does not affect C<decode> in any way - shared values and

Diff Legend

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