Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[#436] Add to the FAQ how to define a custom type; Add type restricti… #447

Merged
merged 2 commits into from
Oct 7, 2024
Merged

[#436] Add to the FAQ how to define a custom type; Add type restricti… #447

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
775f570
[#436] Add to the FAQ how to define a custom type; Add type restricti…
elfenpiff Oct 7, 2024
2fa30ab
[#436] Rephrase install instructions; add release notes for signal ha…
elfenpiff Oct 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 32 additions & 2 deletions FAQ.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,34 @@ To address this, iceoryx2 provides shared-memory-compatible data types. You
can refer to the [complex data types example](examples/rust/complex_data_types),
which demonstrates the use of `FixedSizeByteString` and `FixedSizeVec`.

## How To Define Custom Data Types (Rust)

1. Ensure to only use data types suitable for shared memory communication like
pod-types (plain old data, e.g. `u64`, `f32`, ...) or explicitly
shared-memory compatible containers like some of the constructs in the
`iceoryx2-bb-containers`.
2. Add `#[repr(C`)]` to your custom data type so that it has a uniform memory
representation.

```rust
#[repr(C)]
struct MyDataType {
//....
}
```

3. **Do not use pointers, or data types that are not self-contained or use
pointers for their internal management!**

## How To Define Custom Data Types (C++)

1. Ensure to only use data types suitable for shared memory communication like
pod-types (plain old data, e.g. `uint64_t`, `int32_t`, ...) or explicitly
shared-memory compatible containers like some of the constructs in the
`iceoryx-hoofs`.
2. **Do not use pointers, or data types that are not self-contained or use
pointers for their internal management!**

## How To Send Data Where The Size Is Unknown At Compilation-Time?

Take a look at the
Expand All @@ -30,10 +58,12 @@ insufficient, a new publisher with a larger `max_slice_len` can be created.

<!-- markdownlint-disable -->

> [!IMPORTANT] Be aware that the history of the old publisher is lost when it is
> [!IMPORTANT]
> Be aware that the history of the old publisher is lost when it is
> removed.

> [!NOTE] We are also working on an API that does not require the user to
> [!NOTE]
> We are also working on an API that does not require the user to
> explicitly create a new publisher whenever the memory is insufficient. It
> would also solve the history issue.

Expand Down
2 changes: 2 additions & 0 deletions doc/release-notes/iceoryx2-unreleased.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,8 @@
conflicts when merging.
-->

* Split SignalHandler signals to avoid infinite loops on SIGSEGV
[#436](https://github.com/eclipse-iceoryx/iceoryx2/issues/436)
* Fix misleading warning related to default config file
[#437](https://github.com/eclipse-iceoryx/iceoryx2/issues/437)

Expand Down
24 changes: 12 additions & 12 deletions examples/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,15 +70,15 @@ These types are demonstrated in the complex data types example.

## Overview

| Name | Language | Description |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| complex data types | [Rust](rust/complex_data_types) | Send zero-copy compatible versions of `Vec` and `String`. Introduces `PlacementDefault` trait for large data types to perform an in place initialization where otherwise a stack overflow would be encountered. |
| discovery | [C](c/discovery) [C++](cxx/discovery) [Rust](rust/discovery) | List all available services in a system. |
| docker | [all](rust/docker) | Communicate between different docker containers and the host. |
| domains | [C](c/domains) [C++](cxx/domains) [Rust](rust/domains) | Establish separate domains that operate independently from one another. |
| event | [C](c/event) [C++](cxx/event) [Rust](rust/event) | Push notifications - send event signals to wakeup processes that are waiting for them. |
| event multiplexing | [Rust](rust/event_multiplexing) | Wait on multiple listeners or sockets with a single call. The WaitSet demultiplexes incoming events and notifies the user. |
| publish subscribe | [C](c/publish_subscribe) [C++](cxx/publish_subscribe) [Rust](rust/publish_subscribe) | Communication between multiple processes with a [publish subscribe messaging pattern](https://en.wikipedia.org/wiki/Publish–subscribe_pattern). |
| publish subscribe dynamic data | [Rust](rust/publish_subscribe_dynamic_data) | Communication between multiple processes with a [publish subscribe messaging pattern](https://en.wikipedia.org/wiki/Publish–subscribe_pattern) and payload data that has a dynamic size. |
| publish subscribe with user header | [C](c/publish_subscribe_with_user_header) [C++](cxx/publish_subscribe_with_user_header) [Rust](rust/publish_subscribe_with_user_header) | Add a user header to the payload (samples) to transfer additional information. |
| service attributes | [Rust](rust/service_attributes) | Creates a service with custom attributes that are available to every endpoint. If the attributes are not compatible the service will not open. |
| Name | Language | Description |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| complex data types | [C++](cxx/complex_data_types) [Rust](rust/complex_data_types) | Send zero-copy compatible versions of `Vec` and `String`. Introduces `PlacementDefault` trait for large data types to perform an in place initialization where otherwise a stack overflow would be encountered. |
| discovery | [C](c/discovery) [C++](cxx/discovery) [Rust](rust/discovery) | List all available services in a system. |
| docker | [all](rust/docker) | Communicate between different docker containers and the host. |
| domains | [C](c/domains) [C++](cxx/domains) [Rust](rust/domains) | Establish separate domains that operate independently from one another. |
| event | [C](c/event) [C++](cxx/event) [Rust](rust/event) | Push notifications - send event signals to wakeup processes that are waiting for them. |
| event multiplexing | [Rust](rust/event_multiplexing) | Wait on multiple listeners or sockets with a single call. The WaitSet demultiplexes incoming events and notifies the user. |
| publish subscribe | [C](c/publish_subscribe) [C++](cxx/publish_subscribe) [Rust](rust/publish_subscribe) | Communication between multiple processes with a [publish subscribe messaging pattern](https://en.wikipedia.org/wiki/Publish–subscribe_pattern). |
| publish subscribe dynamic data | [Rust](rust/publish_subscribe_dynamic_data) | Communication between multiple processes with a [publish subscribe messaging pattern](https://en.wikipedia.org/wiki/Publish–subscribe_pattern) and payload data that consists of a slice of shared memory compatible types. |
| publish subscribe with user header | [C](c/publish_subscribe_with_user_header) [C++](cxx/publish_subscribe_with_user_header) [Rust](rust/publish_subscribe_with_user_header) | Add a user header to the payload (samples) to transfer additional information. |
| service attributes | [Rust](rust/service_attributes) | Creates a service with custom attributes that are available to every endpoint. If the attributes are not compatible the service will not open. |
4 changes: 2 additions & 2 deletions examples/c/discovery/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Discovery

Please install all dependencies first, as described in the
[C Examples Readme](../README.md).
Before proceeding, all dependencies need to be installed. You can find
instructions in the [C Examples Readme](../README.md).

## Running The Example

Expand Down
4 changes: 2 additions & 2 deletions examples/c/domains/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Domains

Please install all dependencies first, as described in the
[C Examples Readme](../README.md).
Before proceeding, all dependencies need to be installed. You can find
instructions in the [C Examples Readme](../README.md).

Let's assume you want to create multiple iceoryx2 groups of processes where the
processes inside a group can communicate and interact with each other. However,
Expand Down
4 changes: 2 additions & 2 deletions examples/c/event/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Event

Please install all dependencies first, as described in the
[C Examples Readme](../README.md).
Before proceeding, all dependencies need to be installed. You can find
instructions in the [C Examples Readme](../README.md).

## Running The Example

Expand Down
4 changes: 2 additions & 2 deletions examples/c/publish_subscribe/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Publish-Subscribe

Please install all dependencies first, as described in the
[C Examples Readme](../README.md).
Before proceeding, all dependencies need to be installed. You can find
instructions in the [C Examples Readme](../README.md).

## Running The Example

Expand Down
4 changes: 2 additions & 2 deletions examples/c/publish_subscribe_with_user_header/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Publish-Subscribe With User Header

Please install all dependencies first, as described in the
[C Examples Readme](../README.md).
Before proceeding, all dependencies need to be installed. You can find
instructions in the [C Examples Readme](../README.md).

## Running The Example

Expand Down
45 changes: 45 additions & 0 deletions examples/cxx/complex_data_types/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# Complex Data Types

Before proceeding, all dependencies need to be installed. You can find
instructions in the [C++ Examples Readme](../README.md).

## Running The Example

> [!CAUTION]
> Every payload you transmit with iceoryx2 must be compatible with shared
> memory. Specifically, it must:
>
> * be self contained, no heap, no pointers to external sources
> * not use pointers to manage their internal structure

This example demonstrates how the zero-copy compatible versions of
`std::vector` or `std::string` can be sent.
The library
[iceoryx_hoofs](https://github.com/eclipse-iceoryx/iceoryx/tree/main/iceoryx_hoofs)
provides versions that are shared memory compatible like the
`iox::string` and the `iox::vector`.

First you have to build the C++ examples:

```sh
cmake -S . -B target/ffi/build -DBUILD_EXAMPLES=ON
cmake --build target/ffi/build
```

To see the example in action, open a terminal and enter:

```sh
./target/ffi/build/examples/cxx/complex_data_types/example_cxx_complex_data_types
```

**Note:** The example can be started up to 16 times in parallel. The subscriber
would then receive the samples from every publisher from every running instance.

## How To Define Custom Data Types

1. Ensure to only use data types suitable for shared memory communication like
pod-types (plain old data, e.g. `usize`, `f32`, ...) or explicitly
shared-memory compatible containers like some of the constructs in the
`iceoryx-hoofs`.
2. **Do not use pointers, or data types that are not self-contained or use
pointers for their internal management!**
4 changes: 2 additions & 2 deletions examples/cxx/discovery/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Discovery

Please install all dependencies first, as described in the
[C++ Examples Readme](../README.md).
Before proceeding, all dependencies need to be installed. You can find
instructions in the [C++ Examples Readme](../README.md).

## Running The Example

Expand Down
4 changes: 2 additions & 2 deletions examples/cxx/domains/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Domains

Please install all dependencies first, as described in the
[C++ Examples Readme](../README.md).
Before proceeding, all dependencies need to be installed. You can find
instructions in the [C++ Examples Readme](../README.md).

Let's assume you want to create multiple iceoryx2 groups of processes where the
processes inside a group can communicate and interact with each other. However,
Expand Down
4 changes: 2 additions & 2 deletions examples/cxx/event/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Event

Please install all dependencies first, as described in the
[C++ Examples Readme](../README.md).
Before proceeding, all dependencies need to be installed. You can find
instructions in the [C++ Examples Readme](../README.md).

## Running The Example

Expand Down
18 changes: 16 additions & 2 deletions examples/cxx/publish_subscribe/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,24 @@
# Publish-Subscribe

Please install all dependencies first, as described in the
[C++ Examples Readme](../README.md).
Before proceeding, all dependencies need to be installed. You can find
instructions in the [C++ Examples Readme](../README.md).

## Running The Example

> [!CAUTION]
> Every payload you transmit with iceoryx2 must be compatible with shared
> memory. Specifically, it must:
>
> * be self contained, no heap, no pointers to external sources
> * have a uniform memory representation -> `#[repr(C)]`
> * not use pointers to manage their internal structure
>
> Data types like `std::string` or `std::vector` will cause undefined behavior
> and may result in segmentation faults. We provide alternative data types
> that are compatible with shared memory. See the
> [complex data type example](../complex_data_types) for guidance on how to
> use them.

This example illustrates a robust publisher-subscriber communication pattern
between two separate processes. The publisher sends two messages every second,
each containing [`TransmissionData`]. On the receiving end, the subscriber
Expand Down
18 changes: 16 additions & 2 deletions examples/cxx/publish_subscribe_with_user_header/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,24 @@
# Publish-Subscribe With User Header

Please install all dependencies first, as described in the
[C++ Examples Readme](../README.md).
Before proceeding, all dependencies need to be installed. You can find
instructions in the [C++ Examples Readme](../README.md).

## Running The Example

> [!CAUTION]
> Every payload you transmit with iceoryx2 must be compatible with shared
> memory. Specifically, it must:
>
> * be self contained, no heap, no pointers to external sources
> * have a uniform memory representation -> `#[repr(C)]`
> * not use pointers to manage their internal structure
>
> Data types like `std::string` or `std::vector` will cause undefined behavior
> and may result in segmentation faults. We provide alternative data types
> that are compatible with shared memory. See the
> [complex data type example](../complex_data_types) for guidance on how to
> use them.

This example illustrates a publisher-subscriber communication pattern between
two separate processes with an additional user header, referred to as a
`CustomHeader`. The publisher sends messages every second, each containing an
Expand Down
21 changes: 11 additions & 10 deletions examples/rust/complex_data_types/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,18 @@

## Running The Example

This example demonstrates how the zero-copy compatible versions of `Vec` or
`String` can be sent. All data types that are used as building blocks for
communication must:

* be self contained, no heap, no pointers to external sources
* have a uniform memory representation -> `#[repr(C)]`
* not use pointers to manage their internal structure
> [!CAUTION]
> Every payload you transmit with iceoryx2 must be compatible with shared
> memory. Specifically, it must:
>
> * be self contained, no heap, no pointers to external sources
> * have a uniform memory representation -> `#[repr(C)]`
> * not use pointers to manage their internal structure

This excludes many types Rust offers via its standard library. The crate
`iceoryx2-bb-container` provides versions that satisfy the strict zero-copy
requirements like `FixedSizeVec` and `FixedSizeByteString`.
This example demonstrates how the zero-copy compatible versions of `Vec` or
`String` can be sent.
The crate `iceoryx2-bb-container` provides versions that are shared memory
compatible like `FixedSizeVec` and `FixedSizeByteString`.

**Note**:** There also exist more advanced types called `Relocatable**`, that
will become the basic building blocks for dynamic-sized messages in iceoryx2, so
Expand Down
Loading
Loading