iceoryx2

Python language bindings for iceoryx2.

class iceoryx2.ActiveRequest

Bases: object

The ActiveRequest represents the object that contains the payload that the Client sends to the Server.

delete()

Releases the ActiveRequest and terminates the connection.

After this call the ActiveRequest is no longer usable!

has_disconnect_hint

Returns True if the Client wants to gracefully disconnect. This allows the Server to send its last response and then drop the ActiveRequest to signal the Client that no more ResponseMut will be sent.

header

Returns the RequestHeader of the received RequestMut

is_connected

Returns True until the PendingResponse goes out of scope on the Client’s side indicating that the Client no longer receives the ResponseMut.

loan_flatbuffer() → ResponseMutUninit

Loans/allocates a ResponseMutUninit from the underlying data segment of the Server with an integrated flatbuffer builder.

loan_slice_uninit(number_of_elements: int) → ResponseMutUninit

Loans/allocates memory from the underlying data segment.

The user has to initialize the payload before it can be sent. Fails when it is called for data types which are not a slice. On failure it returns LoanError describing the failure.

loan_uninit() → ResponseMutUninit

Loans/allocates memory from the underlying data segment.

The user has to initialize the payload before it can be sent. On failure it returns LoanError describing the failure.

origin

Returns the UniqueClientId of the Client

payload() → Any

Returns the payload of the request.

It is a Slice when the payload type is a Slice, otherwise a ctypes.POINTER to the payload type.

payload_bytes() → Slice[c_ubyte]

Returns the serialized flatbuffer data as bytes.

Only available when the payload type is a Flatbuffer.

payload_ptr

Returns the address of the payload of the received RequestMut as an int. ActiveRequest.payload provides typed access.

payload_root() → Any

Returns the root of the flatbuffer.

Only available when the payload type is a Flatbuffer.

send_copy(t: Type[ResT]) → Any

Sends a copy of the provided type.

user_header() → Any

Returns a ctypes.POINTER to the request header.

user_header_ptr

Returns the address of the user_header of the received RequestMut as an int. ActiveRequest.user_header provides typed access.

class iceoryx2.Alignment

Bases: object

Contains the alignment memory can have.

static new(value)

Creates a new Alignment. If the value is zero or not a power of 2 it emits an InvalidAlignmentValue.

value()

Returns the value of the Alignment

class iceoryx2.AliveNodeView

Bases: object

Contains all details of a Node that is alive.

details

Returns optional NodeDetails that contains further information about the Node. Can only be acquired when the process has the access right to read it.

id

Returns the UniqueNodeId.

exception iceoryx2.AllocationGrowError

Bases: Exception

Errors caused when growing a payload memory.

class iceoryx2.AllocationStrategy

Bases: object

Describes generically an AllocationStrategy, meaning how the memory is increased when the available memory is insufficient.

BestFit = AllocationStrategy.BestFit

PowerOfTwo = AllocationStrategy.PowerOfTwo

Static = AllocationStrategy.Static

class iceoryx2.Attribute

Bases: object

Represents a single service attribute (key-value) pair that can be defined when the service is being created.

key

Acquires the service attribute key

static new(key, value)

Creates an attribute instance

value

Acquires the service attribute value

class iceoryx2.AttributeKey

Bases: object

Relocatable (inter-process shared memory compatible) SemanticString implementation for AttributeKey.

static max_len()

Returns the maximum length of a AttributeKey

static new(value)

Creates a new AttributeKey when the provided value does not exceed AttributeKey.max_len(), otherwise it emits a SemanticStringError.

to_string()

Converts the AttributeKey into a str

class iceoryx2.AttributeSet

Bases: object

Represents a single service attribute (key-value) pair that can be defined when the service is being created.

static capacity()

Returns the maximum Attribute count the AttributeSet can hold.

key_values(key)

Returns all AttributeValue that belong to a specified AttributeKey.

number_of_attributes

Returns the Attribute count of the AttributeSet.

values

Returns every Attribute stored in the AttributeSet

class iceoryx2.AttributeSpecifier

Bases: object

Represents a single service attribute (key-value) pair that can be defined when the service is being created.

attributes

Returns the underlying AttributeSet

define(key, value)

Defines a value for a specific key. A key is allowed to have multiple values.

static new()

Creates a new empty Attribute set

class iceoryx2.AttributeValue

Bases: object

Relocatable (inter-process shared memory compatible) SemanticString implementation for AttributeValue.

static max_len()

Returns the maximum length of a AttributeValue

static new(value)

Creates a new AttributeValue when the provided value does not exceed AttributeValue.max_len(), otherwise it emits a SemanticStringError.

to_string()

Converts the AttributeValue into a str

class iceoryx2.AttributeVerifier

Bases: object

Represents a single service attribute (key-value) pair that can be defined when the service is being created.

static new()

Creates a new empty Attribute set

require(key, value)

Requires a value for a specific key. A key is allowed to have multiple values.

require_key(key)

Requires that a specific key is defined.

required_attributes

Returns the underlying required AttributeSet

required_keys

Returns the underlying required keys

verify_requirements(rhs)

Verifies if the AttributeSet contains all required keys and key-value pairs.

class iceoryx2.BackpressureStrategy

Bases: object

Defines the strategy a sender shall pursue when the buffer of the receiver is full and the service does not overflow.

DiscardData = BackpressureStrategy.DiscardData

RetryUntilDelivered = BackpressureStrategy.RetryUntilDelivered

exception iceoryx2.BlackboardCreateError

Bases: Exception

Errors caused when creating a blackboard service.

class iceoryx2.BlackboardKey(data: bytes)

Bases: object

A wrapper class for the keys returned by PortFactoryBlackboard.list_keys().

decode_as(ct_type)

Interpret the raw bytes as a ctypes type.

exception iceoryx2.BlackboardOpenError

Bases: Exception

Errors caused when opening a blackboard service.

class iceoryx2.BlackboardValue(data: bytes, generation_counter: c_ulong)

Bases: object

A wrapper class for the value returned by EntryHandle.get().

decode_as(ct_type)

Interpret the raw bytes as a ctypes type.

class iceoryx2.Client

Bases: object

Represents the receiving endpoint of an event based communication.

backpressure_strategy

Returns the strategy the Client follows when a RequestMut cannot be delivered if the Server’s buffer is full.

delete()

Releases the Client.

After this call the Client is no longer usable!

id

Returns the UniqueClientId of the Client

initial_max_slice_len()

Returns the maximum initial slice length configured for this Client.

loan_flatbuffer() → RequestMutUninit

Loans/allocates a RequestMutUninit from the underlying data segment of the Client with an integrated flatbuffer builder.

loan_slice_uninit(number_of_elements: int) → RequestMutUninit

Loans/allocates memory from the underlying data segment.

The user has to initialize the payload before it can be sent. Fails when it is called for data types which are not a slice. On failure it returns LoanError describing the failure.

loan_uninit() → RequestMutUninit

Loans/allocates memory from the underlying data segment.

The user has to initialize the payload before it can be sent. On failure it returns LoanError describing the failure.

max_active_requests

Returns the maximum amount of active requests the Client can send.

name

Returns the PortName of the Client

send_copy(t: Type[ReqT]) → PendingResponse

Sends a copy of the provided type.

exception iceoryx2.ClientCreateError

Bases: Exception

Errors caused when creating a new client port.

exception iceoryx2.ConfigCreationError

Bases: Exception

Errors caused by creating a new config.

exception iceoryx2.ConnectionFailure

Bases: Exception

Errors caused a connection to an endpoint could not be established.

class iceoryx2.DeadNodeView

Bases: object

Contains all details of a Node that is dead.

blocking_remove_stale_resources(timeout)

Removes all stale resources of a dead Node. If another instance is already removing the dead Node it waits until the other instance has cleaned up the dead Node completely. If the other cleanup instance crashes, it will take over the ownership and continue the cleanup. If the process does not have the permission to cleanup all resources it aborts with an error.

If the provided timeout is expired it will return.

details

Returns optional NodeDetails that contains further information about the Node. Can only be acquired when the process has the access right to read it.

id

Returns the UniqueNodeId.

try_remove_stale_resources()

Removes all stale resources of the dead Node. On error it emits a NodeCleanupFailure. It returns true if the stale resources could be removed, otherwise false.

class iceoryx2.Duration

Bases: object

Represents a time duration.

as_micros()

Returns the number of micro seconds stored in the Duration

as_millis()

Returns the number of milli seconds stored in the Duration

as_nanos()

Returns the number of nano seconds stored in the Duration

as_secs()

Returns the number of seconds stored in the Duration

as_secs_f64()

Returns the number of seconds stored in the Duration

static from_micros(micros)

Creates a new Duration from a given number of micro seconds

static from_millis(millis)

Creates a new Duration from a given number of milli seconds

static from_nanos(nanos)

Creates a new Duration from a given number of nano seconds

static from_secs(secs)

Creates a new Duration from a given number of seconds

static from_secs_f64(secs)

Creates a new Duration from a given number of seconds

subsec_micros()

Returns the fractional micro seconds part stored in the Duration

subsec_millis()

Returns the fractional milli seconds part stored in the Duration

subsec_nanos()

Returns the fractional nano seconds part stored in the Duration

class iceoryx2.DynamicConfigBlackboard

Bases: object

The dynamic configuration of a MessagingPattern.Blackboard service. Port counts reflect the current state of the service when accessed. The view keeps the service open while it is referenced. Explicitly deleting the blackboard factory invalidates the view; subsequent count queries raise RuntimeError.

