1 |
root |
1.1 |
=head1 REGISTRATION INFORMATION |
2 |
|
|
|
3 |
|
|
Tag <unassigned> (shareable) |
4 |
|
|
Data Item multiple |
5 |
|
|
Semantics mark value as (potentially) shared |
6 |
|
|
Reference http://cbor.schmorp.de/value-sharing |
7 |
|
|
Contact Marc A. Lehmann <cbor@schmorp.de> |
8 |
|
|
|
9 |
|
|
Tag <unassigned> (sharedref) |
10 |
|
|
Data Item unsigned integer |
11 |
|
|
Semantics reference nth marked value |
12 |
|
|
Reference http://cbor.schmorp.de/value-sharing |
13 |
|
|
Contact Marc A. Lehmann <cbor@schmorp.de> |
14 |
|
|
|
15 |
|
|
=head1 SUMMARY |
16 |
|
|
|
17 |
|
|
These two tags can be used to implement shared value support in CBOR. |
18 |
|
|
|
19 |
|
|
=head1 RATIONALE |
20 |
|
|
|
21 |
|
|
Many serialisable data structures can contain values that are |
22 |
|
|
shared. For example, in Perl, you could have an array with two hash |
23 |
|
|
references pointing to the same object. |
24 |
|
|
|
25 |
|
|
When serialising these data structures to CBOR, these values either |
26 |
|
|
become unshared (duplicated), or, when the structure contains cycles, |
27 |
|
|
they are not serialisable into CBOR at all. |
28 |
|
|
|
29 |
|
|
This extension implements explicit shared value support - encoders need |
30 |
|
|
to explicitly mark values as potentially shared and can later refer to |
31 |
|
|
them. |
32 |
|
|
|
33 |
|
|
This extension is not meant to save space in the CBOR representation by |
34 |
|
|
encoding duplicated values only once - the shared values are supposed |
35 |
|
|
to refer to the same value after decoding (e.g. when implemented as a |
36 |
|
|
pointer, all references to the value should point to the same memory |
37 |
|
|
object). |
38 |
|
|
|
39 |
|
|
=head1 DESCRIPTION |
40 |
|
|
|
41 |
|
|
To share values, the first occurrence of the value must be explicitly |
42 |
|
|
tagged with the shareable tag (value <unassigned>). |
43 |
|
|
|
44 |
|
|
Subsequent occurrences can then be encoded by encoding the index |
45 |
|
|
of a previously marked value tagged with the sharedref tag (value |
46 |
|
|
<unassigned>). That is, index 0 refers to the first value marked as |
47 |
|
|
shareable in the CBOR stream, index 1 to the second and so on. |
48 |
|
|
|
49 |
|
|
There is no requirement to actually refer to a value marked as |
50 |
|
|
shareable - encoders can mark any value they want without ever |
51 |
|
|
referring to them. |
52 |
|
|
|
53 |
|
|
Implementors are advised that, to be able to encode cyclic structures, |
54 |
|
|
it must be possible to refer to a value before it is completely |
55 |
|
|
decoded. For example, during decoding of a map, some entries can |
56 |
|
|
refer to the map being decoded. Thus an implementation cannot decode |
57 |
|
|
a shareable value and then record it for later references - it has to |
58 |
|
|
record the reference before decoding the value. |
59 |
|
|
|
60 |
|
|
This can be handled in a variety of ways. For example, in Perl, values |
61 |
|
|
not explicitly referenced (hash, array, scalar ref) can not (normally) |
62 |
|
|
be shared, so it only has to handle explicit references. Other shared |
63 |
|
|
values will usually become unshared, for effienciy reasons. |
64 |
|
|
|
65 |
|
|
Implementations that do not support sharing can duplicate the values |
66 |
|
|
after decoding, or they can use fix-up lists to fix shared references |
67 |
|
|
after decoding. |
68 |
|
|
|
69 |
|
|
=head2 IMPLEMENTATION NOTE |
70 |
|
|
|
71 |
|
|
The semantics of shareable/sharedref tags require the decoder to be |
72 |
|
|
aware and the encoder to be under control of the sequence in which data |
73 |
|
|
items are encoded into the CBOR stream. This means these tags cannot be |
74 |
|
|
implemented on top of every generic CBOR encoder/decoder (which might |
75 |
|
|
reorder entries in a map); they need to be integrated into their works. |
76 |
|
|
|
77 |
|
|
=head1 EXAMPLES |
78 |
|
|
|
79 |
|
|
<TBD> |
80 |
|
|
|