Class CPublisher#

Defined in File ecal_publisher.h

Inheritance Relationships#

Derived Type#

public eCAL::CMsgPublisher< T > (Template Class CMsgPublisher)

Class Documentation#

class CPublisher#

eCAL publisher class.

class is used to send topics to matching eCAL subscribers. The topic is created automatically by the constructor or by the Create member function.

For sending the topic payload the publisher class provides an overloaded Send method. The first one is sending the payload as a std::string. The second needs a preallocated buffer described by a buffer address and a buffer length. The publisher is not taking the ownership for the allocated memory buffer.

An optional time stamp can be attached to the topic payload.

// create publisher, topic name "A"
eCAL::CPublisher pub("A");

// send string
std::string send_s = "Hello World ";

// send content
size_t snd_len = pub.Send(send_s);

Subclassed by eCAL::CMsgPublisher< T >

Public Functions

CPublisher()#: Constructor.

CPublisher(const std::string &topic_name_, const std::string &topic_type_ = "", const std::string &topic_desc_ = "")#

Constructor.

Parameters

topic_name_ – Unique topic name.
topic_type_ – Type name (optional).
topic_desc_ – Type description (optional).

virtual ~CPublisher()#: Destructor.

CPublisher(const CPublisher&) = delete#: CPublishers are non-copyable.

CPublisher &operator=(const CPublisher&) = delete#: CPublishers are non-copyable.

CPublisher(CPublisher &&rhs) noexcept#: CPublishers are move-enabled.

CPublisher &operator=(CPublisher &&rhs) noexcept#: CPublishers are move-enabled.

bool Create(const std::string &topic_name_, const std::string &topic_type_ = "", const std::string &topic_desc_ = "")#

Creates this object.

Parameters

topic_name_ – Unique topic name.
topic_type_ – Type name (optional).
topic_desc_ – Type description (optional).

Returns

True if it succeeds, false if it fails.

bool Destroy()#

Destroys this object.

Returns: True if it succeeds, false if it fails.

bool SetTypeName(const std::string &topic_type_name_)#

Setup topic type name.

Parameters: topic_type_name_ – Topic type name.
Returns: True if it succeeds, false if it fails.

bool SetDescription(const std::string &topic_desc_)#

Setup topic description.

Parameters: topic_desc_ – Description string.
Returns: True if it succeeds, false if it fails.

bool SetAttribute(const std::string &attr_name_, const std::string &attr_value_)#

Sets publisher attribute.

This feature is marked as experimental:

Parameters

attr_name_ – Attribute name.
attr_value_ – Attribute value.

Returns

True if it succeeds, false if it fails.

bool ClearAttribute(const std::string &attr_name_)#

Removes publisher attribute.

This feature is marked as experimental:

Parameters: attr_name_ – Attribute name.
Returns: True if it succeeds, false if it fails.

bool ShareType(bool state_ = true)#

Share topic type.

Parameters: state_ – Set type share mode (true == share type).
Returns: True if it succeeds, false if it fails.

bool ShareDescription(bool state_ = true)#

Share topic description.

Parameters: state_ – Set description share mode (true == share description).
Returns: True if it succeeds, false if it fails.

bool SetQOS(const QOS::SWriterQOS &qos_)#

Set publisher quality of service attributes.

Parameters: qos_ – Quality of service policies.
Returns: True if it succeeds, false if it fails.

QOS::SWriterQOS GetQOS()#

Get current publisher quality of service attributes.

Returns: Quality of service attributes.

bool SetLayerMode(TLayer::eTransportLayer layer_, TLayer::eSendMode mode_)#

Set publisher send mode for specific transport layer.

Parameters

layer_ – Transport layer.
mode_ – Send mode.

Returns

True if it succeeds, false if it fails.

bool SetMaxBandwidthUDP(long bandwidth_)#

Set publisher maximum transmit bandwidth for the udp layer.

Parameters: bandwidth_ – Maximum bandwidth in bytes/s (-1 == unlimited).
Returns: True if it succeeds, false if it fails.

bool ShmSetBufferCount(long buffering_)#

Set publisher maximum number of used shared memory buffers.

Parameters: buffering_ – Maximum number of used buffers (needs to be greater than 1, default = 1).
Returns: True if it succeeds, false if it fails.

bool ShmEnableZeroCopy(bool state_)#

Enable zero copy shared memory transport mode.

By default, the built-in shared memory layer is configured to make one memory copy on the receiver side. That means the payload is copied by the internal eCAL memory pool manager out of the memory file and the file is closed immediately after this. The intention of this implementation is to free the file as fast as possible after reading its content to allow other subscribing processes to access the content with minimal latency. The different reading subscribers are fully decoupled and can access their memory copy independently.

If ShmEnableZeroCopy is switched on no memory will be copied at all. The user message callback is called right after opening the memory file. A direct pointer to the memory payload is forwarded and can be processed with no latency. The memory file will be closed after the user callback function returned. The advantage of this configuration is a much higher performance for large payloads (> 1024 kB). The disadvantage of this configuration is that in the time when the callback is executed the memory file is blocked for other subscribers and for writing publishers too. Maybe this can be eliminated by a better memory file read/write access implementation (lock free read) in future releases.

Today, for specific scenarios (1:1 pub/sub connections with large payloads for example) this feature can increase the performance remarkable. But please keep in mind to return from the message callback function as fast as possible to not delay subsequent read/write access operations.

Parameters: state_ – Set type zero copy mode for shared memory transport layer (true == zero copy enabled).
Returns: True if it succeeds, false if it fails.

bool ShmSetAcknowledgeTimeout(long long acknowledge_timeout_ms_)#

Force connected subscribers to send acknowledge event after processing the message and block publisher send call on this event with a timeout.

Most applications perform very well with the default behavior. If subscribers are too slow to process incoming messages then the overall software architecture needs to be checked, software components need to be optimized or parallelized.

There may still be cases where it could make sense to synchronize the transfer of the payload from a publisher to a subscriber by using an additional handshake event. This event is signaled by a subscriber back to the sending publisher to confirm the complete payload transmission and the processed subscriber callback.

The publisher will wait up to the specified timeout for the acknowledge signals of all connected subscribers before sending new content. Finally that means the publishers CPublisher::Send API function call is now blocked and will not return until all subscriber have read and processed their content or the timeout has been reached.

Parameters: acknowledge_timeout_ms_ – timeout to wait for acknowledge signal from connected subscriber in ms (0 == no handshake).
Returns: True if it succeeds, false if it fails.

template<typename Rep, typename Period> inline bool ShmSetAcknowledgeTimeout(std::chrono::duration<Rep, Period> acknowledge_timeout_)#

Force connected subscribers to send acknowledge event after processing the message and block publisher send call on this event with a timeout.

See ShmSetAcknowledgeTimeout(long long acknowledge_timeout_ms_)

Parameters: acknowledge_timeout_ – timeout to wait for acknowledge signal from connected subscriber (0 == no handshake).
Returns: True if it succeeds, false if it fails.

bool SetID(long long id_)#

Set the specific topic id.

Parameters: id_ – The topic id for subscriber side filtering (0 == no id).
Returns: True if it succeeds, false if it fails.

size_t Send(const void *const buf_, size_t len_, long long time_ = -1) const#

Send a message to all subscribers.

Parameters

buf_ – Pointer to content buffer.
len_ – Length of buffer.
time_ – Send time (-1 = use eCAL system time in us, default = -1).

Returns

Number of bytes sent.

size_t Send(const std::string &s_, long long time_ = -1) const#

Send a message to all subscribers.

Parameters

s_ – String that contains content to send.
time_ – Send time (-1 = use eCAL system time in us, default = -1).

Returns

Number of bytes sent.

size_t SendSynchronized(const void *const buf_, size_t len_, long long time_, long long acknowledge_timeout_ms_) const#

Send a message to all subscribers synchronized with acknowledge timeout (see also ShmSetAcknowledgeTimeout).

This synchronized mode is currently implemented for local interprocess communication (shm-ecal layer) only.

Parameters

buf_ – Pointer to content buffer.
len_ – Length of buffer.
time_ – Send time (-1 = use eCAL system time in us).
acknowledge_timeout_ms_ – Maximum time to wait for all subscribers acknowledge feedback in ms (buffer received and processed).

Returns

Number of bytes sent.

bool AddEventCallback(eCAL_Publisher_Event type_, PubEventCallbackT callback_)#

Add callback function for publisher events.

Parameters

type_ – The event type to react on.
callback_ – The callback function to add.

Returns

True if succeeded, false if not.

bool RemEventCallback(eCAL_Publisher_Event type_)#

Remove callback function for publisher events.

Parameters: type_ – The event type to remove.
Returns: True if succeeded, false if not.

inline bool IsCreated() const#

Query if the publisher is created.

Returns: True if created, false if not.

bool IsSubscribed() const#

Query if the publisher is subscribed.

Returns: true if subscribed, false if not.

size_t GetSubscriberCount() const#

Query the number of subscribers.

Returns: Number of subscribers.

std::string GetTopicName() const#

Gets name of the connected topic.

Returns: The topic name.

std::string GetTypeName() const#

Gets type of the connected topic.

Returns: The type name.

std::string GetDescription() const#

Gets description of the connected topic.

Returns: The description.

std::string Dump(const std::string &indent_ = "") const#

Dump the whole class state into a string.

Parameters: indent_ – Indentation used for dump.
Returns: The dump string.

Class CPublisher

Contents

Class CPublisher#

Inheritance Relationships#

Derived Type#

Class Documentation#