number_of_readers

Returns the number of readers currently connected to the service.

number_of_writers

Returns the number of writers currently connected to the service.

class iceoryx2.DynamicConfigEvent

Bases: object

The dynamic configuration of a MessagingPattern.Event service. Port counts reflect the current state of the service when accessed. The view keeps the service open while it is referenced.

number_of_listeners

Returns the number of listeners currently connected to the service.

number_of_notifiers

Returns the number of notifiers currently connected to the service.

class iceoryx2.DynamicConfigPublishSubscribe

Bases: object

The dynamic configuration of a MessagingPattern.PublishSubscribe service. Port counts reflect the current state of the service when accessed. The view keeps the service open while it is referenced.

number_of_publishers

Returns the number of publishers currently connected to the service.

number_of_subscribers

Returns the number of subscribers currently connected to the service.

class iceoryx2.DynamicConfigRequestResponse

Bases: object

The dynamic configuration of a MessagingPattern.RequestResponse service. Port counts reflect the current state of the service when accessed. The view keeps the service open while it is referenced.

number_of_clients

Returns the number of clients currently connected to the service.

number_of_servers

Returns the number of servers currently connected to the service.

class iceoryx2.EntryHandle

Bases: object

entry_id

Returns an ID corresponding to the entry which can be used in an event based communication setup.

get() → BlackboardValue

Returns a copy of the value as bytes wrapped in a BlackboardValue.

Use decode_as() to reinterpret the raw bytes as a ctypes type.

is_up_to_date(value: BlackboardValue) → bool

Checks if value is up-to-date.

exception iceoryx2.EntryHandleError

Bases: Exception

Errors caused when an EntryHandle is created with Reader::entry().

class iceoryx2.EntryHandleMut

Bases: object

delete()

Releases the EntryHandleMut.

After this call the EntryHandleMut is no longer usable!

entry_id

Returns an ID corresponding to the entry which can be used in an event based communication setup.

loan_uninit()

Consumes the EntryHandleMut and loans an uninitialized entry value that can be used to update without copy.

update_with_copy(value: Type[V])

Updates the value by copying the passed value into it.

exception iceoryx2.EntryHandleMutError

Bases: Exception

Errors caused when an EntryHandleMut is created with Writer::entry().

class iceoryx2.EntryValueUninit

Bases: object

assume_init_and_update() → EntryHandleMut

Makes the new value accessible.

Consumes the EntryValueUninit, makes the new value accessible and returns the original EntryHandleMut.

discard()

Discards the EntryValueUninit and returns the original EntryHandleMut.

update_with_copy(value: Type[V]) → EntryHandleMut

Updates the entry value.

Consumes the EntryValueUninit, writes values to the entry value and returns the original EntryHandleMut.

value_mut() → Any

Returns a ctypes.POINTER to the value of the blackboard entry.

It can be used to update the value without copy. After writing, assume_init_and_update() must be called.

class iceoryx2.EventActivation

Bases: object

User defined identifier that can be provided in Notifier.notify() to signal a specific kind of event.

count

Returns how often the EventId was notified

id

Returns the EventId

exception iceoryx2.EventCreateError

Bases: Exception

Errors caused when creating an event service.

class iceoryx2.EventId

Bases: object

User defined identifier that can be provided in Notifier.notify() to signal a specific kind of event.

as_value

Returns the integer value of the EventId

static new(value)

Creates a new EventId from a given integer value

exception iceoryx2.EventOpenError

Bases: Exception

Errors caused when opening an event service.

exception iceoryx2.EventOpenOrCreateError

Bases: Exception

Errors caused when open or creating an event service.

class iceoryx2.FileDescriptor

Bases: object

Represents a FileDescriptor in a POSIX system. Contains always a value greater or equal zero, a valid file descriptor. It takes the ownership of the provided file descriptor and calls posix::close on destruction.

native_handle

Returns the underlying value of the FileDescriptor

# Safety

• the user shall not store the value in a variable otherwise lifetime issues may be encountered

• do not manually close the file descriptor with a sys call

static new(value)

Creates a new FileDescriptor. If the value is smaller than zero it returns None.

static non_owning_new(value)

Creates a FileDescriptor which does not hold the ownership of the file descriptor and will not call posix::close on destruction.

class iceoryx2.FileName

Bases: object

Relocatable (inter-process shared memory compatible) SemanticString implementation for FileName. All modification operations ensure that never an invalid file or path name can be generated. All strings have a fixed size so that the maximum path or file name length the system supports can be stored.

static max_len()

Returns the maximum length of a FileName

static new(name)

Creates a new FileName when the provided name contains a valid path to a file, otherwise it emits a SemanticStringError.

to_string()

Converts the FileName into a str

class iceoryx2.FilePath

Bases: object

Relocatable (inter-process shared memory compatible) SemanticString implementation for FilePath. All modification operations ensure that never an invalid file or path name can be generated. All strings have a fixed size so that the maximum path or file name length the system supports can be stored.

static max_len()

Returns the maximum length of a FilePath

static new(name)

Creates a new FilePath when the provided name contains a valid path to a file, otherwise it emits a SemanticStringError.

to_string()

Converts the FilePath into a str

class iceoryx2.Flatbuffer

Bases: Generic[T]

A class representing flatbuffer serializable T.

class iceoryx2.HeaderPublishSubscribe

Bases: object

Sample header used by MessagingPattern.PublishSubscribe

node_id

Returns the UniqueNodeId of the source node that published the Sample.

number_of_elements

Returns how many elements are stored inside the Sample’s payload.

payload_offset

Returns the payload offset.

publisher_id

Returns the UniquePublisherId of the source Publisher.

exception iceoryx2.InvalidAlignmentValue

Bases: Exception

Errors caused when the value of the alignment is not a power of two or exceeds the maximum supported value.

class iceoryx2.Listener

Bases: object

Represents the receiving endpoint of an event based communication.

blocking_wait()

Blocking wait for new events. Unblocks as soon as an event was received and then collects every EventActivation that was received and returns them. On error it emits ListenerWaitError.

deadline

Returns the deadline of the corresponding Service.

delete()

Releases the Listener.

After this call the Listener is no longer usable!

id

Returns the UniqueListenerId of the Listener

name

Returns the PortName of the Listener

timed_wait(timeout)

Blocking wait for new events until the provided timeout has passed. Unblocks as soon as an event was received and then collects every EventActivation that was received and returns them. On error it emits ListenerWaitError.

try_wait()

Non-blocking wait for new events. Collects every EventActivation that was received and returns them. On error it emits ListenerWaitError.

exception iceoryx2.ListenerCreateError

Bases: Exception

Errors caused when creating a new Listener port.

exception iceoryx2.ListenerWaitError

Bases: Exception

Errors caused when waiting on a Listener port in an event service.

exception iceoryx2.LoanError

Bases: Exception

Errors caused when loaning memory from a ports datasegment.

class iceoryx2.LogLevel

Bases: object

Describes the log level.

Debug = LogLevel.Debug

Error = LogLevel.Error

Fatal = LogLevel.Fatal

Info = LogLevel.Info

Trace = LogLevel.Trace

Warn = LogLevel.Warn

class iceoryx2.MessageTypeDetails

Bases: object

Contains all type information to the header and payload type.

header

The TypeDetail of the header of a message, the first iceoryx2 internal part.

payload

The TypeDetail of the payload of the message, the last part.

user_header

The TypeDetail of the user_header or the custom header, is located directly after the header.

class iceoryx2.MessagingPattern

Bases: object

Blackboard = MessagingPattern.Blackboard

Event = MessagingPattern.Event

PublishSubscribe = MessagingPattern.PublishSubscribe

RequestResponse = MessagingPattern.RequestResponse

class iceoryx2.Node

Bases: object

The central entry point of iceoryx2. Represents a node of the iceoryx2 system. One process can have arbitrary many nodes but usually it should be only one node per process. Can be created via the NodeBuilder.

blocking_cleanup_dead_nodes(timeout)

Removes the stale system resources of every dead Node. A dead Node is also removed from every registered Service.

If a Node cannot be cleaned up since the process has insufficient permissions then the Node is skipped. If it is currently being cleaned up by another process then the cleaner will wait until the timeout as either passed or the cleaned was finished.

The timeout is applied to every individual dead Node the function needs to wait on.

config

Returns the config.Config that the Node will use to create any iceoryx2 entity.

force_remove_service(name, messaging_pattern)

Removes a Service by force. This shall be used if the resources could not be removed in a previous run and now it is no longer possible to open the service.

# Safety

No other process shall continue to use the service.

id

Returns the unique id of the Node.

static list(service_type, config)

Returns the NodeState of every Node under a provided config. On failure it emits a NodeListFailure.

name

Returns the name of the node inside a NodeName.

service_builder(name)

Instantiates a ServiceBuilder for a service with the provided name.

signal_handling_mode

Returns the SignalHandlingMode with which the Node was created.

try_cleanup_dead_nodes()

Removes the stale system resources of every dead Node. A dead Node is also removed from every registered Service.

If a Node cannot be cleaned up since the process has insufficient permissions then the Node is skipped.

wait(cycle_time)

Waits for a given cycle_time. On failure it emits a NodeWaitFailure.

class iceoryx2.NodeBuilder

Bases: object

Creates a new Node.

config(config)

The config.Config that shall be used for the Node. If no config.Config is specified the config.global_config is used.

create(service_type)

