Goby3  3.1.5a
2024.05.23
goby::middleware::InterThreadTransporter Class Reference

A transporter for the interthread layer. More...

#include <goby/middleware/transport/interthread.h>

Inheritance diagram for goby::middleware::InterThreadTransporter:
goby::middleware::StaticTransporterInterface< InterThreadTransporter, NullTransporter > goby::middleware::Poller< InterThreadTransporter > goby::middleware::InnerTransporterInterface< InterThreadTransporter, NullTransporter > goby::middleware::PollerInterface

Public Member Functions

 InterThreadTransporter ()
 
virtual ~InterThreadTransporter ()
 
template<const Group & group>
void check_validity ()
 Check validity of the Group for interthread use (at compile time) More...
 
void check_validity_runtime (const Group &group)
 Check validity of the Group for interthread use (for DynamicGroup at run time) More...
 
template<typename Data , int scheme = scheme<Data>()>
void publish_dynamic (const Data &data, const Group &group, const Publisher< Data > &publisher=Publisher< Data >())
 Publish a message using a run-time defined DynamicGroup (const reference variant). Where possible, prefer the static variant in StaticTransporterInterface::publish() More...
 
template<typename Data , int scheme = scheme<Data>()>
void publish_dynamic (std::shared_ptr< const Data > data, const Group &group, const Publisher< Data > &publisher=Publisher< Data >())
 Publish a message using a run-time defined DynamicGroup (shared pointer to const data variant). Where possible, prefer the static variant in StaticTransporterInterface::publish() More...
 
template<typename Data , int scheme = scheme<Data>()>
void publish_dynamic (std::shared_ptr< Data > data, const Group &group, const Publisher< Data > &publisher=Publisher< Data >())
 Publish a message using a run-time defined DynamicGroup (shared pointer to mutable data variant). Where possible, prefer the static variant in StaticTransporterInterface::publish() More...
 
template<const Group & group>
void publish_empty ()
 Publish with no data (used to signal another thread) More...
 
template<typename Data , int scheme = scheme<Data>()>
void subscribe_dynamic (std::function< void(const Data &)> f, const Group &group, const Subscriber< Data > &=Subscriber< Data >())
 Subscribe to a specific run-time defined group and data type (const reference variant). Where possible, prefer the static variant in StaticTransporterInterface::subscribe() More...
 
template<typename Data , int scheme = scheme<Data>()>
void subscribe_dynamic (std::function< void(std::shared_ptr< const Data >)> f, const Group &group, const Subscriber< Data > &=Subscriber< Data >())
 Subscribe to a specific run-time defined group and data type (shared pointer variant). Where possible, prefer the static variant in StaticTransporterInterface::subscribe() More...
 
template<const Group & group>
void subscribe_empty (const std::function< void()> &f)
 Subscribe with no data (used to receive a signal from another thread) More...
 
template<typename Data , int scheme = scheme<Data>()>
void unsubscribe_dynamic (const Group &group, const Subscriber< Data > &=Subscriber< Data >())
 Unsubscribe to a specific run-time defined group and data type. Where possible, prefer the static variant in StaticTransporterInterface::unsubscribe() More...
 
void unsubscribe_all ()
 Unsubscribe from all current subscriptions. More...
 
- Public Member Functions inherited from goby::middleware::StaticTransporterInterface< InterThreadTransporter, NullTransporter >
void publish (const Data &data, const Publisher< Data > &publisher=Publisher< Data >())
 Publish a message (const reference variant) More...
 
void publish (std::shared_ptr< const Data > data, const Publisher< Data > &publisher=Publisher< Data >())
 Publish a message (shared pointer to const data variant) More...
 
void publish (std::shared_ptr< Data > data, const Publisher< Data > &publisher=Publisher< Data >())
 Publish a message (shared pointer to mutable data variant) More...
 
void subscribe (std::function< void(const Data &)> f, const Subscriber< Data > &subscriber=Subscriber< Data >())
 Subscribe to a specific group and data type (const reference variant) More...
 
void subscribe (std::function< void(std::shared_ptr< const Data >)> f, const Subscriber< Data > &subscriber=Subscriber< Data >())
 Subscribe to a specific group and data type (shared pointer variant) More...
 
void subscribe (Func f)
 Simplified version of subscribe() that can deduce Data from the first argument of the function (lambda, function pointer, etc.) passed to it. More...
 
void unsubscribe (const Subscriber< Data > &subscriber=Subscriber< Data >())
 Unsubscribe to a specific group and data type. More...
 
void unsubscribe_all ()
 Unsubscribe to all messages that this transporter has subscribed to. More...
 
- Public Member Functions inherited from goby::middleware::InnerTransporterInterface< InterThreadTransporter, NullTransporter >
NullTransporterinner ()
 
auto innermost ()
 
