Shared Memory

class ZShm : public zenoh::Owned<::z_owned_shm_t>

An immutable SHM buffer.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

Constructors

inline ZShm(ZShmMut &&mut)

Create a new ZShm from ZShmMut.

Parameters:: mut – mutable buffer.

inline ZShm(const ZShm &other)

Create a new ZShm from ZShm by performing a shallow SHM reference copy.

Parameters:: other – ZShm to copy

Methods

inline const uint8_t *data() const

Get buffer’s const data. It is completely unsafe to to modify SHM data without using ZShmMut interface.

Returns:: pointer to the underlying data.

inline std::size_t len() const

Get buffer’s data size.

Returns:: underlying data size.

static inline std::optional<ZShmMut> try_mutate(ZShm &&immut)

Create a new ZShmMut from ZShm.

Parameters:: immut – immutable buffer, NOTE: the value will not be moved if nullopt returned.
Returns:: mutable buffer or empty option if buffer mutation is impossible.

static inline std::optional<std::reference_wrapper<ZShmMut>> try_mutate(ZShm &immut)

Create a new ZShmMut& from ZShm&.

Parameters:: immut – immutable buffer, NOTE: the value will not be moved if nullopt returned.
Returns:: mutable buffer or empty option if buffer mutation is impossible.

class ZShmMut : public zenoh::Owned<::z_owned_shm_mut_t>

A mutable SHM buffer.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

Methods

inline const uint8_t *data() const

Get buffer’s const data.

Returns:: pointer to the underlying data.

inline uint8_t *data()

Get buffer’s data.

Returns:: pointer to the underlying data.

inline std::size_t len() const

Get buffer’s data size.

Returns:: underlying data size.

class CppShmClient: An interface for making custom SHM clients.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

class ShmClient : public zenoh::Owned<::z_owned_shm_client_t>

An SHM client for reading shared memory buffers.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

Subclassed by zenoh::PosixShmClient

Constructors

inline ShmClient(std::unique_ptr<CppShmClient> &&cpp_interface): Create a new CPP-defined ShmClient.

class CppShmSegment: An interface for accessing custom SHM segments.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

class ShmClientStorage : public zenoh::Owned<::z_owned_shm_client_storage_t>

A storage for SHM clients. Session constructed with instance of this type gets capabilities to read SHM buffers for Protocols added to this instance.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

Constructors

static inline ShmClientStorage global(): Create ShmClientStorage referencing a default global list of SHM clients.

inline ShmClientStorage(): Creates ShmClient storage with zenoh-default set of SHM clients.

template<class Container, typename _T = std::enable_if<std::is_same<typename std::iterator_traits<typename Container::iterator>::value_type, std::pair<ProtocolId, ShmClient>>::value>> inline ShmClientStorage(Container &&container, bool add_default_client_set, ZResult *err = nullptr)

Create ShmClientStorage from a list of SHM clients.

Parameters:

container – arbitrary container of SHM clients. ShmClientStorage takes the ownership of the clients.
add_default_client_set – if true, the resulting ShmClientStorage will also include zenoh-default set of SHM clients
err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

template<class I, typename _T = std::enable_if<std::is_same<typename std::iterator_traits<I>::value_type, std::pair<ProtocolId, ShmClient>>::value>> inline ShmClientStorage(std::move_iterator<I> begin, std::move_iterator<I> end, bool add_default_client_set, ZResult *err = nullptr)

Create ShmClientStorage from a range of SHM clients.

Parameters:

begin – start iterator of SHM clients. ShmClientStorage takes the ownership of the clients.
end – end iterator of SHM clients.
add_default_client_set – if true, the resulting ShmClientStorage will also include zenoh-default set of SHM clients
err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

inline ShmClientStorage(const ShmClientStorage &other): Performs a shallow copy of ShmClientStorage.

class PosixShmClient : public zenoh::ShmClient 

Client factory implementation for particular shared memory protocol.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

Constructors

inline PosixShmClient(): Create a new PosixShmClient.

class PosixShmProvider : public zenoh::ShmProvider

An SHM provider implementing zenoh-standard POSIX shared memory protocol.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