Creates a new Node for a specified ServiceType. Emits NodeCreationFailure on failure.

name(value)

The NodeName that shall be assigned to the Node. It does not have to be unique. If no NodeName is defined then the Node does not have a name.

static new()

Instantiates a new NodeBuilder

signal_handling_mode(value)

Defines the SignalHandlingMode for the Node. It affects the Node.wait() call that returns any received signal via its NodeWaitFailure

exception iceoryx2.NodeCleanupFailure

Bases: Exception

Errors caused by cleaning up the stale resources of a dead node.

exception iceoryx2.NodeCreationFailure

Bases: Exception

Errors caused by creating a new node.

class iceoryx2.NodeDetails

Bases: object

Contains details of a Node.

config

Returns a reference to the config.Config the Node uses.

executable

Returns the executable FileName of the Node’s owner process.

name

Returns a reference of the NodeName.

process_id

Returns the process id of the Node’s owner process.

exception iceoryx2.NodeListFailure

Bases: Exception

Errors caused when listing all nodes.

class iceoryx2.NodeName

Bases: object

Represent the name for a Node.

as_str()

Converts the NodeName into a str

static max_len()

Returns the maximum length of a NodeName

static new(name)

Creates a new NodeName. If the provided name does not contain a valid NodeName it will emit SemanticStringError, otherwise the NodeName.

class iceoryx2.NodeState

Bases: object

Describes the state of a Node.

class Alive(_0)

Bases: NodeState

The Node’s process is still alive.

class Dead(_0)

Bases: NodeState

The Node’s process died without cleaning up the Node’s resources. Another process has now the responsibility to cleanup all the stale resources.

class Inaccessible(_0)

Bases: NodeState

The process does not have sufficient permissions to identify the Node as dead or alive.

class Undefined(_0)

Bases: NodeState

The Node is in an undefined state, meaning that certain elements are missing, misconfigured or inconsistent. This can only happen due to an implementation failure or when the corresponding Node resources were altered.

exception iceoryx2.NodeWaitFailure

Bases: Exception

Errors caused when waiting on a node.

class iceoryx2.Notifier

Bases: object

Represents the sending endpoint of an event based communication.

deadline

Returns the deadline of the corresponding Service.

delete()

Releases the Notifier.

After this call the Notifier is no longer usable!

id

Returns the UniqueNotifierId of the Notifier

name

Returns the PortName of the Notifier

notify()

Notifies all Listener connected to the service with the default event id provided on creation. Returns on success the number of Listener ports that were notified otherwise it emits NotifierNotifyError.

notify_with_custom_event_id(event_id)

Notifies all Listener connected to the service with a custom EventId. Returns on success the number of Listener ports that were notified otherwise it returns NotifierNotifyError.

exception iceoryx2.NotifierCreateError

Bases: Exception

Errors caused when creating a new Notifier port.

exception iceoryx2.NotifierNotifyError

Bases: Exception

Errors caused when sending a notification via the Notifier port in an event service.

class iceoryx2.Path

Bases: object

Relocatable (inter-process shared memory compatible) SemanticString implementation for Path. All modification operations ensure that never an invalid file or path name can be generated. All strings have a fixed size so that the maximum path or file name length the system supports can be stored.

static max_len()

Returns the maximum length of a Path

static new(name)

Creates a new Path when the provided name contains a valid path, otherwise it emits a SemanticStringError.

to_string()

Converts the Path into a str

class iceoryx2.PendingResponse

Bases: object

Represents an active connection to all Server that received the RequestMut. The Client can use it to receive every corresponding Response.

As soon as it goes out of scope, the connections are closed and every Server is informed.

delete()

Releases the PendingResponse and signals the Server that the Client is no longer interested in receiving another Response and terminates the connection.

After this call the PendingResponse is no longer usable!

has_response

Returns True when a Server has sent a Response otherwise False.

header

Returns a reference to the iceoryx2 internal RequestHeader of the corresponding RequestMut

is_connected

Returns True until the ActiveRequest goes out of scope on the Server’s side indicating that the Server will no longer send a Response. It also returns False when there are no Server.

number_of_server_connections

Returns how many Server ports received the corresponding RequestMut initially.

payload() → Any

Returns the payload of the request.

It is a Slice when the payload type is a Slice, otherwise a ctypes.POINTER to the payload type.

payload_bytes() → Slice[c_ubyte]

Returns the serialized flatbuffer data as bytes.

Only available when the payload type is a Flatbuffer.

payload_ptr

Returns the address of the request payload of the corresponding RequestMut as an int. PendingResponse.payload provides typed access.

payload_root() → Any

Returns the root of the flatbuffer.

Only available when the payload type is a Flatbuffer.

receive()

Receives a Response from a Server that received the RequestMut.

set_disconnect_hint()

Marks the connection state that the Client wants to gracefully disconnect. When the Server reads this, it can send the last Response and drop the corresponding ActiveRequest to terminate the connection ensuring that no Response is lost on the Client side.

user_header() → Any

Returns a ctypes.POINTER to the request header.

user_header_ptr

Returns the address of the user defined request header of the corresponding RequestMut as an int. PendingResponse.user_header provides typed access.

class iceoryx2.PortFactoryBlackboard

Bases: object

The factory for MessagingPattern.Blackboard. It can acquire dynamic and static service information and create Reader or Writer ports.

attributes

Returns the AttributeSet defined in the Service.

blocking_cleanup_dead_nodes(timeout)

Removes the stale system resources of every dead Node connected to this service.

If a Node cannot be cleaned up since the process has insufficient permissions then the Node is skipped. If it is currently being cleaned up by another process then the cleaner will wait until the timeout as either passed or the cleaned was finished.

The timeout is applied to every individual dead Node the function needs to wait on.

delete()

Releases the PortFactoryBlackboard.

After this call the PortFactoryBlackboard is no longer usable!

dynamic_config

Returns the dynamic configuration, including the current port counts.

list_keys()

Returns a list containing copies of the blackboard keys as bytes.

The keys are wrapped in a BlackboardKey. Use decode_as() to reinterpret the raw bytes as a ctypes type.

name

Returns the ServiceName of the service.

nodes

Returns a list of all NodeState of every Node which has opened the Service.

reader_builder()

Returns a PortFactoryReader to create a new Reader port

service_hash

Returns the ServiceHash of the Service.

static_config

Returns the StaticConfig of the Service. Contains all settings that never change during the lifetime of the service.

try_cleanup_dead_nodes()

Removes the stale system resources of every dead Node connected to this service.

If a Node cannot be cleaned up since the process has insufficient permissions or it is currently being cleaned up by another process then the Node is skipped.

writer_builder()

Returns a PortFactoryWriter to create a new Writer port

class iceoryx2.PortFactoryClient

Bases: object

Factory to create a new Client port/endpoint for MessagingPattern.RequestResponse based communication.

allocation_strategy(value: AllocationStrategy) → PortFactoryClient

Defines the allocation strategy that is used when the memory is exhausted.

backpressure_strategy(value)

Sets the BackpressureStrategy which defines how the Client shall behave when a Server cannot receive a RequestMut since its internal buffer is full.

create()

Creates a new Client or emits a ClientCreateError on failure.

initial_max_slice_len(value: int) → PortFactoryClient

Sets the maximum slice length that a user can allocate.

initial_reserved_memory(value: int) → PortFactoryClient

Sets the maximum initial reserved memory that the underlying allocator reserves for the flatbuffer builder.

max_active_requests(value)

Defines the maximal active requests the Client can send. Smallest possible value is 1.

name(value)

The PortName that shall be assigned to the Client. It does not have to be unique. If no PortName is defined then the Client does not have a name.

override_request_preallocation(value)

Reduces the preallocated RequestMut count. The return value is clamped between 1 and the worst case preallocated RequestMut count required to guarantee that the Client always has a RequestMut to loan and send.

# Important

If the user reduces the preallocated RequestMut count, iceoryx2 can no longer guarantee, that the Client can always loan a RequestMut to send.

class iceoryx2.PortFactoryEvent

Bases: object

The factory for MessagingPattern.Event. It can acquire dynamic and static service information and create Notifier or Listener ports.

attributes

Returns the AttributeSet defined in the Service

blocking_cleanup_dead_nodes(timeout)

Removes the stale system resources of every dead Node connected to this service.

If a Node cannot be cleaned up since the process has insufficient permissions then the Node is skipped. If it is currently being cleaned up by another process then the cleaner will wait until the timeout as either passed or the cleaned was finished.

The timeout is applied to every individual dead Node the function needs to wait on.

dynamic_config

Returns the dynamic configuration, including the current port counts.

listener_builder()

Returns a PortFactoryListener to create a new Listener port

name

Returns the ServiceName of the service

nodes

Returns a list of all NodeState of every Node which has opened the Service.

notifier_builder()

Returns a PortFactoryNotifier to create a new Notifier port

service_hash

Returns the ServiceHash of the Service

static_config

Returns the StaticConfig of the Service. Contains all settings that never change during the lifetime of the service.

try_cleanup_dead_nodes()

Removes the stale system resources of every dead Node connected to this service.

If a Node cannot be cleaned up since the process has insufficient permissions or it is currently being cleaned up by another process then the Node is skipped.

class iceoryx2.PortFactoryListener

Bases: object

Factory to create a new Listener port/endpoint for MessagingPattern.Event based communication.

create()

Creates the Listener port or emits a ListenerCreateError on failure.

name(value)

The PortName that shall be assigned to the Listener. It does not have to be unique. If no PortName is defined then the Listener does not have a name.

