pub enum WirePosition {
Member,
Element,
Discriminator,
KeyHolderMember,
Sentinel,
ExtendedMarker,
}Expand description
Where a wchar is reached from.
The one axis WcharFraming varies along, and the reason it exists
is a measurement rather than a symmetry: tao_idl writes GIOP 1.2’s
length octet for a wchar member and no length octet for a wchar
inside an array or a sequence. Nothing else in this crate’s layout
varies with position, so this enum is deliberately small and
deliberately not a general traversal context.
Variants§
Member
Reached as a member of a structure, a union branch, or as the whole of a top-level value. The default, because it is the position every value was in before collections were measured.
Measured on WcharFraming — tao_idl writes GIOP 1.2’s
length octet here and not at Self::Element — and on
WstringLengthPolicy, where it is measured to agree with
Self::Element in all nine implementations.
Element
Reached as an element of an array or a sequence.
A wstring’s code units are not this: they are not wchars
on the wire at all and are laid out by WstringLengthPolicy.
Measured on WcharFraming and on
WstringLengthPolicy; see Self::Member.
Discriminator
The discriminator of a union.
Prospective. No axis has been measured to answer this
differently from Self::Member. It is here because a
discriminator is reached by a path of its own in every emitter,
so an axis that starts varying with it has somewhere to say so
without a signature change.
KeyHolderMember
A key holder’s copy of a member.
Prospective. KeyHolderExtensibility and
KeyHolderOrder are today whole-holder settings rather than
per-position ones; if a per-member difference is ever measured
this is where it lands.
Sentinel
The sentinel that closes an XCDR1 parameter list.
Measured on PidFlagPolicy, which is the axis that reads
this variant: PidFlagPolicy::must_understand_at and
PidFlagPolicy::impl_extension_at both take a position, the
writer asks them at Self::Member for a member id and here for
PID_LIST_END, and the four implementations’ answers differ
between the two positions. The measurement is on
PidFlagPolicy.
ExtendedMarker
The PID_EXTENDED marker that opens an XCDR1 parameter’s
extended header.
Measured on PidFlagPolicy. The flag was
PlCdr1HeaderPolicy::marker_must_understand, on the argument
that the marker exists only under
PlCdr1HeaderPolicy::AlwaysExtended and its flag is therefore
a property of the form. Eight recorded rows contradict that:
xcdr.rs::needs_extended_pid writes the marker under
PlCdr1HeaderPolicy::Specification too — for a member id above
PID_SHORT_MAX_ID or a value the short length cannot hold — and
the four implementations answer it as follows, on
annotation-hashid-implicit and annotation-id-sparse:
implementation framing form the marker
Cyclone AlwaysExtended 7f01
RTI Specification 7f01
Fast DDS ShortTrueLength 3f01
OpenDDS ShortTrueLength ff01 — with FLAG_IMPL_EXTENSIONTwo forms answer alike and two forms answer differently, which is
judgement 3 of docs/wire-axes-followup.md: a field two forms
answer differently and two forms answer alike is not a field of
the form. The three PidFlagPolicy values answer all four
implementations here with no fourth value.
Implementations§
Source§impl WirePosition
impl WirePosition
Sourcepub const MEASURED: [Self; 4]
pub const MEASURED: [Self; 4]
The positions on which some axis has a measured difference or a measured agreement, as against those carried prospectively.
Kept apart because measured and provided-for must not look alike:
a reader who cannot tell them apart reads the next measurement as
a confirmation of something that was never checked.
Self::Member and Self::Element are measured on
WcharFraming (they differ) and on WstringLengthPolicy
(they agree, in nine implementations); Self::Sentinel and
Self::ExtendedMarker are measured on PidFlagPolicy, which
reads both. The other two are prospective.
Sourcepub const fn is_measured(self) -> bool
pub const fn is_measured(self) -> bool
Whether some axis has been measured at this position.
Sourcepub const fn inside_collection() -> Self
pub const fn inside_collection() -> Self
The position an element of a collection is reached in.
A named constructor rather than a literal at the call sites so
that “descending into a collection” is one decision written once:
a sequence of arrays of wchar reaches the same answer as an
array of wchar, and neither has to say so itself.
Sourcepub const fn inside(self) -> Self
pub const fn inside(self) -> Self
The position the members of an aggregate are reached in.
An aggregate resets the position: a wchar member of a struct
that is itself an array element takes the member’s framing,
because tao_idl reaches it through the struct’s own marshaller.
Unmeasured against TAO — the corpus has no such case — and it is
the reading the generated code’s shape gives, recorded here so
that the day a case is added there is something to contradict.