iceoryx_doc  1.0.1
Classes | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
iox::popo::Listener Class Reference

The Listener is a class which reacts to registered events by executing a corresponding callback concurrently. This is achieved via an encapsulated thread inside this class. More...

#include <listener.hpp>

Public Member Functions

 Listener (const Listener &)=delete
 
 Listener (Listener &&)=delete
 
Listeneroperator= (const Listener &)=delete
 
Listeneroperator= (Listener &&)=delete
 
template<typename T , typename EventType , typename ContextDataType , typename = std::enable_if_t<std::is_enum<EventType>::value>>
cxx::expected< ListenerError > attachEvent (T &eventOrigin, const EventType eventType, const NotificationCallback< T, ContextDataType > &eventCallback) noexcept
 Attaches an event. Hereby the event is defined as a class T, the eventOrigin, an enum which further defines the event inside the class and the corresponding callback which will be called when the event occurs. More...
 
template<typename T , typename ContextDataType >
cxx::expected< ListenerError > attachEvent (T &eventOrigin, const NotificationCallback< T, ContextDataType > &eventCallback) noexcept
 Attaches an event. Hereby the event is defined as a class T, the eventOrigin and the corresponding callback which will be called when the event occurs. More...
 
template<typename T , typename EventType , typename = std::enable_if_t<std::is_enum<EventType>::value>>
void detachEvent (T &eventOrigin, const EventType eventType) noexcept
 Detaches an event. Hereby, the event is defined as a class T, the eventOrigin and the eventType with further specifies the event inside of eventOrigin. More...
 
template<typename T >
void detachEvent (T &eventOrigin) noexcept
 Detaches an event. Hereby, the event is defined as a class T, the eventOrigin. More...
 
uint64_t size () const noexcept
 Returns the size of the Listener. More...
 
template<typename T , typename UserType >
cxx::expected< ListenerError > attachEvent (T &eventOrigin, const NotificationCallback< T, UserType > &eventCallback) noexcept
 
template<typename T , typename EventType , typename UserType , typename >
cxx::expected< ListenerError > attachEvent (T &eventOrigin, const EventType eventType, const NotificationCallback< T, UserType > &eventCallback) noexcept
 

Static Public Member Functions

static constexpr uint64_t capacity () noexcept
 Returns the capacity of the Listener. More...
 

Protected Member Functions

 Listener (ConditionVariableData &conditionVariableData) noexcept
 

Detailed Description

The Listener is a class which reacts to registered events by executing a corresponding callback concurrently. This is achieved via an encapsulated thread inside this class.

Note
The Listener is threadsafe and can be used without any restrictions concurrently.
Attention
Calling detachEvent for the same event from multiple threads is supported but can cause a race condition if you attach the same event again concurrently from another thread. Example:
  1. One calls detachEvent [1] from thread A, B and C
  2. thread B wins and detaches event [1]
  3. A new thread D spawns and would like to attach event [1] again while thread A and C are still waiting to detach [1].
  4. Thread A wins but cannot detach event [1] since it is not attached.
  5. Thread D wins and attaches event [1].
  6. Finally thread C can continue and detaches event [1] again.

If thread D is executed last then the event is attached. So depending on the operating system defined execution order the event is either attached or detached.

Best practice: Detach a specific event only from one specific thread and not from multiple contexts.

Member Function Documentation

◆ attachEvent() [1/2]

template<typename T , typename EventType , typename ContextDataType , typename = std::enable_if_t<std::is_enum<EventType>::value>>
cxx::expected<ListenerError> iox::popo::Listener::attachEvent ( T &  eventOrigin,
const EventType  eventType,
const NotificationCallback< T, ContextDataType > &  eventCallback 
)
noexcept

Attaches an event. Hereby the event is defined as a class T, the eventOrigin, an enum which further defines the event inside the class and the corresponding callback which will be called when the event occurs.

Note
This method can be called from any thread concurrently without any restrictions! Furthermore, attachEvent does not take ownership of callback in the underlying eventCallback or the optional contextData. The user has to ensure that both will live as long as the event is attached.
Template Parameters

◆ attachEvent() [2/2]

template<typename T , typename ContextDataType >
cxx::expected<ListenerError> iox::popo::Listener::attachEvent ( T &  eventOrigin,
const NotificationCallback< T, ContextDataType > &  eventCallback 
)
noexcept

Attaches an event. Hereby the event is defined as a class T, the eventOrigin and the corresponding callback which will be called when the event occurs.

Note
This method can be called from any thread concurrently without any restrictions! Furthermore, attachEvent does not take ownership of callback in the underlying eventCallback or the optional contextData. The user has to ensure that both will live as long as the event is attached.
Template Parameters

◆ capacity()

constexpr uint64_t iox::popo::Listener::capacity ( )
inlinestaticconstexprnoexcept

Returns the capacity of the Listener.

Returns
capacity of the Listener

◆ detachEvent() [1/2]

template<typename T >
void iox::popo::Listener::detachEvent ( T &  eventOrigin)
inlinenoexcept

Detaches an event. Hereby, the event is defined as a class T, the eventOrigin.

Note
This method can be called from any thread concurrently without any restrictions!
Template Parameters

◆ detachEvent() [2/2]

template<typename T , typename EventType , typename >
void iox::popo::Listener::detachEvent ( T &  eventOrigin,
const EventType  eventType 
)
inlinenoexcept

Detaches an event. Hereby, the event is defined as a class T, the eventOrigin and the eventType with further specifies the event inside of eventOrigin.

Note
This method can be called from any thread concurrently without any restrictions!
Template Parameters

◆ size()

uint64_t iox::popo::Listener::size ( ) const
noexcept

Returns the size of the Listener.

Returns
size of the Listener

The documentation for this class was generated from the following files: