Skip to content
Eclipse eCAL™

class eCAL::CPublisher

eCAL publisher class.

The CPublisher 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.

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


4
// send string
5
std::string send_s = "Hello World ";
6


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

Members

public ECAL_API CPublisher()

Constructor.

public ECAL_API CPublisher(const std::string & topic_name_,const std::string & topic_type_,const std::string & topic_desc_)

Constructor.

Deprecated: Please use the constructor CPublisher(const std::string& topic_name_, const SDataTypeInformation& topic_info_) instead. This function will be removed in future eCAL versions.

Parameters

  • topic_name_ Unique topic name.

  • topic_type_ Type name.

  • topic_desc_ Type description (optional).

public ECAL_API CPublisher(const std::string & topic_name_,const SDataTypeInformation & topic_info_)

Constructor.

Parameters

  • topic_name_ Unique topic name.

  • topic_info_ Topic information (encoding, type, descriptor)

public ECAL_API CPublisher(const std::string & topic_name_)

Constructor.

Parameters

  • topic_name_ Unique topic name.

public virtual ECAL_API ~CPublisher()

Destructor.

public ECAL_API CPublisher(const CPublisher &) = delete

CPublishers are non-copyable.

public ECAL_API CPublisher&operator=(const CPublisher &) = delete

CPublishers are non-copyable.

public ECAL_API CPublisher(CPublisher && rhs) noexcept

CPublishers are move-enabled.

public ECAL_API CPublisher&operator=(CPublisher && rhs) noexcept

CPublishers are move-enabled.

public ECAL_API bool Create(const std::string & topic_name_,const std::string & topic_type_,const std::string & topic_desc_)

Creates this object.

Deprecated: Please use the create method bool Create(const std::string& topic_name_, const SDataTypeInformation& topic_info_) instead. This function will be removed in future eCAL versions.

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.

public ECAL_API bool Create(const std::string & topic_name_,const SDataTypeInformation & topic_info_)

Creates this object.

Parameters

  • topic_name_ Unique topic name.

  • topic_info_ Topic information (encoding, type, descriptor)

Returns

True if it succeeds, false if it fails.

public inline ECAL_API bool Create(const std::string & topic_name_)

Creates this object.

Parameters

  • topic_name_ Unique topic name.

Returns

True if it succeeds, false if it fails.

public ECAL_API bool Destroy()

Destroys this object.

Returns

True if it succeeds, false if it fails.

public ECAL_API bool SetTypeName(const std::string & topic_type_name_)

Setup topic type name.

Deprecated: Please use the method bool SetDataTypeInformation(const SDataTypeInformation& topic_info_) instead. This function will be removed in future eCAL versions.

Parameters

  • topic_type_name_ Topic type name.

Returns

True if it succeeds, false if it fails.

public ECAL_API bool SetDescription(const std::string & topic_desc_)

Setup topic description.

Deprecated: Please use the method bool SetDataTypeInformation(const SDataTypeInformation& topic_info_) instead. This function will be removed in future eCAL versions.

Parameters

  • topic_desc_ Description string.

Returns

True if it succeeds, false if it fails.

public ECAL_API bool SetDataTypeInformation(const SDataTypeInformation & topic_info_)

Setup topic information.

Parameters

  • topic_info_ Topic information attributes.

Returns

True if it succeeds, false if it fails.

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

Sets publisher attribute.

Parameters

  • attr_name_ Attribute name.

  • attr_value_ Attribute value.

Returns

True if it succeeds, false if it fails. @experimental

public ECAL_API bool ClearAttribute(const std::string & attr_name_)

Removes publisher attribute.

Parameters

  • attr_name_ Attribute name.

Returns

True if it succeeds, false if it fails. @experimental

public ECAL_API bool ShareType(bool state_)

Share topic type.

Parameters

  • state_ Set type share mode (true == share type).

Returns

True if it succeeds, false if it fails.

public ECAL_API bool ShareDescription(bool state_)

Share topic description.

Parameters

  • state_ Set description share mode (true == share description).

Returns

True if it succeeds, false if it fails.

public ECAL_API bool SetQOS(const QOS::SWriterQOS & qos_)

