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