=head1 REGISTRATION INFORMATION

   Tag             <unassigned> (shareable)
   Data Item       multiple
   Semantics       mark value as (potentially) shared
   Reference       http://cbor.schmorp.de/value-sharing
   Contact         Marc A. Lehmann <cbor@schmorp.de>

   Tag             <unassigned> (sharedref)
   Data Item       unsigned integer
   Semantics       reference nth marked value
   Reference       http://cbor.schmorp.de/value-sharing
   Contact         Marc A. Lehmann <cbor@schmorp.de>

=head1 SUMMARY

These two tags can be used to implement shared value support in CBOR.

=head1 RATIONALE

Many serialisable data structures can contain values that are
shared. For example, in Perl, you could have an array with two hash
references pointing to the same object.

When serialising these data structures to CBOR, these values either
become unshared (duplicated), or, when the structure contains cycles,
they are not serialisable into CBOR at all.

This extension implements explicit shared value support - encoders need
to explicitly mark values as potentially shared and can later refer to
them.

This extension is not meant to save space in the CBOR representation by
encoding duplicated values only once - the shared values are supposed
to refer to the same value after decoding (e.g. when implemented as a
pointer, all references to the value should point to the same memory
object).

=head1 DESCRIPTION

To share values, the first occurrence of the value must be explicitly
tagged with the shareable tag (value <unassigned>).

Subsequent occurrences can then be encoded by encoding the index
of a previously marked value tagged with the sharedref tag (value
<unassigned>). That is, index 0 refers to the first value marked as
shareable in the CBOR stream, index 1 to the second and so on.

There is no requirement to actually refer to a value marked as
shareable - encoders can mark any value they want without ever
referring to them.

Implementors are advised that, to be able to encode cyclic structures,
it must be possible to refer to a value before it is completely
decoded. For example, during decoding of a map, some entries can
refer to the map being decoded. Thus an implementation cannot decode
a shareable value and then record it for later references - it has to
record the reference before decoding the value.

This can be handled in a variety of ways. For example, in Perl, values
not explicitly referenced (hash, array, scalar ref) can not (normally)
be shared, so it only has to handle explicit references. Other shared
values will usually become unshared, for effienciy reasons.

Implementations that do not support sharing can duplicate the values
after decoding, or they can use fix-up lists to fix shared references
after decoding.

=head2 IMPLEMENTATION NOTE

The semantics of shareable/sharedref tags require the decoder to be
aware and the encoder to be under control of the sequence in which data
items are encoded into the CBOR stream. This means these tags cannot be
implemented on top of every generic CBOR encoder/decoder (which might
reorder entries in a map); they need to be integrated into their works.

=head1 EXAMPLES

<TBD>