Open questions on the mw::com Rust API

[awillenbuecher-xq-tec]

We gathered some questions and a few suggestions regarding the proposed Rust COM API in its current state (main_api_rs branch, commit 22ae299).

1. InstanceSpecifier struct:
   1. Is the concrete representation of the instance specifier dependant on the backend? If yes, it should instead be a trait: trait InstanceSpecifier<R: Runtime>. Otherwise, this struct should already contain the specifier as a field and not be empty.
   2. Is an InstanceSpecifier unique in a system? Otherwise, if several producers are allowed to use the same specifier, shouldn't it rather be called ServiceSpecifier or similar?
2. Runtime trait:
   1. This should be renamed. For example, to TransportLayer or IpcAdapter.
3. Producer/OfferedProducer:
   1. Is a producer already visible for service discovery, or is it visible only once it has been offered?
   2. Maybe replace the type distinction with internal offered flag? Having two different types makes it difficult to dynamically switch between those states: the current API would require deconstructing the producer/offered producer when making the switch.
   3. Can offer()/unoffer() block? If yes, should they be async? What are the exact semantics of those methods?
   4. What happens if a consumer doesn't release a sample? Will unoffer() block indefinitely? What if the consumer crashes while holding a sample?
4. ConsumerDescriptor:
   1. Shouldn't this rather be called ProducerDescriptor, since it's the result of service discovery? And its get_instance_id() method returns the ID of the producer, right?
5. Service discovery:
   1. Which kind of specifier is passed to find_service? Does it uniquely identify at most one producer, or can it identify a set of producers? If the latter, is the identifier allowed to contain wildcards?
6. Use of builder pattern:
   1. The Builder trait seems unnecessary. Why would you ever want to be generic over all possible builders? User seems to be overloaded in caliing build(). Something like Vec<&mut dyn Builder> doesn't really make sense.
   2. The ProducerBuilder trait shouldn't be a part of the COM API, since it's not being used by any other part of the COM API.
7. Architecture:
   1. Would a more convenient interface for building consumers also be acceptable, where the backend handles the service/producer discovery?
   2. Do we really want to always couple multiple single topics into one big interface? Looks like overhead.

It would be great if you could answer these questions, and we would be happy to start a discussion on the more complex issues.

[darkwisebear]

Hey @awillenbuecher-xq-tec I'll try to comment on your questions:

1. InstanceSpecifier. General comment: This one isn't finished yet, since the whole topic of service discovery isn't finished. But the goal of this one is to be binding independent, and therefore the most likely representation will be a simple string conveying all information needed.
2. Naming of Runtime: Agreed, but we deliberately excluded naming for now until the interface has settled, and called some things just like they're called in the C++ bindings, which is where Runtime was borrowed from.
3. Producer / OfferedProducer
   i. A producer is only visible once it has been offered. There is a concept called "implicit service discovery" that allows for the creation of consumers before the producers are available. However, there will be no communication before a respective OfferedProducer is available, and calls made will return an error / yield no data.
   ii. The distinction is intentional: We want to bind the lifetime of samples that are "in-flight" on producer side to the lifetime of the service offer. IOW, we do not want to have in-flight samples when the service gets withdrawn.
   iii. offer / unoffer must not block. We should add this in the docs.
   iv. If a consumer still holds a sample when the producer unoffers, the sample will be kept alive until the last consumer drops it. So an unoffer does not automatically destroy all resources; instead, consumers are allowed to keep references to already-sent data for as long as they need.
4. ConsumerDescriptor naming: Well, that's a matter of how you see it :) I get your point, but when we were naming this thing, it was a "lightweight descriptor of what the respective consumer is going to be". But since naming isn't settled yet, we can also discuss whether we change that. However, I'd be a bit concerned then that the users might think that the API belongs to the server side, which isn't true. get_instance_id refers to the producer's instance, correct.
5. SD: As said, SD isn't finished yet. We also need an async API here that notifies users of newly available services and allows for a non-blocking way to create client endpoints for newly available service. That said, find_service will return all currently available services in case you only specify the interface without specifying the exact instance. You could call this a wildcard, yes.
6. We wanted to stick to the builder pattern as that one is familiar to a lot of people. To enforce this,we also introduced the Builder trait as a means of also enforcing it through Rust's trait system. It might not be necessary "to get the job done", but it should lead to a consistent API. ProducerBuilder still being around might be a mistake, need to check that. I experimented quite a bit, so that might e some refactoring fallout.
7. Architecture
   i. We already discussed that we will most likely have a low level interface that caters all use cases, and a high level API that covers the "90% case". This one can and will be much more convenient. Example: We will have a "streaming consumer" at some point, which will be what 90% of the (async) users will want, but it sacrifices a bit of resources as we cannot "reuse" samples, which is what we sometimes do when querying for new data: In case there is noting new, just return what was there before. You can't do that with a streaming API. In the same way we could also ease the service discovery. But as I already said, SD is anyway unfinished, so we'll anyway add stuff in the upcoming design sessions.
   ii. Short answer is yes :) I'll bring more structure into your APIs, grouping things that are closely related. The interfaces do not necessarily have to be big, though. It's absolutely ok to have interfaces with just one member, but usually, big interfaces become hard to maintain, so usually a middle ground is the way to go.

[pawelrutkaq]

@darkwisebear one more questions. What is currently exact intent for VehicleInterface/*Interface ? Is it only marker type really that bounds service == (Interface + InstanceSpecifier)? Maybe it's shown somewhere, couldn't find it.

[darkwisebear]

@pawelrutkaq Correct, it's a marker trait that denotes that a certain (implementation specific, most lilkely generated) type fulfills a certain interface specification.