class iceoryx2.PortFactoryNotifier

Bases: object

Factory to create a new Notifier port/endpoint for MessagingPattern.Event based communication.

create()

Creates a new Notifier port or emits a NotifierCreateError on failure.

default_event_id(value)

Sets a default EventId for the Notifier that is used in Notifier.notify()

name(value)

The PortName that shall be assigned to the Notifier. It does not have to be unique. If no PortName is defined then the Notifier does not have a name.

class iceoryx2.PortFactoryPublishSubscribe

Bases: object

The factory for MessagingPattern.PublishSubscribe. It can acquire dynamic and static service information and create Publisher or Subscriber ports.

attributes

Returns the AttributeSet defined in the Service

blocking_cleanup_dead_nodes(timeout)

Removes the stale system resources of every dead Node connected to this service.

If a Node cannot be cleaned up since the process has insufficient permissions then the Node is skipped. If it is currently being cleaned up by another process then the cleaner will wait until the timeout as either passed or the cleaned was finished.

The timeout is applied to every individual dead Node the function needs to wait on.

dynamic_config

Returns the dynamic configuration, including the current port counts.

name

Returns the ServiceName of the service

nodes

Returns a list of all NodeState of every Node which has opened the Service.

publisher_builder()

Returns a PortFactoryPublisher to create a new Publisher port

service_hash

Returns the ServiceHash of the Service

static_config

Returns the StaticConfig of the Service. Contains all settings that never change during the lifetime of the service.

subscriber_builder()

Returns a PortFactorySubscriber to create a new Subscriber port

try_cleanup_dead_nodes()

Removes the stale system resources of every dead Node connected to this service.

If a Node cannot be cleaned up since the process has insufficient permissions or it is currently being cleaned up by another process then the Node is skipped.

class iceoryx2.PortFactoryPublisher

Bases: object

Factory to create a new Publisher port/endpoint for MessagingPattern.PublishSubscribe based communication.

allocation_strategy(value: AllocationStrategy) → PortFactoryPublisher

Defines the allocation strategy that is used when the memory is exhausted.

backpressure_strategy(value)

Sets the BackpressureStrategy.

create()

Creates a new Publisher or emits a PublisherCreateError on failure.

initial_max_slice_len(value: int) → PortFactoryPublisher

Sets the maximum slice length that a user can allocate.

initial_reserved_memory(value: int) → PortFactoryPublisher

Sets the maximum initial reserved memory that the underlying allocator reserves for the flatbuffer builder.

max_loaned_samples(value)

Defines how many SampleMut the Publisher can loan with Publisher.loan_uninit or Publisher.loan_slice_uninit in parallel.

name(value)

The PortName that shall be assigned to the Publisher. It does not have to be unique. If no PortName is defined then the Publisher does not have a name.

override_sample_preallocation(value)

Reduces the preallocated SampleMut count. The return value is clamped between 1 and the worst case preallocated SampleMut count required to guarantee that the Publisher always has a SampleMut to loan and send.

# Important

If the user reduces the preallocated SampleMut count, iceoryx2 can no longer guarantee, that the Publisher can always loan a SampleMut to send.

class iceoryx2.PortFactoryReader

Bases: object

Factory to create a new Reader port/endpoint for MessagingPattern.Blackboard based communication.

create()

Creates a new Reader or emits a ReaderCreateError on failure.

name(value)

The PortName that shall be assigned to the Reader. It does not have to be unique. If no PortName is defined then the Reader does not have a name.

class iceoryx2.PortFactoryRequestResponse

Bases: object

The factory for MessagingPattern.RequestResponse. It can acquire dynamic and static service information and create Client or Server ports.

attributes

Returns the AttributeSet defined in the Service

blocking_cleanup_dead_nodes(timeout)

Removes the stale system resources of every dead Node connected to this service.

If a Node cannot be cleaned up since the process has insufficient permissions then the Node is skipped. If it is currently being cleaned up by another process then the cleaner will wait until the timeout as either passed or the cleaned was finished.

The timeout is applied to every individual dead Node the function needs to wait on.

client_builder()

Returns a PortFactoryClient to create a new Client port

dynamic_config

Returns the dynamic configuration, including the current port counts.

name

Returns the ServiceName of the service

nodes

Returns a list of all NodeState of every Node which has opened the Service.

server_builder()

Returns a PortFactoryServer to create a new Server port

service_hash

Returns the ServiceHash of the Service

static_config

Returns the StaticConfig of the Service. Contains all settings that never change during the lifetime of the service.

try_cleanup_dead_nodes()

Removes the stale system resources of every dead Node connected to this service.

If a Node cannot be cleaned up since the process has insufficient permissions or it is currently being cleaned up by another process then the Node is skipped.

class iceoryx2.PortFactoryServer

Bases: object

Factory to create a new Server port/endpoint for MessagingPattern.RequestResponse based communication.

allocation_strategy(value: AllocationStrategy) → PortFactoryServer

Defines the allocation strategy that is used when the memory is exhausted.

backpressure_strategy(value)

Sets the BackpressureStrategy which defines how the Server shall behave when a Client cannot receive a Response since its internal buffer is full.

create()

Creates a new Server or emits a ServerCreateError on failure.

initial_max_slice_len(value: int) → PortFactoryServer

Sets the maximum slice length that a user can allocate.

initial_reserved_memory(value: int) → PortFactoryServer

Sets the maximum initial reserved memory that the underlying allocator reserves for the flatbuffer builder.

max_loaned_responses_per_request(value)

Defines the maximum number of ResponseMut that the Server can loan in parallel per ActiveRequest.

name(value)

The PortName that shall be assigned to the Server. It does not have to be unique. If no PortName is defined then the Server does not have a name.

override_response_preallocation(value)

Reduces the preallocated ResponseMut count. The return value is clamped between 1 and the worst case preallocated ResponseMut count required to guarantee that the Server always has a ResponseMut to loan and send.

# Important

If the user reduces the preallocated ResponseMut count, iceoryx2 can no longer guarantee, that the Server can always loan a ResponseMut to send.

class iceoryx2.PortFactorySubscriber

Bases: object

Factory to create a new Subscriber port/endpoint for MessagingPattern.PublishSubscribe based communication.

buffer_size(value)

Defines the buffer size of the Subscriber. Smallest possible value is 1.

create()

Creates a new Subscriber or emits a SubscriberCreateError on failure.

history_request(value)

Defines the amount of requested history samples. By default the value defined with the service’s history_size is used

name(value)

The PortName that shall be assigned to the Subscriber. It does not have to be unique. If no PortName is defined then the Subscriber does not have a name.

class iceoryx2.PortFactoryWriter

Bases: object

Factory to create a new Writer port/endpoint for MessagingPattern.Blackboard based communication.

create()

Creates a new Writer or returns a WriterCreateError on failure.

name(value)

The PortName that shall be assigned to the Writer. It does not have to be unique. If no PortName is defined then the Writer does not have a name.

class iceoryx2.PortName

Bases: object

Represent the name for a port.

as_str()

Converts the PortName into a str

static max_len()

Returns the maximum length of a PortName

static new(name)

Creates a new PortName. If the provided name does not contain a valid PortName it will emit SemanticStringError, otherwise the PortName.

exception iceoryx2.PublishSubscribeCreateError

Bases: Exception

Errors caused when creating a publish-subscribe service.

exception iceoryx2.PublishSubscribeOpenError

Bases: Exception

Errors caused when opening a publish-subscribe service.

exception iceoryx2.PublishSubscribeOpenOrCreateError

Bases: Exception

Errors caused when open or creating a publish-subscribe service.

class iceoryx2.Publisher

Bases: object

Represents the receiving endpoint of an event based communication.

backpressure_strategy

Returns the strategy the Publisher follows when a SampleMut cannot be delivered since the Subscriber’s buffer is full.

delete()

Releases the Publisher.

After this call the Publisher is no longer usable!

id

Returns the UniquePublisherId of the Publisher

initial_max_slice_len

Returns the maximum initial slice length configured for this Publisher.

loan_flatbuffer() → SampleMutUninit

Loans/allocates a SampleMutUninit from the underlying data segment of the Publisher with an integrated flatbuffer builder.

loan_slice_uninit(number_of_elements: int) → SampleMutUninit

Loans/allocates a SampleMutUninit from the underlying data segment of the Publisher.

The user has to initialize the payload before it can be sent. Fails when it is called for data types which are not a slice. On failure it returns LoanError describing the failure.

loan_uninit() → SampleMutUninit

Loans/allocates a SampleMutUninit from the underlying data segment of the Publisher.

The user has to initialize the payload before it can be sent. On failure it returns LoanError describing the failure.

name

Returns the PortName of the Publisher

send_copy(t: Type[T]) → Any

Sends a copy of the provided type.

update_connections()

Explicitly updates the connection to every Subscriber. This is required to be called whenever a new Subscriber connected to the service. It is done implicitly whenever SampleMut.send or Publisher.send_copy is called. When a Subscriber is connected that requires a history this call will deliver it.

exception iceoryx2.PublisherCreateError

Bases: Exception

Errors caused when creating a publisher port.

class iceoryx2.Reader

Bases: object

Represents the reading endpoint of a blackboard based communication.

delete()

Releases the Reader.

After this call the Reader is no longer usable!

entry(key: Type[K], value: Type[V]) → EntryHandle

Creates an EntryHandle for direct read access to the value.

On failure it returns EntryHandleError describing the failure.

