Document compatibility guarantees

[jayhf]

This falls under the umbrella of #450, but one specific piece of information I couldn't find anywhere is what guarantees Iceoryx2 makes regarding protocol stability across versions, which is important for making decisions about how and where we can use Iceoryx2. If I build two applications with two different versions of each other, should I expect them to be able to communicate with each other, assuming one isn't using a new feature not supported by the other? If so, will you ever make breaking changes and how will these correspond with release version numbers?

[elfenpiff]

@jayhf, we aim to provide clear guarantees as we progress towards v1.0.

If I build two applications with two different versions of each other, should I expect them to be able to communicate with each other, assuming one isn't using a new feature not supported by the other?

Currently, all processes must use the same iceoryx2 version. For instance, a publisher built with iceoryx2 v0.3 will be incompatible with a subscriber built with iceoryx2 v0.4 and will report an incompatibility error. However, in the future, we plan to decouple the iceoryx2 version from its protocol version.

In the future, we will introduce an iceoryx2 protocol version number so that the iceoryx2 version is not strictly coupled to the protocol version. Here the idea is that the protocol itself is specified in detail so that in theory another 3rd party client could follow the specification and be able to participate in the communication. Also an iceoryx2 version could then be compiled with a specific iceoryx2 protocol version.

If so, will you ever make breaking changes and how will these correspond with release version numbers?

Until we have reached v1.0 there will be breaking changes and I think afterwards, there may still be breaking changes with new protocol version but this will be unlikely. But just for some context, even though we did not yet have reached v1.0 the pub/sub pattern is pretty much stable since some key design elements originated from iceoryx1 which are very well proven in use.

The Protocol

It will contain the structure of the underlying communication mechanisms and how they are structured in memory. Additionally, we will write an iceoryx2 independent test suite that verifies the correctness of the iceoryx2 protocol inside iceoryx2. This also will identify breaking changes between versions if they ever happen.
Additionally, the protocol will contain the definition of data types like a vector or a string. The idea is that when using shared-memory you do not need payload serialization at all and since it is memory and CPU intensive we should also strive to avoid it at all costs. Therefore, we provide shared-memory compatible data types like Vec, ByteString (Rust) or iox::vector and iox::string (C++). Those data types have a language idiomatic interface but the underlying data structure will be memory-compatible with each other.

Meaning

// rust
#[derive(ShmSend)]
struct MyDataType {
  data_1: FixedSizeVec<u64, 1024>,
  data_2: FixedSizeByteString<128>
  data_3: RelocatableVec<uint64_t>,
}

and

// C++
struct MyDataType {
  iox::fixed_size_vector<uint64_t, 1024> data_1;
  iox::fixed_size_byte_string<128> data_2;
  iox::relocatable_vector<uint64_t> data_3;
};

are in memory identical and can be received, send, modified by C++ and Rust.

Long-term support

We at (ekxide.io, contact ([email protected])) pursue an open-core business strategy. To address the problem of long-term compatibility and bug fixes, we also offer that a specific iceoryx2 version will get support from us, even when the open-source support has ended. This means it will run in our internal CI, bug-fixes are back-ported as well as features (when feasible).

which is important for making decisions about how and where we can use Iceoryx2.

I am interested in your use case. Can you tell us a bit more about it?

[jayhf]

Thanks @elfenpiff! Appreciate your detailed answer here. I'm just looking for a cross platform shared memory pub/sub library for Rust (and potentially other languages). Future compatibility is important to us because it means we can use iceoryx2 in a microservice architecture and update services without breaking the system.

[elfenpiff]

@jayhf, we have the micro-service use case on our radar, and by v1.0, we will have a strategy defined for ensuring protocol stability and providing a smooth migration path when multiple protocol versions are required.

Community feedback would be invaluable when we design the protocol strategy! Would you be opened to review it by considering your use case so that we can identify weak points early and have something that can be actually used?

[jayhf]

Yes, I think I'd be happy to review it!

[elBoberido]

@jayhf would it be an option to just link to the shared libraries? Of course, this would lead to the weird situation that we need a Rust Wrapper for the C binding. But it would be much more robust to use the same shared library for every application.

[jayhf]

For our use case, we'd strongly prefer a stable protocol to a stable C library for a few reasons:

• A C library would presumably add a system dependency which would be an extra thing to manage anywhere these services are deployed. Adds an extra opportunity for version incompatibility.
• We heavily use nix which is really good at making sure every package gets the right dependency versions, but also means there isn't one system version to link against. On the plus side it makes it easier to ensure multiple packages build with the same version of the library, but this doesn't work as well for native Rust projects that might have Cargo.lock pinned to different versions or for a complicated project I have to build outside of nix for now that bundles its own dependencies.
• C libraries add build complexity to Rust projects and may make cross compilation etc. more difficult

We've built an in house shared memory pub/sub framework in Rust and recently switched to using protobuf as part of the interface to ensure compatibility across versions. I'm investigating iceoryx2 to get better cross platform support