Set publisher quality of service attributes.

Deprecated: Will be removed in future eCAL versions.

Parameters

  • qos_ Quality of service policies.

Returns

True if it succeeds, false if it fails.

public ECAL_API QOS::SWriterQOS GetQOS()

Get current publisher quality of service attributes.

Deprecated: Will be removed in future eCAL versions.

Returns

Quality of service attributes.

public ECAL_API 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.

public ECAL_API bool SetMaxBandwidthUDP(long bandwidth_)

Set publisher maximum transmit bandwidth for the udp layer.

Deprecated: Will be removed in future eCAL versions.

Parameters

  • bandwidth_ Maximum bandwidth in bytes/s (-1 == unlimited).

Returns

True if it succeeds, false if it fails.

public ECAL_API 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.

public ECAL_API bool ShmEnableZeroCopy(bool state_)

Enable zero copy shared memory transport mode.

By default, the built-in shared memory layer is configured to make two memory copies one on the publisher and one on the subscriber side.

The intention of this implementation is to free the file as fast as possible after writing and reading its content to allow other processes to access the content with minimal latency. The publisher and subscribers are fully decoupled and can access their internal memory copy independently.

If ShmEnableZeroCopy is switched on no memory will be copied at all using the low level binary publish / subscribe API. On publisher side the memory copy is exectuted into the opened memory file. On the subscriber side 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.

By using the eCAL::CPayloadWriter API a full zero copy implementation is possible by providing separate methods for the initialization and the modification of the memory file content (see CPayloadWriter documentation).

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.

public ECAL_API 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.

public template<>
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.

public ECAL_API 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.

public ECAL_API size_t Send(const void * buf_,size_t len_,long long time_) 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.

public ECAL_API size_t Send(CPayloadWriter & payload_,long long time_) const

Send a message to all subscribers.

Parameters

  • payload_ Payload.

  • time_ Send time (-1 = use eCAL system time in us, default = -1).

Returns

Number of bytes sent.

public ECAL_API size_t Send(const void * 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.

public inline ECAL_API 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).

Deprecated: Please use the method size_t Send(CPayloadWriter& payload_, long long time_, long long acknowledge_timeout_ms_) const instead. This function will be removed in future eCAL versions.

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.

public ECAL_API size_t Send(CPayloadWriter & payload_,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

  • payload_ Payload.

  • 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.

public inline ECAL_API size_t Send(const std::string & s_,long long time_) 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.

public inline ECAL_API size_t Send(const std::string & s_,long long time_,long long acknowledge_timeout_ms_) const

Send a message to all subscribers synchronized.

Parameters

  • s_ String that contains content to send.

  • 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.

public ECAL_API 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.

public ECAL_API 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.

public inline ECAL_API bool IsCreated() const

Query if the publisher is created.

Returns

True if created, false if not.

public ECAL_API bool IsSubscribed() const

Query if the publisher is subscribed.

Returns

true if subscribed, false if not.

public ECAL_API size_t GetSubscriberCount() const

Query the number of subscribers.

Returns

Number of subscribers.

public ECAL_API std::string GetTopicName() const

Gets name of the connected topic.

Returns

The topic name.

public ECAL_API std::string GetTypeName() const

Gets type of the connected topic.

Deprecated: Please use the method SDataTypeInformationGetDataTypeInformation() instead. You can extract the typename from the SDataTypeInformation variable. This function will be removed in future eCAL versions.

Returns

The type name.

public ECAL_API std::string GetDescription() const

Gets description of the connected topic.

Deprecated: Please use the method SDataTypeInformationGetDataTypeInformation() instead. You can extract the descriptor from the SDataTypeInformation variable. This function will be removed in future eCAL versions.

Returns

The description.

public ECAL_API SDataTypeInformation GetDataTypeInformation() const

Gets description of the connected topic.

Returns

The topic information.

public ECAL_API 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.

protected std::shared_ptr< CDataWriter > m_datawriter

protected long long m_id

protected bool m_created

protected bool m_initialized

protected void InitializeQOS()

protected void InitializeTLayer()

protected bool ApplyTopicToDescGate(const std::string & topic_name_,const SDataTypeInformation & topic_info_)