Provide API for querying the availability of fields

Open
#140 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Stale
Tech stack
c, python

Research direction

Start by reading the serialization and deserialization code generation paths and the generated C representation for DSDL types; the issue does not name specific files or tests. Work through how field availability should be represented for nested structures and arrays, then define what counts as available for partial fields. Done means generated deserialization can report field availability consistently for the cases described.

Written by the indexing model from the issue text.

Description

feature

This is based on DDS XTYPES and MAVLink v2 in general and @tridge's comment on the UAVCAN forum in particular:

I’m thinking of adding an API that allows the recipient to ask if a specific field was provided. Something like this for C:

bool mavlink_msg_extension_available(const mavlink_message_t *msg, uint8_t field_offset);

used like this:

bool freemem32_available = mavlink_msg_extension_available(msg, offsetof(mavlink_meminfo_t, freemem32));

the basic idea is that the mavlink_message_t does already have the information needed to tell the caller if a particular field came from zero-fill or not, we just don’t have a convenient API for consumers of the extensions at the moment.

I think the same idea could work for extensions in UAVCAN v1.

Given Foo.1.0:

uint8 a

And Foo.1.1:

uint8 a
float32 b

A subscriber should be able to query if b is populated in the received message. This information is derivable either from the message length or from the delimiter header (in case of nested types). Nunavut should emit code for that, but it would be a mistake to rely on offsetof due to its inadmissibility in high-rel code. Instead, it may be wiser to extend the deserialization code with an option to provide an extra argument that would store the field availability data. The type of that argument could also be generated (more on this later). It is also possible to implement dedicated field availability query functions like "here's my serialized representation, tell me if it contains a field such and such", but it is trivial to see that in order to answer that question one would have to deserialize the representation first, so it's best to avoid the double effort and combine both actions in one operation.

There are edge cases that need to be considered though. In the example above, b is available if the length of the serialized representation is >=5 bytes. It is not available if the length is <=1 byte. What if the length is 2...5 bytes? It probably makes sense to assume that the field is not available in this case.

But what if instead of float32 there was a nested structure where some of the last fields were missing? As long as some of the fields are available, should we not say that the structure itself is available? In this case, it would make sense to assume the opposite of the above.

Another ambiguity arises with arrays, either fixed-size or variable. If we publish this:

uint8[2] a

And deserialize this:

uint8[3] a

Do we expose the information about the availability of a[2]? The same question holds for variable-size entities.


Above I mentioned auto-generating types for storing the field availability information. What I mean is that if we take the following type named Bar.1.0:

uint8 x
float32[8] y
Foo.1.1 z

...its own representation in C would be as follows:

typedef struct namespace_Bar_1_0 {
    uint8_t x;
    float y[8];
    namespace_Foo_1_1 z;
} namespace_Bar_1_0;

And then the availability could be expressed like:

typedef struct namespace_Bar_1_0_FieldAvailability {
    bool x;
    bool y[8];                              // XXX: what if y was variable-length?
    namespace_Foo_1_1_FieldAvailability z;  // XXX: how do we express the availability of z itself?
} namespace_Bar_1_0_FieldAvailability;

Languages that are less limited in their capabilities obviously provide far more options for handling this, but if we start with C it should be easier to stay consistent for all languages because what can be expressed using the limited type system of C can certainly be expressed anywhere else.

P.S. this is enabled by https://github.com/UAVCAN/specification/pull/97

Dominant language
Python
Stars
48
Forks
26
Avg merge
1d 18h
Merged PRs (30d)
9

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from OpenCyphal/nunavut

All issues in OpenCyphal/nunavut

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.