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.
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.// 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
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.
- 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.
- Parameters
attr_name_ – Attribute name.
- Returns
True if it succeeds, false if it fails.
Share topic type.
- Parameters
state_ – Set type share mode (true == share type).
- Returns
True if it succeeds, false if it fails.
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 trasnport mode.
By default, the builtin 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 trasnport layer (true == zero copy enabled).
- Returns
True if it succeeds, false if it fails.
-
bool
SetID
(long long id_)¶ Set the 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.
-
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.
-