iceoryx - true zero-copy inter-process-communication

Introduction

Great that you’ve made it to this little Eclipse project! Let’s get you started by providing a quick background tour, introducing the project scope and all you need for installation and a first running example.

So first off: What is iceoryx?

iceoryx is an inter-process-communication (IPC) middleware for various operating systems (currently we support Linux, MacOS and QNX). It has its origins in the automotive industry, where large amounts of data have to be transferred between different processes when it comes to driver assistance or automated driving systems. However, the efficient communication mechanisms can also be applied to a wider range of use cases, e.g. in the field of robotics or game development.

iceoryx uses a true zero-copy, shared memory approach that allows to transfer data from publishers to subscribers without a single copy. This ensures data transmissions with constant latency, regardless of the size of the payload. For more information have a look at the 1000 words iceoryx introduction

You’re right, middleware is a cluttered term and can somehow be all or nothing, so let’s talk about the goals and non-goals of iceoryx.

It’s all about the API?!

Don’t get too frighten of the API when strolling through the codebase. Think of iceoryx’s API as a “plumbing” one (“plumbing” as defined in Git, which means low-level). We’re not using the “plumbing” API ourselves, but instead a typed API. The normal use case is that iceoryx is integrated as high-performance IPC transport layer in a bigger framework with additional API layers. An example for such a “porcelain” API would be ROS2. Others are listed in the next section.

You can find the full API documentation on 🌐 https://iceoryx.io.

Where is Eclipse iceoryx used?

Build and install

You can find the build and installation guidelines here.

Examples

After you’ve built all the necessary things, you can continue playing around with the examples.

Build and run in a Docker environment

If you want to avoid installing anything on your host machine but you have Docker installed, it is possible to use it to build and run iceoryx applications.

Please see the dedicated README.md for information on how to do this.

Documentation

• Getting Started
• Installation Guide
• Concepts
• Iceoryx Utils Hacker Guide

Targeted quality levels & platforms

Quality level are 5 to 1, where 1 is highest level.

Is something missing or you’ve got ideas for other nifty examples? Jump right away to the next section!

Contribute

Please refer to the CONTRIBUTING.md for a quick read-up about what to consider if you want to contribute.

Planned features

File truncated at 100 lines see the full file

Contributing to Eclipse iceoryx

Thanks for your interest in this project.

Project description

In domains like automotive, robotics or gaming, a huge amount of data must be transferred between different parts of the system. If these parts are actually different processes on a POSIX based operating system like Linux, this huge amount of data has to be transferred via an inter-process-communication (IPC) mechanism. Find more infos on the Eclipse site.

Eclipse Contributor Agreement

Before your contribution can be accepted by the project team, contributors must electronically sign the Eclipse Contributor Agreement (ECA).

Commits that are provided by non-committers must have a Signed-off-by field in the footer indicating that the author is aware of the terms by which the contribution has been provided to the project. The non-committer must additionally have an Eclipse Foundation account and must have a signed Eclipse Contributor Agreement (ECA) on file.

For more information, please see the Eclipse Committer Handbook.

Contact

Contact the project developers via the project’s “dev” list.

• iceoryx-dev@eclipse.org

Feature request and bugs

We love pull requests! The next sections try to cover most of the relevant questions. For larger contributions or architectural changes, we’d kindly ask you to either:

• Raise the proposed changes during a developer meetup

or

• Create a design document and raise it in a separate pull request beforehand

If you would like to report a bug or propose a new feature, please raise an issue before raising a pull request. Please have a quick search upfront if a similar issue already exists. An release board is used to prioritize the issues for a specific release. This makes it easier to track the work-in-progress. If you have troubles getting an issue assigned to you please contact the maintainers via Gitter.

Please make sure you have:

1. Signed the Eclipse Contributor Agreement
2. Created an issue before creating a branch, e.g. Super duper feature with issue number 123
3. All branches have the following naming format: iox-#[issue]-branch-name e.g. iox-#123-super-duper-feature
4. All commits have the following naming format: iox-#[issue] commit message e.g. iox-#123 implemented super-duper feature
5. All commits have been signed with git commit -s
6. You open your pull request towards the base branch staging
7. Link the pull request to the according Github issue and set the label accordingly

Coding style

We love the C++ core guidelines. If in doubt please try to follow them as well as our unwritten conventions in the existing parts of the code base. Please format your code with the provided clang-format and clang-tidy before raising a pull request. Lots of IDEs do read the clang-format file these days.

We created some convenient rules to highlight some bits that you might not be used to in other FOSS projects. They are helpful to build embedded systems for safety fields like automotive or avionics. It is possible that not the whole codebase follows these rules, things are work in progress.

1) No heap is allowed, static memory management hugely decreases the complexity of your software (e.g. cxx::vector without heap) 2) No exceptions are allowed, all function and methods need to have noexcept in their signature 3) No undefined behavior, zero-cost abstract is not feasible in high safety environments 4) Use C++14 5) Rule of Five, if there is a non-default destructor needed, the rule of five has to be applied 6) STL, we aim to be compatible towards the STL, but our code may contain additions which are not compatible with the STL (e.g. iox::cxx::vector::emplace_back() does return a bool) 7) Always use iox::log::Logger, instead of printf() 8) Always use iox::ErrorHandler(), when an error occurs that cannot or shall not be propagated via an iox::cxx::expected, the iox::ErrorHandler() shall be used; exceptions are not allowed

See error-handling.md for additional information about logging and error handling.

Naming conventions

• File names with lower_snake_case: my_thing.hpp
• Structs, classes and enum classes in UpperCamelCase: class MyClass{}
• Methods and variables in lowerCamelCase: uint16_t myVariable
• Compile time constants, also enum values in UPPER_SNAKE_CASE: static constexpr uint16_t MY_CONSTANT
• Class members start with m_: m_myMember
  • Public members of structs and classes do not have the m_ prefix
• Namespaces in lower_snake_case : my_namespace
• Aliases have a _t postfix : using FooString_t = iox::cxx::string<100>;

Doxygen

File truncated at 100 lines see the full file