id

Returns the UniqueReaderId of the Reader

name

Returns the PortName of the Reader

exception iceoryx2.ReaderCreateError

Bases: Exception

Errors caused when creating a reader port.

exception iceoryx2.ReceiveError

Bases: Exception

Errors caused when receiving data.

class iceoryx2.RequestHeader

Bases: object

Request header used by MessagingPattern.RequestResponse

client_id

Returns the UniqueClientId of the Client which sent the RequestMut

number_of_elements

Returns how many elements are stored inside the requests’s payload.

payload_offset

Returns the payload offset.

class iceoryx2.RequestMut

Bases: object

The RequestMut represents the object that contains the payload that the Client sends to the Server.

delete()

Releases the RequestMut.

After this call the RequestMut is no longer usable!

header

Returns the iceoryx2 internal RequestHeader

payload() → Any

Returns the payload of the request.

It is a Slice when the payload type is a Slice, otherwise a ctypes.POINTER to the payload type.

payload_bytes() → Slice[c_ubyte]

Returns the serialized flatbuffer data as bytes.

Only available when the payload type is a Flatbuffer.

payload_ptr

Returns the address of the user defined request payload as an int. RequestMut.payload provides typed access.

payload_root() → Any

Returns the root of the flatbuffer.

Only available when the payload type is a Flatbuffer.

send()

Sends the RequestMut to every connected Server of the Service.

user_header() → Any

Returns a ctypes.POINTER to the request header.

user_header_ptr

Returns the address of the user defined request header as an int. RequestMut.user_header provides typed access.

class iceoryx2.RequestMutUninit

Bases: object

A version of the RequestMut where the payload is not initialized which allows true zero copy usage. To send a RequestMutUninit it must be first initialized and converted into RequestMut with RequestMutUninit.assume_init.

assume_init(root=None) → RequestMut

Extracts the value of the uninitialized payload and labels the RequestMutUninit as initialized RequestMut.

After this call the RequestMutUninit is no longer usable!

delete()

Releases the RequestMutUninit.

After this call the RequestMutUninit is no longer usable!

flatbuffer_builder() → Builder

Returns the flatbuffer builder to produce the data that shall be sent.

header

Returns the iceoryx2 internal RequestHeader

payload() → Any

Returns the payload of the request.

It is a Slice when the payload type is a Slice, otherwise a ctypes.POINTER to the payload type.

payload_ptr

Returns the address of the user defined request payload as an int. RequestMutUninit.payload provides typed access.

user_header() → Any

Returns a ctypes.POINTER to the request header.

user_header_ptr

Returns the address of the user defined request header as an int. RequestMutUninit.user_header provides typed access.

write_payload(t: Type[ReqT]) → RequestMut

Writes the provided payload into the request.

exception iceoryx2.RequestResponseCreateError

Bases: Exception

Errors caused when creating a request-response service.

exception iceoryx2.RequestResponseOpenError

Bases: Exception

Errors caused when opening a request-response service.

exception iceoryx2.RequestResponseOpenOrCreateError

Bases: Exception

Errors caused when open or creating a request-response service.

exception iceoryx2.RequestSendError

Bases: Exception

Errors caused when sending a request.

class iceoryx2.Response

Bases: object

It stores the payload and can be received by the PendingResponse after a RequestMut was sent to a Server via the Client.

delete()

Releases the Response.

After this call the Response is no longer usable!

header

Returns the ResponseHeader

origin

Returns the UniqueServerId of the Server which sent the Response.

payload() → Any

Returns the payload of the response.

It is a Slice when the payload type is a Slice, otherwise a ctypes.POINTER to the payload type.

payload_bytes() → Slice[c_ubyte]

Returns the serialized flatbuffer data as bytes.

Only available when the payload type is a Flatbuffer.

payload_ptr

Returns the address of the payload of the response as an int. Response.payload provides typed access.

payload_root() → Any

Returns the root of the flatbuffer.

Only available when the payload type is a Flatbuffer.

user_header() → Any

Returns a ctypes.POINTER to the response header.

user_header_ptr

Returns the address of the user header of the response as an int. Response.user_header provides typed access.

class iceoryx2.ResponseHeader

Bases: object

Response header used by MessagingPattern.RequestResponse

number_of_elements

Returns how many elements are stored inside the Response’s payload.

payload_offset

Returns the payload offset.

server_id

Returns the UniqueServerId of the Server which sent the Response

class iceoryx2.ResponseMut

Bases: object

delete()

Releases the ResponseMut.

After this call the ResponseMut is no longer usable!

header

Returns a reference to the ResponseHeader.

payload() → Any

Returns the payload of the response.

It is a Slice when the payload type is a Slice, otherwise a ctypes.POINTER to the payload type.

payload_bytes() → Slice[c_ubyte]

Returns the serialized flatbuffer data as bytes.

Only available when the payload type is a Flatbuffer.

payload_ptr

Returns the address of the payload of the response as an int. ResponseMut.payload provides typed access.

payload_root() → Any

Returns the root of the flatbuffer.

Only available when the payload type is a Flatbuffer.

send()

Sends a ResponseMut to the corresponding PendingResponse of the Client.

user_header() → Any

Returns a ctypes.POINTER to the response header.

user_header_ptr

Returns the address of the user header of the response as an int. ResponseMut.user_header provides typed access.

class iceoryx2.ResponseMutUninit

Bases: object

Acquired by an ActiveRequest with

• ActiveRequest.loan_uninit,

• ActiveRequest.loan_slice_uninit,

• ActiveRequest.loan_flatbuffer

It stores the uninitialized payload of the response. It must be initialized and converted into a ResponseMut with ResponseMutUninit.write_payload or ResponseMutUninit.assume_init before it can be sent. Otherwise the loaned memory is released when going out of scope.

assume_init(root=None) → ResponseMut

Extracts the value of the uninitialized payload and labels the ResponseMutUninit as initialized ResponseMut.

After this call the ResponseMutUninit is no longer usable!

delete()

Releases the ResponseMutUninit.

After this call the ResponseMutUninit is no longer usable!

flatbuffer_builder() → Builder

Returns the flatbuffer builder to produce the data that shall be sent.

header

Returns a reference to the ResponseHeader.

payload() → Any

Returns the payload of the response.

It is a Slice when the payload type is a Slice, otherwise a ctypes.POINTER to the payload type.

payload_ptr

Returns the address of the payload of the response as an int. ResponseMutUninit.payload provides typed access.

user_header() → Any

Returns a ctypes.POINTER to the response header.

user_header_ptr

Returns the address of the user header of the response as an int. ResponseMutUninit.user_header provides typed access.

write_payload(t: Type[ReqT]) → ResponseMut

Writes the provided payload into the response.

class iceoryx2.Sample

Bases: object

It stores the payload and is acquired by the Subscriber whenever it receives new data from a Publisher via Subscriber.receive.

delete()

Releases the Sample.

After this call the Sample is no longer usable!

header

Returns the HeaderPublishSubscribe of the Sample.

payload() → Any

Returns the payload.

It is a Slice when the payload type is a Slice, otherwise a ctypes.POINTER to the payload type.

payload_bytes() → Slice[c_ubyte]

Returns the serialized flatbuffer data as bytes.

Only available when the payload type is a Flatbuffer.

payload_ptr

Returns the address of the payload as an int. Sample.payload provides typed access.

payload_root() → Any

Returns the root of the flatbuffer.

Only available when the payload type is a Flatbuffer.

user_header() → Any

Returns a ctypes.POINTER to the user header.

user_header_ptr

Returns the address of the user header as an int. Sample.user_header provides typed access.

class iceoryx2.SampleMut

Bases: object

Acquired by initializing a SampleMutUninit via

• SampleMutUninit.write_payload,

• SampleMutUninit.assume_init

It stores the payload that will be sent to every connected Subscriber. If the SampleMut is not sent it will release the loaned memory when going out of scope.

delete()

Releases the SampleMut.

After this call the SampleMut is no longer usable!

header

Returns the HeaderPublishSubscribe of the Sample.

payload() → Any

Returns the payload.

It is a Slice when the payload type is a Slice, otherwise a ctypes.POINTER to the payload type.

payload_bytes() → Slice[c_ubyte]

Returns the serialized flatbuffer data as bytes.

Only available when the payload type is a Flatbuffer.

payload_ptr

Returns the address of the payload as an int. SampleMut.payload provides typed access.

payload_root() → Any

Returns the root of the flatbuffer.

Only available when the payload type is a Flatbuffer.

send()

Send a previously loaned Publisher.loan_uninit SampleMut to every connected Subscriber of the service.

On success the number of Subscriber ports that received the data is returned, otherwise a SendError is emitted describing the failure.

user_header() → Any

Returns a ctypes.POINTER to the user header.

user_header_ptr

Returns the address of the user header as an int. SampleMut.user_header provides typed access.

class iceoryx2.SampleMutUninit

Bases: object

Acquired by a Publisher via

• Publisher.loan_uninit,

• Publisher.loan_slice_uninit,

• Publisher.loan_flatbuffer

It stores the uninitialized payload. It must be initialized and converted into a SampleMut with SampleMutUninit.write_payload or SampleMutUninit.assume_init before it can be sent. Otherwise the loaned memory is released when going out of scope.

assume_init(root=None) → SampleMut

Extracts the value of the uninitialized payload and labels the SampleMutUninit as initialized SampleMut.

After this call the SampleMutUninit is no longer usable.

delete()