- Public Member Functions inherited from goby::middleware::PollerInterface
template<class Clock = std::chrono::system_clock, class Duration = typename Clock::duration>
int poll (const std::chrono::time_point< Clock, Duration > &timeout=std::chrono::time_point< Clock, Duration >::max())
 poll for data. Blocks until a data event occurs or a timeout when a particular time has been reached More...
 
template<class Clock = std::chrono::system_clock, class Duration = typename Clock::duration>
int poll (Duration wait_for)
 poll for data. Blocks until a data event occurs or a certain duration of time elapses (timeout) More...
 
std::shared_ptr< std::timed_mutex > poll_mutex ()
 access the mutex used for poll synchronization More...
 
std::shared_ptr< std::condition_variable_any > cv ()
 access the condition variable used for poll synchronization More...
 

Static Public Member Functions

template<typename Data >
static constexpr int scheme ()
 Scheme for interthread is always MarshallingScheme::CXX_OBJECT as the data are not serialized, but rather passed around using shared pointers. More...
 

Additional Inherited Members

- Public Types inherited from goby::middleware::InnerTransporterInterface< InterThreadTransporter, NullTransporter >
using InnerTransporterType = NullTransporter
 the InnerTransporter type (accessible for other uses) More...
 
- Protected Member Functions inherited from goby::middleware::StaticTransporterInterface< InterThreadTransporter, NullTransporter >
 StaticTransporterInterface (NullTransporter &inner)
 
 StaticTransporterInterface ()
 
- Protected Member Functions inherited from goby::middleware::Poller< InterThreadTransporter >
 Poller (PollerInterface *inner_poller=nullptr)
 Construct this Poller with a pointer to the inner Poller (unless this is the innermost Poller) More...
 
PollerInterfaceinner_poller ()
 
- Protected Member Functions inherited from goby::middleware::PollerInterface
 PollerInterface (std::shared_ptr< std::timed_mutex > poll_mutex, std::shared_ptr< std::condition_variable_any > cv)
 

Detailed Description

A transporter for the interthread layer.

As no layer exists inside the interthread layer, no distinction is made between interthread "portals" and "forwarders". This class serves both purposes, providing a no-copy publish/subscribe interface for interthread communications using std::shared_ptr (for maximum efficiency, use the shared pointer overloads for publish). As no copy is made, the publisher must not modify the underlying data after calling publish, as this would lead to potentially unsafe data races when subscribed nodes read the data.

auto data = std::make_shared<protobuf::NavigationReport>();
data->set_x(100);
interthread.publish<groups::nav>(data);
// after this point 'data' should not be mutated (but may be read or re-published)

Definition at line 56 of file interthread.h.

Constructor & Destructor Documentation

◆ InterThreadTransporter()

goby::middleware::InterThreadTransporter::InterThreadTransporter ( )
inline

Definition at line 66 of file interthread.h.

◆ ~InterThreadTransporter()

virtual goby::middleware::InterThreadTransporter::~InterThreadTransporter ( )
inlinevirtual

Definition at line 68 of file interthread.h.

Member Function Documentation

◆ check_validity()

template<const Group & group>
void goby::middleware::InterThreadTransporter::check_validity ( )
inline

Check validity of the Group for interthread use (at compile time)

Definition at line 78 of file interthread.h.

◆ check_validity_runtime()

void goby::middleware::InterThreadTransporter::check_validity_runtime ( const Group group)
inline

Check validity of the Group for interthread use (for DynamicGroup at run time)

Definition at line 86 of file interthread.h.

◆ publish_dynamic() [1/3]

template<typename Data , int scheme = scheme<Data>()>
void goby::middleware::InterThreadTransporter::publish_dynamic ( const Data &  data,
const Group group,
const Publisher< Data > &  publisher = Publisher<Data>() 
)
inline

Publish a message using a run-time defined DynamicGroup (const reference variant). Where possible, prefer the static variant in StaticTransporterInterface::publish()

Template Parameters
Datadata type to publish. Can usually be inferred from the data parameter.
schemeMarshalling scheme id (typically MarshallingScheme::MarshallingSchemeEnum). Can usually be inferred from the Data type.
Parameters
dataMessage to publish
groupgroup to publish this message to (typically a DynamicGroup)
publisherOptional metadata that controls the publication or sets callbacks to monitor the result. Typically unnecessary for interprocess and inner layers.

Definition at line 100 of file interthread.h.

◆ publish_dynamic() [2/3]

template<typename Data , int scheme = scheme<Data>()>
void goby::middleware::InterThreadTransporter::publish_dynamic ( std::shared_ptr< const Data >  data,
const Group group,
const Publisher< Data > &  publisher = Publisher<Data>() 
)
inline

Publish a message using a run-time defined DynamicGroup (shared pointer to const data variant). Where possible, prefer the static variant in StaticTransporterInterface::publish()