Constructors

inline PosixShmProvider(const MemoryLayout &layout, ZResult *err = nullptr)

Create a new PosixShmProvider.

Parameters:

layout – layout for POSIX shared memory segment to be allocated and used by the provider
err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

class CppShmProvider : public zenoh::ShmProvider

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

Constructors

inline CppShmProvider(ProtocolId id, std::unique_ptr<CppShmProviderBackend> backend): Create a new CPP-defined ShmProvider.

inline CppShmProvider(ProtocolId id, std::unique_ptr<CppShmProviderBackendThreadsafe> backend): Create a new CPP-defined threadsafe ShmProvider.

class AllocLayout : public zenoh::Owned<::z_owned_alloc_layout_t>

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

Constructors

inline AllocLayout(const ShmProvider &owner_provider, std::size_t size, AllocAlignment alignment, ZResult *err = nullptr): Create a new Alloc Layout for SHM Provider.

class MemoryLayout : public zenoh::Owned<::z_owned_memory_layout_t>

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

Constructors

inline MemoryLayout(size_t size, AllocAlignment alignment, ZResult *err = nullptr)

Create a new MemoryLayout.

Parameters:

size – layout size.
alignment – layout alignment.
err – if not null, the result code will be written to this location, otherwise ZException exception will be thrown in case of error.

class ChunkAllocResult : public zenoh::Owned<::z_owned_chunk_alloc_result_t>

SHM chunk allocation result.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

Constructors

inline ChunkAllocResult(AllocatedChunk chunk)

Create a new ChunkAllocResult that carries successfuly allocated chunk.

Parameters:: chunk – allocated chunk.

inline ChunkAllocResult(AllocError error)

Create a new ChunkAllocResult that carries error.

Parameters:: error – allocation error.

typedef z_protocol_id_t zenoh::ProtocolId: Unique protocol identifier. Here is a contract: it is up to user to make sure that incompatible ShmClient and CppShmProviderBackend implementations will never use the same ProtocolID.

typedef z_segment_id_t zenoh::SegmentId: Unique segment identifier.

typedef z_chunk_id_t zenoh::ChunkId: Chunk id within it’s segment.

typedef z_chunk_descriptor_t zenoh::ChunkDescriptor: A ChunkDescriptor.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

typedef z_allocated_chunk_t zenoh::AllocatedChunk: An AllocatedChunk.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

typedef ::z_alloc_error_t zenoh::AllocError

Allocation errors.

NEED_DEFRAGMENT: defragmentation needed
OUT_OF_MEMORY: the provider is out of memory
OTHER: other error

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

typedef ::z_layout_error_t zenoh::LayoutError

Layouting errors.

Z_LAYOUT_ERROR_INCORRECT_LAYOUT_ARGS: layout arguments are incorrect
Z_LAYOUT_ERROR_PROVIDER_INCOMPATIBLE_LAYOUT: layout incompatible with provider

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

typedef ::z_alloc_alignment_t zenoh::AllocAlignment: An AllocAlignment.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

typedef std::variant<ZShmMut, AllocError> zenoh::BufAllocResult: SHM buffer allocation result.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

typedef std::variant<ZShmMut, AllocError, LayoutError> zenoh::BufLayoutAllocResult: SHM buffer layouting and allocation result.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.

inline void zenoh::cleanup_orphaned_shm_segments()

Linux: Trigger cleanup for orphaned SHM segments. If process that created named SHM segment crashes or exits by a signal, the segment persists in the system disregarding if it is used by other Zenoh processes or not. This is the detail of POSIX specification for shared memory that is hard to bypass. To deal with this we developed a cleanup routine that enumerates all segments and tries to find processes that are using it. If no such process found, segment will be removed. There is no ideal signal to trigger this cleanup, so by default, zenoh triggers it in the following moments:

first POSIX SHM segment creation
process exit via exit() call or return from maint function It is OK to additionally trigger this function at any time, but be aware that this can be costly.

For non-linux platforms this function currently does nothing.

Warning

This API has been marked as unstable: it works as advertised, but it may be changed in a future release.