Releases the SampleMutUninit.

After this call the SampleMutUninit is no longer usable!

flatbuffer_builder() → Builder

Returns the flatbuffer builder to produce the data that shall be sent.

header

Returns the HeaderPublishSubscribe of the Sample.

payload() → Any

Returns the payload.

It is a Slice when the payload type is a Slice, otherwise a ctypes.POINTER to the payload type.

payload_ptr

Returns the address of the payload as an int. SampleMutUninit.payload provides typed access.

user_header() → Any

Returns a ctypes.POINTER to the user header.

user_header_ptr

Returns the address of the user header as an int. SampleMutUninit.user_header provides typed access.

write_payload(t: Type[T]) → SampleMut

Writes the provided payload into the sample.

exception iceoryx2.SemanticStringError

Bases: Exception

Errors caused by creating a semantic string.

exception iceoryx2.SendError

Bases: Exception

Errors caused when sending data.

class iceoryx2.Server

Bases: object

Represents the receiving endpoint of an event based communication.

backpressure_strategy

Returns the strategy the Server follows when a ResponseMut cannot be delivered if the Client’s buffer is full.

delete()

Releases the Server.

After this call the Server is no longer usable!

has_requests

Returns true if the Server has a RequestMut in its buffer.

id

Returns the UniqueServerId of the Server

name

Returns the PortName of the Server

receive()

Receives a RequestMut that was sent by a Client and returns an ActiveRequest which can be used to respond. If no RequestMut was received it returns None.

exception iceoryx2.ServerCreateError

Bases: Exception

Errors caused when creating a server port.

class iceoryx2.Service

Bases: object

Builder to create or open a Service

static details(service_name, config, messaging_pattern, service_type)

Acquires the ServiceDetails of a Service.

static does_exist(service_name, config, messaging_pattern, service_type)

Checks if a service under a given config.Config does exist

static list(config, service_type)

Returns a list of all services created under a given config.Config.

class iceoryx2.ServiceBuilder

Bases: object

Builder to create or open a Service

blackboard_creator(key: Type[K]) → ServiceBuilderBlackboardCreator

Returns the ServiceBuilderBlackboardCreator to create a new blackboard service.

The key ctype must be provided as argument. If the key is of type ctypes.Structure, it must implement __eq__.

blackboard_opener(key: Type[K]) → ServiceBuilderBlackboardOpener

Returns the ServiceBuilderBlackboardOpener to open a blackboard service.

The key ctype must be provided as argument.

event()

Create a new builder to create a MessagingPattern.Event Service.

publish_subscribe(t: Type[T]) → ServiceBuilderPublishSubscribe

Returns the ServiceBuilderPublishSubscribe to create a new publish-subscribe service. The payload ctype must be provided as argument.

request_response(request: Type[ReqT], response: Type[ResT]) → ServiceBuilderPublishSubscribe

Returns the ServiceBuilderRequestResponse to create a new request-response service.

The request/response payload ctype must be provided as argument.

class iceoryx2.ServiceBuilderBlackboardCreator

Bases: object

Builder to create a new MessagingPattern.Blackboard based Service

add(key: Type[K], value: Type[V]) → ServiceBuilderBlackboardCreator

Adds a key-value pair to the blackboard.

create()

Creates a new Service.

create_with_attributes(attributes)

Creates a new Service with a set of attributes.

max_nodes(value)

Defines how many Node instances shall be able to open the Service in parallel.

max_readers(value)

Defines how many Reader ports shall be supported at most.

class iceoryx2.ServiceBuilderBlackboardOpener

Bases: object

Builder to open a new MessagingPattern.Blackboard based Service

max_nodes(value)

Defines how many Node instances must be at least supported.

max_readers(value)

Defines how many Reader ports must be at least supported.

open()

Opens an existing Service.

open_with_attributes(verifier)

Opens an existing Service with attribute requirements. If the defined attribute requirements are not satisfied the open process will fail.

class iceoryx2.ServiceBuilderEvent

Bases: object

Builder to create a new MessagingPattern.Event based Service

create()

Creates a new Service.

create_with_attributes(attributes)

Creates a new Service with a set of attributes.

deadline(deadline)

Enables the deadline property of the service. There must be a notification emitted by any Notifier after at least the provided deadline.

disable_deadline()

Disables the deadline property of the service. Notifier can signal notifications at any rate.

disable_notifier_created_event()

If the Service is created it disables the event that shall be emitted by every newly created Notifier.

disable_notifier_dead_event()

If the Service is created it disables the event that shall be emitted when a Notifier is identified as dead.

disable_notifier_dropped_event()

If the Service is created it disables the event that shall be emitted by every Notifier before it is dropped.

event_id_max_value(value)

If the Service is created it set the greatest supported EventId value If an existing Service is opened it defines the value size the EventId must at least support.

max_listeners(value)

If the Service is created it defines how many Listener shall be supported at most. If an existing Service is opened it defines how many Listener must be at least supported.

max_nodes(value)

If the Service is created it defines how many Node instances shall be able to open it in parallel. If an existing Service is opened it defines how many Node instances must be at least supported.

max_notifiers(value)

If the Service is created it defines how many Notifier shall be supported at most. If an existing Service is opened it defines how many Notifier must be at least supported.

notifier_created_event(value)

If the Service is created it defines the event that shall be emitted by every newly created Notifier.

notifier_dead_event(value)

If the Service is created it defines the event that shall be emitted when a Notifier is identified as dead.

notifier_dropped_event(value)

If the Service is created it defines the event that shall be emitted by every Notifier before it is dropped.

open()

Opens an existing Service. Emits an EventOpenError on failure.

open_or_create()

If the Service exists, it will be opened otherwise a new Service will be created. On failure it emits an EventOpenOrCreateError

open_or_create_with_attributes(verifier)

If the Service exists, it will be opened otherwise a new Service will be created. It defines a set of attributes. If the Service already exists all attribute requirements must be satisfied otherwise the open process will fail. If the Service does not exist the required attributes will be defined in the Service. Emits and EventOpenOrCreateError on failure.

open_with_attributes(verifier)

Opens an existing Service with attribute requirements. If the defined attribute requirements are not satisfied the open process will fail. Emits an EventOpenError on failure.

class iceoryx2.ServiceBuilderPublishSubscribe

Bases: object

Builder to create a new MessagingPattern.PublishSubscribe based Service

create()

Creates a new Service. On failure it emits PublishSubscribeCreateError.

create_with_attributes(attributes)

Creates a new Service with a set of attributes. On failure it emits PublishSubscribeCreateError.

enable_safe_overflow(value)

If the Service is created, defines the overflow behavior of the service. If an existing Service is opened it requires the service to have the defined overflow behavior.

flatbuffer_schema_path(value: FilePath) → PortFactoryPublisher

Sets the path to the flatbuffer schema file.

If this is not explicitly defined, iceoryx2 will try to find the best fitting schema file in the configured flatbuffer schema paths defined in the config.

history_size(value)

If the Service is created it defines the maximum history size a Subscriber can request on connection. If an existing Service is opened it defines the minimum required.

max_nodes(value)

If the Service is created it defines how many Node instances shall be able to open it in parallel. If an existing Service is opened it defines how many Node instances must be at least supported.

max_publishers(value)

If the Service is created it defines how many Publisher shall be supported at most. If an existing Service is opened it defines how many Publisher must be at least supported.

max_subscribers(value)

If the Service is created it defines how many Subscriber shall be supported at most. If an existing Service is opened it defines how many Subscriber must be at least supported.

open()

Opens an existing Service. On failure it emits PublishSubscribeOpenError.

open_or_create()

If the Service exists, it will be opened otherwise a new Service will be created. On failure it emits PublishSubscribeOpenOrCreateError

open_or_create_with_attributes(verifier)

If the Service exists, it will be opened otherwise a new Service will be created. It defines a set of attributes. If the Service already exists all attribute requirements must be satisfied otherwise the open process will fail. If the Service does not exist the required attributes will be defined in the Service. On failure it emits PublishSubscribeOpenOrCreateError

open_with_attributes(verifier)

Opens an existing Service with attribute requirements. If the defined attribute requirements are not satisfied the open process will fail. On failure it emits PublishSubscribeOpenError.

payload_alignment(value)

Overrides and increases the alignment of the payload - useful when the payload is used in SIMD operations. To be able to connect to a Service the payload alignment must be identical in all participants since the communication is always strongly typed.

subscriber_max_borrowed_samples(value)

If the Service is created it defines the Sample count a Subscriber can borrow at most in parallel. If an existing Service is opened it defines the minimum required.

subscriber_max_buffer_size(value)

If the Service is created it defines how many Sample a Subscriber can store in its internal buffer. If an existing Service is opened it defines the minimum required.

user_header(t: Type[T]) → ServiceBuilderPublishSubscribe

Sets the user header type for the service.

class iceoryx2.ServiceBuilderRequestResponse

Bases: object

Builder to create a new MessagingPattern.RequestResponse based Service

create()

Creates a new Service. On failure RequestResponseCreateError will be emitted.

create_with_attributes(attributes)

Creates a new Service with a set of attributes. On failure RequestResponseCreateError will be emitted.

enable_fire_and_forget_requests(value)

If the Service is created, defines the fire-and-forget behavior of the service for requests.

enable_safe_overflow_for_requests(value)

If the Service is created, defines the overflow behavior of the service for requests. If an existing Service is opened it requires the service to have the defined overflow behavior.

enable_safe_overflow_for_responses(value)