Template Parameters
Datadata type to publish. Can usually be inferred from the data parameter.
schemeMarshalling scheme id (typically MarshallingScheme::MarshallingSchemeEnum). Can usually be inferred from the Data type.
Parameters
dataMessage to publish
groupgroup to publish this message to (typically a DynamicGroup)
publisherOptional metadata that controls the publication or sets callbacks to monitor the result. Typically unnecessary for interprocess and inner layers.

Definition at line 116 of file interthread.h.

◆ publish_dynamic() [3/3]

template<typename Data , int scheme = scheme<Data>()>
void goby::middleware::InterThreadTransporter::publish_dynamic ( std::shared_ptr< Data >  data,
const Group group,
const Publisher< Data > &  publisher = Publisher<Data>() 
)
inline

Publish a message using a run-time defined DynamicGroup (shared pointer to mutable data variant). Where possible, prefer the static variant in StaticTransporterInterface::publish()

Template Parameters
Datadata type to publish. Can usually be inferred from the data parameter.
schemeMarshalling scheme id (typically MarshallingScheme::MarshallingSchemeEnum). Can usually be inferred from the Data type.
Parameters
dataMessage to publish
groupgroup to publish this message to (typically a DynamicGroup)
publisherOptional metadata that controls the publication or sets callbacks to monitor the result. Typically unnecessary for interprocess and inner layers.

Definition at line 131 of file interthread.h.

◆ publish_empty()

template<const Group & group>
void goby::middleware::InterThreadTransporter::publish_empty ( )
inline

Publish with no data (used to signal another thread)

Definition at line 138 of file interthread.h.

◆ scheme()

template<typename Data >
static constexpr int goby::middleware::InterThreadTransporter::scheme ( )
inlinestaticconstexpr

Scheme for interthread is always MarshallingScheme::CXX_OBJECT as the data are not serialized, but rather passed around using shared pointers.

Definition at line 75 of file interthread.h.

◆ subscribe_dynamic() [1/2]

template<typename Data , int scheme = scheme<Data>()>
void goby::middleware::InterThreadTransporter::subscribe_dynamic ( std::function< void(const Data &)>  f,
const Group group,
const Subscriber< Data > &  = Subscriber<Data>() 
)
inline

Subscribe to a specific run-time defined group and data type (const reference variant). Where possible, prefer the static variant in StaticTransporterInterface::subscribe()

Template Parameters
Datadata type to subscribe to.
schemeMarshalling scheme id (typically MarshallingScheme::MarshallingSchemeEnum). Can usually be inferred from the Data type.
Parameters
fCallback function or lambda that is called upon receipt of the subscribed data
groupgroup to subscribe to (typically a DynamicGroup)

Definition at line 151 of file interthread.h.

◆ subscribe_dynamic() [2/2]

template<typename Data , int scheme = scheme<Data>()>
void goby::middleware::InterThreadTransporter::subscribe_dynamic ( std::function< void(std::shared_ptr< const Data >)>  f,
const Group group,
const Subscriber< Data > &  = Subscriber<Data>() 
)
inline

Subscribe to a specific run-time defined group and data type (shared pointer variant). Where possible, prefer the static variant in StaticTransporterInterface::subscribe()

Template Parameters
Datadata type to subscribe to.
schemeMarshalling scheme id (typically MarshallingScheme::MarshallingSchemeEnum). Can usually be inferred from the Data type.
Parameters
fCallback function or lambda that is called upon receipt of the subscribed data
groupgroup to subscribe to (typically a DynamicGroup)

Definition at line 168 of file interthread.h.

◆ subscribe_empty()

template<const Group & group>
void goby::middleware::InterThreadTransporter::subscribe_empty ( const std::function< void()> &  f)
inline

Subscribe with no data (used to receive a signal from another thread)

Definition at line 178 of file interthread.h.

◆ unsubscribe_all()

void goby::middleware::InterThreadTransporter::unsubscribe_all ( )
inline

Unsubscribe from all current subscriptions.

Definition at line 198 of file interthread.h.

◆ unsubscribe_dynamic()

template<typename Data , int scheme = scheme<Data>()>
void goby::middleware::InterThreadTransporter::unsubscribe_dynamic ( const Group group,
const Subscriber< Data > &  = Subscriber<Data>() 
)
inline

Unsubscribe to a specific run-time defined group and data type. Where possible, prefer the static variant in StaticTransporterInterface::unsubscribe()

Template Parameters
Datadata type to unsubscribe from.
schemeMarshalling scheme id (typically MarshallingScheme::MarshallingSchemeEnum). Can usually be inferred from the Data type.
Parameters
groupgroup to unsubscribe from (typically a DynamicGroup)

Definition at line 190 of file interthread.h.


The documentation for this class was generated from the following file:
goby::middleware::InterThreadTransporter::InterThreadTransporter
InterThreadTransporter()
Definition: interthread.h:66