| … | |
… | |
| 165 | partner supports the value sharing extensions to CBOR |
165 | partner supports the value sharing extensions to CBOR |
| 166 | (<http://cbor.schmorp.de/value-sharing>), as without decoder |
166 | (<http://cbor.schmorp.de/value-sharing>), as without decoder |
| 167 | support, the resulting data structure might be unusable. |
167 | support, the resulting data structure might be unusable. |
| 168 | |
168 | |
| 169 | Detecting shared values incurs a runtime overhead when values are |
169 | Detecting shared values incurs a runtime overhead when values are |
| 170 | encoded that have a reference counter large than one, and might |
170 | encoded that have a reference counter larger than one, and might |
| 171 | unnecessarily increase the encoded size, as potentially shared |
171 | unnecessarily increase the encoded size, as potentially shared |
| 172 | values are encoded as shareable whether or not they are actually |
172 | values are encoded as shareable whether or not they are actually |
| 173 | shared. |
173 | shared. |
| 174 | |
174 | |
| 175 | At the moment, only targets of references can be shared (e.g. |
175 | At the moment, only targets of references can be shared (e.g. |
| … | |
… | |
| 193 | code that isn't prepared for this will not leak memory. |
193 | code that isn't prepared for this will not leak memory. |
| 194 | |
194 | |
| 195 | If $enable is false (the default), then "decode" will throw an error |
195 | If $enable is false (the default), then "decode" will throw an error |
| 196 | when it encounters a self-referential/cyclic data structure. |
196 | when it encounters a self-referential/cyclic data structure. |
| 197 | |
197 | |
| 198 | FUTURE DIRECTION: the motivation behind this option is to avoid |
198 | This option does not affect "encode" in any way - shared values and |
| 199 | *real* cycles - future versions of this module might chose to decode |
199 | references will always be encoded properly if present. |
| 200 | cyclic data structures using weak references when this option is |
200 | |
| 201 | off, instead of throwing an error. |
201 | $cbor = $cbor->allow_weak_cycles ([$enable]) |
|
|
202 | $enabled = $cbor->get_allow_weak_cycles |
|
|
203 | This works like "allow_cycles" in that it allows the resulting data |
|
|
204 | structures to contain cycles, but unlike "allow_cycles", those |
|
|
205 | cyclic rreferences will be weak. That means that code that |
|
|
206 | recurrsively walks the data structure must be prepared with cycles, |
|
|
207 | but at least not special precautions must be implemented to free |
|
|
208 | these data structures. |
|
|
209 | |
|
|
210 | Only those references leading to actual cycles will be weakened - |
|
|
211 | other references, e.g. when the same hash or arrray is referenced |
|
|
212 | multiple times in an arrray, will be normal references. |
| 202 | |
213 | |
| 203 | This option does not affect "encode" in any way - shared values and |
214 | This option does not affect "encode" in any way - shared values and |
| 204 | references will always be encoded properly if present. |
215 | references will always be encoded properly if present. |
| 205 | |
216 | |
| 206 | $cbor = $cbor->forbid_objects ([$enable]) |
217 | $cbor = $cbor->forbid_objects ([$enable]) |
| … | |
… | |
| 414 | data structure in memory at one time, it does allow you to parse a CBOR |
425 | data structure in memory at one time, it does allow you to parse a CBOR |
| 415 | stream incrementally, using a similar to using "decode_prefix" to see if |
426 | stream incrementally, using a similar to using "decode_prefix" to see if |
| 416 | a full CBOR object is available, but is much more efficient. |
427 | a full CBOR object is available, but is much more efficient. |
| 417 | |
428 | |
| 418 | It basically works by parsing as much of a CBOR string as possible - if |
429 | It basically works by parsing as much of a CBOR string as possible - if |
| 419 | the CBOR data is not complete yet, the pasrer will remember where it |
430 | the CBOR data is not complete yet, the parser will remember where it |
| 420 | was, to be able to restart when more data has been accumulated. Once |
431 | was, to be able to restart when more data has been accumulated. Once |
| 421 | enough data is available to either decode a complete CBOR value or raise |
432 | enough data is available to either decode a complete CBOR value or raise |
| 422 | an error, a real decode will be attempted. |
433 | an error, a real decode will be attempted. |
| 423 | |
434 | |
| 424 | A typical use case would be a network protocol that consists of sending |
435 | A typical use case would be a network protocol that consists of sending |
| … | |
… | |
| 548 | "CBOR::XS::tag" to create such objects. |
559 | "CBOR::XS::tag" to create such objects. |
| 549 | |
560 | |
| 550 | Types::Serialiser::true, Types::Serialiser::false, |
561 | Types::Serialiser::true, Types::Serialiser::false, |
| 551 | Types::Serialiser::error |
562 | Types::Serialiser::error |
| 552 | These special values become CBOR true, CBOR false and CBOR undefined |
563 | These special values become CBOR true, CBOR false and CBOR undefined |
| 553 | values, respectively. You can also use "\1", "\0" and "\undef" |
564 | values, respectively. |
| 554 | directly if you want. |
|
|
| 555 | |
565 | |
| 556 | other blessed objects |
566 | other blessed objects |
| 557 | Other blessed objects are serialised via "TO_CBOR" or "FREEZE". See |
567 | Other blessed objects are serialised via "TO_CBOR" or "FREEZE". See |
| 558 | "TAG HANDLING AND EXTENSIONS" for specific classes handled by this |
568 | "TAG HANDLING AND EXTENSIONS" for specific classes handled by this |
| 559 | module, and "OBJECT SERIALISATION" for generic object serialisation. |
569 | module, and "OBJECT SERIALISATION" for generic object serialisation. |