If the Service is created, defines the overflow behavior of the service for responses. If an existing Service is opened it requires the service to have the defined overflow behavior.

max_active_requests_per_client(value)

Defines how many active requests a Server can hold in parallel per Client. The objects are used to send answers to a request that was received earlier from a Client.

max_borrowed_responses_per_pending_response(value)

If the Service is created it defines the Response count that shall be able to be borrowed in parallel per PendingResponse. If an existing Service is opened it defines how many borrows must be at least supported.

max_clients(value)

If the Service is created it defines how many Client ports shall be supported at most. If an existing Service is opened it defines how many Client ports must be at least supported.

max_loaned_requests(value)

If the Service is created it defines how many RequestMut a Client can loan in parallel.

max_nodes(value)

If the Service is created it defines how many Node instances shall be able to open it in parallel. If an existing Service is opened it defines how many Node instances must be at least supported.

max_response_buffer_size(value)

If the Service is created it defines how many responses fit in the Client’s buffer. If an existing Service is opened it defines the minimum required.

max_servers(value)

If the Service is created it defines how many Server ports shall be supported at most. If an existing Service is opened it defines how many Server ports must be at least supported.

open()

Opens an existing Service. On failure RequestResponseOpenError will be emitted.

open_or_create()

If the Service exists, it will be opened otherwise a new Service will be created. On failure RequestResponseOpenOrCreateError will be emitted.

open_or_create_with_attributes(verifier)

If the Service exists, it will be opened otherwise a new Service will be created. It defines a set of attributes.

If the Service already exists all attribute requirements must be satisfied, and service payload type must be the same, otherwise the open process will fail. If the Service does not exist the required attributes will be defined in the Service. On failure RequestResponseOpenOrCreateError will be emitted.

open_with_attributes(verifier)

Opens an existing Service with attribute requirements. If the defined attribute requirements are not satisfied the open process will fail. On failure RequestResponseOpenError will be emitted.

request_flatbuffer_schema_path(value: FilePath) → ServiceBuilderRequestResponse

Sets the path to the flatbuffer schema file.

If this is not explicitly defined, iceoryx2 will try to find the best fitting schema file in the configured filebuffer schema paths defined in the config.

request_header(request: Type[ReqT]) → ServiceBuilderPublishSubscribe

Sets the request header type for the service.

request_payload_alignment(value)

Overrides and increases the alignment of the request payload - useful when the payload is used in SIMD operations. To be able to connect to a Service the payload alignment must be identical in all participants since the communication is always strongly typed.

response_flatbuffer_schema_path(value: FilePath) → ServiceBuilderRequestResponse

Sets the path to the flatbuffer schema file.

If this is not explicitly defined, iceoryx2 will try to find the best fitting schema file in the configured filebuffer schema paths defined in the config.

response_header(response: Type[ResT]) → ServiceBuilderPublishSubscribe

Sets the response header type for the service.

response_payload_alignment(value)

Overrides and increases the alignment of the response payload - useful when the payload is used in SIMD operations. To be able to connect to a Service the payload alignment must be identical in all participants since the communication is always strongly typed.

class iceoryx2.ServiceDetails

Bases: object

Represents all the Service information that one can acquire with Service.list.

attributes()

Returns the attributes of the Service

messaging_pattern()

Returns the Service’s underlying MessagingPattern.

name()

Returns the ServiceName

nodes()

A list of every Node that is registered at the Service

service_hash()

Returns the unique ServiceHash of the Service

exception iceoryx2.ServiceDetailsError

Bases: Exception

Errors caused when acquiring the details of a service.

class iceoryx2.ServiceHash

Bases: object

The unique id of a Service

as_str

Returns a String containing the ServiceHash value

static max_number_of_characters()

Returns the maximum string length of a ServiceHash

class iceoryx2.ServiceName

Bases: object

Relocatable (inter-process shared memory compatible) SemanticString implementation for ServiceName. All modification operations ensure that never an invalid file or path name can be generated. All strings have a fixed size so that the maximum path or file name length the system supports can be stored.

static max_len()

Returns the maximum length of a ServiceName

static new(name)

Creates a new ServiceName when the provided name contains a valid path to a file, otherwise it emits a SemanticStringError.

to_string()

Converts the ServiceName into a str

exception iceoryx2.ServiceRemoveError

Bases: Exception

Errors caused when a Service is removed with Node::force_remove_service().

class iceoryx2.ServiceType

Bases: object

Defines the type of the Service and what kind of resources and operating system mechanisms it shall use.

Ipc = ServiceType.Ipc

Local = ServiceType.Local

class iceoryx2.SignalHandlingMode

Bases: object

Defines how signals are handled by constructs that might register a custom SignalHandler

Disabled = SignalHandlingMode.Disabled

HandleTerminationRequests = SignalHandlingMode.HandleTerminationRequests

class iceoryx2.Slice(data_ptr: int, number_of_elements: int, t: Type[T], owner: Any = None)

Bases: Generic[T]

A class representing a slice of contiguous elements of type T.

A Slice provides a view into a contiguous sequence of elements without owning the memory. It allows for efficient access and iteration over a portion of a contiguous data structure.

T - The type of elements in the slice. Can be const-qualified for read-only slices.

as_memory_view() → memoryview

Returns a memoryview over the elements of the Slice, without copying.

as_ptr() → int

Returns a pointer to the first element of the Slice.

len() → int

Returns the length / number of elements contained in the Slice.

class iceoryx2.StaticConfigBlackboard

Bases: object

The static configuration of an MessagingPattern.Blackboard based Service. Contains all parameters that do not change during the lifetime of a Service.

max_nodes

Returns the maximum supported amount of Node instances that can open the Service in parallel.

max_readers

Returns the maximum supported amount of Reader ports

type_details

Returns the type details of the Service.

class iceoryx2.StaticConfigEvent

Bases: object

The static configuration of an MessagingPattern.Event based service. Contains all parameters that do not change during the lifetime of a Service.

deadline

Returns the deadline of the service. If no new notification is signaled from any Notifier after the given deadline, it is rated as an error and every Listener that is attached to a WaitSet is woken up and notified about the missed

event_id_max_value

Returns the largest EventId that is supported by the service

max_listeners

Returns the maximum supported amount of Listener ports

max_nodes

Returns the maximum supported amount of Node instances that can open the Service in parallel.

max_notifiers

Returns the maximum supported amount of Notifier ports

notifier_created_event

Returns the emitted EventId when a new notifier is created.

notifier_dead_event

Returns the emitted EventId when a notifier is identified as dead.

notifier_dropped_event

Returns the emitted EventId when a notifier is dropped.

class iceoryx2.StaticConfigPublishSubscribe

Bases: object

The static configuration of an MessagingPattern.PublishSubscribe based Service. Contains all parameters that do not change during the lifetime of a Service.

has_safe_overflow

Returns true if the Service safely overflows, otherwise false. Safe overflow means that the Publisher will recycle the oldest Sample from the Subscriber when its buffer is full.

history_size

Returns the maximum history size that can be requested on connect.

max_nodes

Returns the maximum supported amount of Node instances that can open the Service in parallel.

max_publishers

Returns the maximum supported amount of Publisher ports

max_subscribers

Returns the maximum supported amount of Subscriber ports

message_type_details

Returns the type details of the Service.

subscriber_max_borrowed_samples

Returns how many Sample a Subscriber port can borrow in parallel at most.

subscriber_max_buffer_size

Returns the maximum supported buffer size for Subscriber port

class iceoryx2.StaticConfigRequestResponse

Bases: object

The static configuration of an MessagingPattern.RequestResponse based service. Contains all parameters that do not change during the lifetime of a Service.

does_support_fire_and_forget_requests

Returns true if a fire and forget RequestMut can be sent from the Client, otherwise false.

has_safe_overflow_for_requests

Returns true if the request buffer of the Service safely overflows, otherwise false. Safe overflow means that the Client will recycle the oldest requests from the Server when its buffer is full.

has_safe_overflow_for_responses

Returns true if the response buffer of the Service safely overflows, otherwise false. Safe overflow means that the Server will recycle the oldest responses from the Client when its buffer is full.

max_active_requests_per_client

Returns the maximum of active requests a Server can hold in parallel per Client.

max_borrowed_responses_per_pending_response

Returns the maximum borrowed Response count a Client can hold in parallel per PendingResponse

max_clients

Returns the maximum number of supported Client ports for the Service.

max_loaned_requests

Returns the maximum number of RequestMut a Client can loan in parallel.

max_nodes

Returns the maximum number of supported Node instances for the Service.

max_response_buffer_size

Returns the maximum buffer size for responses for a PendingResponse.

max_servers

Returns the maximum number of supported Server ports for the Service.

request_message_type_details

Returns the request type details of the Service.

response_message_type_details

Returns the response type details of the Service.

class iceoryx2.Subscriber

Bases: object

Represents the receiving endpoint of a publish-subscribe based communication.

buffer_size

Returns the internal buffer size of the Subscriber.

delete()

Releases the Subscriber.

After this call the Subscriber is no longer usable!

has_samples()

Returns true if the Subscriber has samples in the buffer that can be received with Subscriber.receive. Emits ConnectionFailure on error.

id

Returns the UniqueSubscriberId of the Subscriber

name

Returns the PortName of the Subscriber

receive()

Receives a Sample from Publisher. If no sample could be received None is returned. If a failure occurs ReceiveError is returned.

exception iceoryx2.SubscriberCreateError

Bases: Exception

Errors caused when creating a subscriber port.

class iceoryx2.TypeDetail

Bases: object

Contains all type details required to connect to a Service

alignment(alignment)

Sets the alignment of the type

static new()

Creates a new TypeDetail for the unit type. Meaning size == 0, alignment == 1

size(size)

Sets the size of the type

type_name(name)

Sets the unique TypeName of the type

type_variant(value)

Defines the TypeVariant of the defined type. TypeVariant.FixedSize if the type has always the same size like an ctypes.c_uint64 or TypeVariant.Dynamic when it is a dynamic array or vector

class iceoryx2.TypeName

Bases: object

Represents the string name of a type. The name shall uniquely identify the type in the communication system.

static max_len()

The maximum supported length of a TypeName

static new(name)

Creates a new TypeName. If the provided name exceeds the maximum supported length it emits an SemanticStringError.

to_string()

Returns the underlying str of the TypeName

class iceoryx2.TypeVariant

Bases: object

Defines if the type is a slice with a runtime-size (TypeVariant.Dynamic) or if its a type that satisfies Sized (TypeVariant.FixedSize).

Dynamic = TypeVariant.Dynamic

FixedSize = TypeVariant.FixedSize

class iceoryx2.UniqueClientId

Bases: object

The system-wide unique id of a Client.

value

Returns the underlying raw value of the ID

class iceoryx2.UniqueListenerId

Bases: object

The system-wide unique id of a Listener.

value

Returns the underlying raw value of the ID

class iceoryx2.UniqueNodeId

Bases: object

The system-wide unique id of a Node

pid(service_type)

Returns the process id of the process that owns the Node.

value

Returns the underlying integer value of the UniqueNodeId.

class iceoryx2.UniqueNotifierId

Bases: object

The system-wide unique id of a Notifier.

value

Returns the underlying raw value of the ID

class iceoryx2.UniquePublisherId

Bases: object

The system-wide unique id of a Publisher.

value

Returns the underlying raw value of the ID

class iceoryx2.UniqueReaderId

Bases: object

The system-wide unique id of a Reader.

value

Returns the underlying raw value of the ID

class iceoryx2.UniqueServerId

Bases: object

The system-wide unique id of a Server.

value

Returns the underlying raw value of the ID

class iceoryx2.UniqueSubscriberId

Bases: object

The system-wide unique id of a Subscriber.

value

Returns the underlying raw value of the ID

class iceoryx2.UniqueWriterId

Bases: object

The system-wide unique id of a Writer.

value

Returns the underlying raw value of the ID

class iceoryx2.WaitSet

Bases: object

The WaitSet implements a reactor pattern and allows to wait on multiple events in one single call WaitSet.wait_and_process until a interrupt or termination signal was received.

The Listener can be attached as well as sockets or anything else that is a FileDescriptor.

Can be created via the WaitSetBuilder.

attach_deadline(attachment, deadline)

Attaches a Listener as deadline to the WaitSet. Whenever the event is received or the deadline is hit, the user is informed in WaitSet.wait_and_process. The object cannot be attached twice and the WaitSet.capacity is limited by the underlying implementation. Whenever the object emits an event the deadline is reset by the WaitSet.

attach_deadline_fd(attachment, deadline)

Attaches a FileDescriptor as deadline to the WaitSet. Whenever the event is received or the deadline is hit, the user is informed in WaitSet.wait_and_process. The object cannot be attached twice and the WaitSet.capacity is limited by the underlying implementation. Whenever the object emits an event the deadline is reset by the WaitSet.

attach_interval(interval)

Attaches a tick event to the WaitSet. Whenever the timeout is reached the WaitSet informs the user in WaitSet.wait_and_process.

attach_notification(attachment)

Attaches a Listener as notification to the WaitSet. Whenever an event is received on the object the WaitSet informs the user in WaitSet.wait_and_process to handle the event. The object cannot be attached twice and the WaitSet.capacity is limited by the underlying implementation.

attach_notification_fd(attachment)

Attaches a FileDescriptor as notification to the WaitSet. Whenever an event is received on the object the WaitSet informs the user in WaitSet.wait_and_process to handle the event. The object cannot be attached twice and the WaitSet.capacity is limited by the underlying implementation.

capacity

Returns the capacity of the WaitSet

delete()

Releases the WaitSet.

After this call the WaitSet is no longer usable!

is_empty

Returns true if the WaitSet has no attachments, otherwise false.

len

Returns the number of attachments.

signal_handling_mode

Returns the SignalHandlingMode with which the WaitSet was created.

wait_and_process()

Waits until an event arrives on the WaitSet, then collects the events corresponding WaitSetAttachmentId in a vector and returns it.

If an interrupt- (signal.SIGINT) or a termination-signal (signal.SIGTERM) was received, it will exit the loop and inform the user with WaitSetRunResult.Interrupt or WaitSetRunResult.TerminationRequest.

Important: The WaitSet only reports that an attachment is ready; it does not consume the notification or data that caused the wake-up. If the callback returns without consuming any pending input, the attachment remains ready and the WaitSet wakes up again immediately. Repeating this can cause a busy loop and high CPU usage.

For a Listener, consume pending notifications with Listener.try_wait. For a socket or another file-descriptor-based attachment, consume the pending data using its corresponding read or receive API.

wait_and_process_with_timeout(timeout)

Waits until an event arrives on the WaitSet or the provided timeout has passed, then collects the events corresponding WaitSetAttachmentId in a vector and returns it.

If an interrupt- (signal.SIGINT) or a termination-signal (signal.SIGTERM) was received, it will exit the loop and inform the user with WaitSetRunResult.Interrupt or WaitSetRunResult.TerminationRequest.

Important: The WaitSet only reports that an attachment is ready; it does not consume the notification or data that caused the wake-up. If the callback returns without consuming any pending input, the attachment remains ready and the WaitSet wakes up again immediately. Repeating this can cause a busy loop and high CPU usage.

For a Listener, consume pending notifications with Listener.try_wait. For a socket or another file-descriptor-based attachment, consume the pending data using its corresponding read or receive API.

exception iceoryx2.WaitSetAttachmentError

Bases: Exception

Errors caused when attaching something to the waitset.

class iceoryx2.WaitSetAttachmentId

Bases: object

Represents an attachment to the WaitSet

static from_guard(guard)

Creates an WaitSetAttachmentId from a WaitSetGuard that was returned via WaitSet.attach_interval, WaitSet.attach_notification or WaitSet.attach_deadline.

has_event_from(other)

Returns true if an event was emitted from a notification or deadline attachment corresponding to WaitSetGuard.

has_missed_deadline(other)

Returns true if the deadline for the attachment corresponding to WaitSetGuard was missed.

class iceoryx2.WaitSetBuilder

Bases: object

Creates a new WaitSet.

create(service_type)

Creates the WaitSet.

static new()

Instantiates a new WaitSetBuilder

signal_handling_mode(value)

Defines the SignalHandlingMode for the WaitSet. It affects the WaitSet.wait_and_process and WaitSet.wait_and_process_with_timeout calls that returns any received Signal via its WaitSetRunResult return value.

exception iceoryx2.WaitSetCreateError

Bases: Exception

Errors caused by creating a new waitset.

class iceoryx2.WaitSetGuard

Bases: object

Is returned when something is attached to the WaitSet. As soon as it goes out of scope, the attachment is detached.

delete()

Drops the WaitSetGuard. After this call the WaitSetGuard is no longer usable.

exception iceoryx2.WaitSetRunError

Bases: Exception

Errors caused by calling WaitSet::wait_and_process().

class iceoryx2.WaitSetRunResult

Bases: object

States why the WaitSet.wait_and_process method returned.

AllEventsHandled = WaitSetRunResult.AllEventsHandled

Interrupt = WaitSetRunResult.Interrupt

StopRequest = WaitSetRunResult.StopRequest

TerminationRequest = WaitSetRunResult.TerminationRequest

class iceoryx2.Writer

Bases: object

Represents the writing endpoint of a blackboard based communication.

delete()

Releases the Writer.

After this call the Writer is no longer usable!

entry(key: Type[K], value: Type[V]) → EntryHandleMut

Creates an EntryHandleMut for direct write access to the value.

There can be only one EntryHandleMut per value. On failure it returns EntryHandleMutError describing the failure.

id

Returns the UniqueWriterId of the Writer

name

Returns the PortName of the Writer

exception iceoryx2.WriterCreateError

Bases: Exception

Errors caused when creating a writer port.

iceoryx2.get_type_name(t: Type[T]) → Any

Generates a human readable type name from a given type.

iceoryx2.set_log_level(value)

Sets the current log level. This is ignored for external frameworks like log or tracing. Here you have to use the log-level settings of that framework.

# Important

When using external frameworks, the log level should be set explicitly, as only messages matching that level will be forwarded. You may also need to configure the framework’s own log level settings.

iceoryx2.set_log_level_from_env_or(value)

Sets the log level by reading environment variable “IOX2_LOG_LEVEL”, and if the environment variable doesn’t exit it sets it with a user-defined logging level

# Important

When using external frameworks, the log level should be set explicitly, as only messages matching that level will be forwarded. You may also need to configure the framework’s own log level settings.

iceoryx2.set_log_level_from_env_or_default()

Sets the log level by reading environment variable “IOX2_LOG_LEVEL” or default it with LogLevel.Info

# Important

When using external frameworks, the log level should be set explicitly, as only messages matching that level will be forwarded. You may also need to configure the framework’s own log level settings.