libxr  1.0
Want to be the best embedded framework
Loading...
Searching...
No Matches
LibXR::Topic Class Reference

主题(Topic)管理类 / Topic management class More...

#include <message.hpp>

Collaboration diagram for LibXR::Topic:
[legend]

Data Structures

struct  ASyncBlock
 异步订阅块,继承自 SuberBlock Asynchronous subscription block, inheriting from SuberBlock More...
 
class  ASyncSubscriber
 异步订阅者类,用于订阅异步数据 Asynchronous subscriber class for subscribing to asynchronous data More...
 
struct  Block
 存储主题(Topic)数据的结构体。Structure storing topic data. More...
 
struct  CallbackBlock
 回调订阅块,继承自 SuberBlock Callback subscription block, inheriting from SuberBlock More...
 
class  Domain
 主题域(Domain)管理器,用于组织多个主题。Domain manager for organizing multiple topics. More...
 
struct  QueueBlock
 队列订阅块,继承自 SuberBlock Queue subscription block, inheriting from SuberBlock More...
 
class  QueuedSubscriber
 构造函数,使用名称和无锁队列进行初始化 Constructor using a name and a lock-free queue More...
 
class  Server
 服务器类,负责解析数据并将其分发到相应的主题 Server class responsible for parsing data and distributing it to corresponding topics More...
 
struct  SuberBlock
 订阅者信息存储结构。Structure storing subscriber information. More...
 
struct  SyncBlock
 同步订阅者存储结构。Structure storing synchronous subscriber data. More...
 
class  SyncSubscriber
 同步订阅者类,允许同步方式接收数据。Synchronous subscriber class allowing data reception in a synchronous manner. More...
 

Public Types

enum class  SuberType : uint8_t { SYNC , ASYNC , QUEUE , CALLBACK }
 订阅者类型。Subscriber type. More...
 
typedef RBTree< uint32_t >::Node< Block > * TopicHandle
 主题句柄,指向存储数据的红黑树节点。Handle pointing to a red-black tree node storing data.
 
typedef LibXR::Topic::ASyncBlock ASyncBlock
 
typedef LibXR::Topic::QueueBlock QueueBlock
 
using Callback = LibXR::Callback<LibXR::RawData &>
 
typedef LibXR::Topic::CallbackBlock CallbackBlock
 

Public Member Functions

void RegisterCallback (Callback &cb)
 注册回调函数 Registers a callback function
 
 Topic ()
 默认构造函数,创建一个空的 Topic 实例 Default constructor, creates an empty Topic instance
 
 Topic (const char *name, uint32_t max_length, Domain *domain=nullptr, bool cache=false, bool check_length=false)
 构造函数,使用指定名称、最大长度、域及其他选项初始化主题 Constructor to initialize a topic with the specified name, maximum length, domain, and options
 
 Topic (TopicHandle topic)
 通过句柄构造主题 Constructs a topic from a topic handle
 
void EnableCache ()
 启用主题的缓存功能 Enables caching for the topic
 
template<typename Data >
void Publish (Data &data)
 发布数据 Publishes data
 
void Publish (void *addr, uint32_t size)
 以原始地址和大小发布数据 Publishes data using raw address and size
 
template<SizeLimitMode Mode = SizeLimitMode::MORE>
ErrorCode DumpData (RawData data, bool pack=false)
 转储数据 Dump data
 
template<typename Data >
ErrorCode DumpData (PackedData< Data > &data)
 转储数据到 PackedData Dumps data into PackedData format
 
template<typename Data >
ErrorCode DumpData (Data &data)
 转储数据到普通数据结构 Dumps data into a normal data structure
 
 operator TopicHandle ()
 Topic 转换为 TopicHandle Converts Topic to TopicHandle
 
uint32_t GetKey () const
 获取主题的键值 Gets the key value of the topic
 

Static Public Member Functions

template<typename Data >
static Topic CreateTopic (const char *name, Domain *domain=nullptr, bool cache=false, bool check_length=true)
 创建一个新的主题 Creates a new topic
 
static TopicHandle Find (const char *name, Domain *domain=nullptr)
 在指定域中查找主题 Finds a topic in the specified domain
 
template<typename Data >
static TopicHandle FindOrCreate (const char *name, Domain *domain=nullptr, bool cache=false, bool check_length=true)
 在指定域中查找或创建主题 Finds or creates a topic in the specified domain
 
static void PackData (uint32_t topic_name_crc32, RawData buffer, RawData source)
 打包数据
 
static TopicHandle WaitTopic (const char *name, uint32_t timeout=UINT32_MAX, Domain *domain=nullptr)
 等待主题的创建并返回其句柄 Waits for a topic to be created and returns its handle
 

Private Attributes

TopicHandle block_ = nullptr
 主题句柄,指向当前主题的内存块 Topic handle pointing to the memory block of the current topic
 

Static Private Attributes

static RBTree< uint32_t > * domain_ = nullptr
 主题域的红黑树结构,存储不同的主题 Red-Black Tree structure for storing different topics in the domain
 
static Domaindef_domain_ = nullptr
 默认的主题域,所有未指定域的主题都会归入此域 Default domain where all topics without a specified domain are assigned
 

Detailed Description

主题(Topic)管理类 / Topic management class

该类提供了基于发布-订阅模式的主题管理,支持同步、异步、队列和回调订阅者,以及数据的缓存和校验机制。 This class provides topic management based on the publish-subscribe model, supporting synchronous, asynchronous, queue-based, and callback subscribers, as well as data caching and validation mechanisms.

Definition at line 27 of file message.hpp.

Member Typedef Documentation

◆ Callback

Definition at line 441 of file message.hpp.

◆ TopicHandle

主题句柄,指向存储数据的红黑树节点。Handle pointing to a red-black tree node storing data.

Definition at line 134 of file message.hpp.

Member Enumeration Documentation

◆ SuberType

enum class LibXR::Topic::SuberType : uint8_t
strong

订阅者类型。Subscriber type.

Enumerator
SYNC 

同步订阅者。Synchronous subscriber.

ASYNC 

异步订阅者。Asynchronous subscriber.

QUEUE 

队列订阅者。Queued subscriber.

CALLBACK 

回调订阅者。Callback subscriber.

Definition at line 161 of file message.hpp.

162 {
163 SYNC,
164 ASYNC,
165 QUEUE,
166 CALLBACK,
167 };
@ SYNC
同步订阅者。Synchronous subscriber.
@ ASYNC
异步订阅者。Asynchronous subscriber.
@ QUEUE
队列订阅者。Queued subscriber.
@ CALLBACK
回调订阅者。Callback subscriber.

Constructor & Destructor Documentation

◆ Topic() [1/3]

Topic::Topic ( )

默认构造函数,创建一个空的 Topic 实例 Default constructor, creates an empty Topic instance

Definition at line 61 of file message.cpp.

61{}

◆ Topic() [2/3]

Topic::Topic ( const char * name,
uint32_t max_length,
Domain * domain = nullptr,
bool cache = false,
bool check_length = false )

构造函数,使用指定名称、最大长度、域及其他选项初始化主题 Constructor to initialize a topic with the specified name, maximum length, domain, and options

Parameters
name主题名称 Topic name
max_length数据的最大长度 Maximum length of data
domain主题所属的域(默认为 nullptr)Domain to which the topic belongs (default: nullptr)
cache是否启用缓存(默认为 false)Whether to enable caching (default: false)
check_length是否检查数据长度(默认为 false)Whether to check data length (default: false)

Definition at line 63 of file message.cpp.

65{
66 if (!def_domain_)
67 {
68 if (!def_domain_)
69 {
70 def_domain_ = new Domain("libxr_def_domain");
71 }
72 }
73
74 if (domain == nullptr)
75 {
76 domain = def_domain_;
77 }
78
79 auto crc32 = CRC32::Calculate(name, strlen(name));
80
81 auto topic = domain->node_->data_.Search<Block>(crc32);
82
83 if (topic)
84 {
85 ASSERT(topic->data_.max_length == max_length);
86 ASSERT(topic->data_.check_length == check_length);
87
88 block_ = topic;
89 }
90 else
91 {
92 block_ = new RBTree<uint32_t>::Node<Block>;
93 block_->data_.max_length = max_length;
94 block_->data_.crc32 = crc32;
95 block_->data_.data.addr_ = nullptr;
96 block_->data_.cache = false;
97 block_->data_.check_length = check_length;
98
99 domain->node_->data_.Insert(*block_, crc32);
100 }
101
102 if (cache && !block_->data_.cache)
103 {
104 EnableCache();
105 }
106}
static uint32_t Calculate(const void *raw, size_t len)
计算数据的 CRC32 校验码 / Computes the CRC32 checksum for the given data
Definition crc.hpp:251
红黑树的泛型数据节点,继承自 BaseNode (Generic data node for Red-Black Tree, inheriting from BaseNode).
Definition rbt.hpp:64
Data data_
存储的数据 (Stored data).
Definition rbt.hpp:99
static Domain * def_domain_
默认的主题域,所有未指定域的主题都会归入此域 Default domain where all topics without a specified domain are assigned
Definition message.hpp:749
void EnableCache()
启用主题的缓存功能 Enables caching for the topic
Definition message.cpp:122
TopicHandle block_
主题句柄,指向当前主题的内存块 Topic handle pointing to the memory block of the current topic
Definition message.hpp:737

◆ Topic() [3/3]

Topic::Topic ( TopicHandle topic)

通过句柄构造主题 Constructs a topic from a topic handle

Parameters
topic主题句柄 Topic handle

Definition at line 108 of file message.cpp.

108: block_(topic) {}

Member Function Documentation

◆ CreateTopic()

template<typename Data >
static Topic LibXR::Topic::CreateTopic ( const char * name,
Domain * domain = nullptr,
bool cache = false,
bool check_length = true )
inlinestatic

创建一个新的主题 Creates a new topic

Template Parameters
Data主题数据类型 Topic data type
Parameters
name主题名称 Topic name
domain主题所属的域(默认为 nullptr)Domain to which the topic belongs (default: nullptr)
cache是否启用缓存(默认为 false)Whether to enable caching (default: false)
check_length是否检查数据长度(默认为 true)Whether to check data length (default: true)
Returns
创建的 Topic 实例 The created Topic instance

Definition at line 494 of file message.hpp.

496 {
497 return Topic(name, sizeof(Data), domain, cache, check_length);
498 }
Topic()
默认构造函数,创建一个空的 Topic 实例 Default constructor, creates an empty Topic instance
Definition message.cpp:61

◆ DumpData() [1/3]

template<typename Data >
ErrorCode LibXR::Topic::DumpData ( Data & data)
inline

转储数据到普通数据结构 Dumps data into a normal data structure

Template Parameters
Data数据类型 Data type
Parameters
data存储数据的变量 Variable to store the data

Definition at line 638 of file message.hpp.

639 {
640 if (block_->data_.data.addr_ == nullptr)
641 {
642 return ErrorCode::EMPTY;
643 }
644
645 ASSERT(sizeof(Data) == block_->data_.data.size_);
646
647 return DumpData<SizeLimitMode::NONE>(data, false);
648 }
ErrorCode DumpData(RawData data, bool pack=false)
转储数据 Dump data
Definition message.hpp:577

◆ DumpData() [2/3]

template<typename Data >
ErrorCode LibXR::Topic::DumpData ( PackedData< Data > & data)
inline

转储数据到 PackedData Dumps data into PackedData format

Template Parameters
Data数据类型 Data type
Parameters
data存储数据的 PackedData 结构 PackedData structure to store data

Definition at line 619 of file message.hpp.

620 {
621 if (block_->data_.data.addr_ == nullptr)
622 {
623 return ErrorCode::EMPTY;
624 }
625
626 ASSERT(sizeof(Data) == block_->data_.data.size_);
627
628 return DumpData<SizeLimitMode::NONE>(RawData(data), true);
629 }

◆ DumpData() [3/3]

template<SizeLimitMode Mode = SizeLimitMode::MORE>
ErrorCode LibXR::Topic::DumpData ( RawData data,
bool pack = false )
inline

转储数据 Dump data

Template Parameters
Mode数据大小检查模式 Size limit check mode
Parameters
data需要转储的数据 Data to be dumped
pack是否打包数据 Pack data
Returns
ErrorCode

Definition at line 577 of file message.hpp.

578 {
579 if (block_->data_.data.addr_ == nullptr)
580 {
581 return ErrorCode::EMPTY;
582 }
583
584 if (!pack)
585 {
586 Assert::SizeLimitCheck<Mode>(block_->data_.data.size_, data.size_);
587 block_->data_.mutex.Lock();
588 memcpy(data.addr_, block_->data_.data.addr_, block_->data_.data.size_);
589 block_->data_.mutex.Unlock();
590 }
591 else
592 {
593 Assert::SizeLimitCheck<Mode>(PACK_BASE_SIZE + block_->data_.data.size_, data.size_);
594
595 block_->data_.mutex.Lock();
596 PackData(block_->data_.crc32, data, block_->data_.data);
597 block_->data_.mutex.Unlock();
598 }
599
600 return ErrorCode::OK;
601 }
static void SizeLimitCheck(size_t limit, size_t size)
在非调试模式下的占位大小检查函数(无实际作用)。 Dummy size limit check for non-debug builds.
static void PackData(uint32_t topic_name_crc32, RawData buffer, RawData source)
打包数据
Definition message.cpp:200

◆ EnableCache()

void Topic::EnableCache ( )

启用主题的缓存功能 Enables caching for the topic

Definition at line 122 of file message.cpp.

123{
124 block_->data_.mutex.Lock();
125 if (!block_->data_.cache)
126 {
127 block_->data_.cache = true;
128 block_->data_.data.addr_ = new uint8_t[block_->data_.max_length];
129 }
130 block_->data_.mutex.Unlock();
131}

◆ Find()

Topic::TopicHandle Topic::Find ( const char * name,
Domain * domain = nullptr )
static

在指定域中查找主题 Finds a topic in the specified domain

Parameters
name主题名称 Topic name
domain主题所属的域(默认为 nullptr)Domain to search in (default: nullptr)
Returns
主题句柄,如果找到则返回对应的句柄,否则返回 nullptr Topic handle if found, otherwise returns nullptr

Definition at line 110 of file message.cpp.

111{
112 if (domain == nullptr)
113 {
114 domain = def_domain_;
115 }
116
117 auto crc32 = CRC32::Calculate(name, strlen(name));
118
119 return domain->node_->data_.Search<Block>(crc32);
120}

◆ FindOrCreate()

template<typename Data >
static TopicHandle LibXR::Topic::FindOrCreate ( const char * name,
Domain * domain = nullptr,
bool cache = false,
bool check_length = true )
inlinestatic

在指定域中查找或创建主题 Finds or creates a topic in the specified domain

Template Parameters
Data数据类型 Data type
Parameters
name话题名称 Topic name
domain可选的域指针 Optional domain pointer (default: nullptr)
cache可选的缓存标志位 Optional cache flag (default: false)
check_length可选的数据长度检查标志位 Optional data length check flag (default: true)
Returns
TopicHandle 主题句柄 Topic handle

Definition at line 530 of file message.hpp.

532 {
533 auto topic = Find(name, domain);
534 if (topic == nullptr)
535 {
536 topic = CreateTopic<Data>(name, domain, cache, check_length).block_;
537 }
538 return topic;
539 }
static Topic CreateTopic(const char *name, Domain *domain=nullptr, bool cache=false, bool check_length=true)
创建一个新的主题 Creates a new topic
Definition message.hpp:494
static TopicHandle Find(const char *name, Domain *domain=nullptr)
在指定域中查找主题 Finds a topic in the specified domain
Definition message.cpp:110

◆ GetKey()

uint32_t Topic::GetKey ( ) const

获取主题的键值 Gets the key value of the topic

Returns
uint32_t

Definition at line 236 of file message.cpp.

237{
238 if (block_)
239 {
240 return block_->key;
241 }
242 else
243 {
244 return 0;
245 }
246}
Key key
节点键值 (Key associated with the node).
Definition rbt.hpp:41

◆ operator TopicHandle()

LibXR::Topic::operator TopicHandle ( )
inline

Topic 转换为 TopicHandle Converts Topic to TopicHandle

Returns
TopicHandle

Definition at line 669 of file message.hpp.

669{ return block_; }

◆ PackData()

void Topic::PackData ( uint32_t topic_name_crc32,
RawData buffer,
RawData source )
static

打包数据

Parameters
topic_name_crc32话题名称的 CRC32 校验码
buffer等待写入的包 Packed data to be written
source需要打包的数据 Data to be packed

Definition at line 200 of file message.cpp.

201{
202 PackedData<uint8_t> *pack = reinterpret_cast<PackedData<uint8_t> *>(buffer.addr_);
203
204 memcpy(&pack->raw.data_, source.addr_, source.size_);
205
206 pack->raw.header_.prefix = 0xa5;
207 pack->raw.header_.topic_name_crc32 = topic_name_crc32;
208 pack->raw.header_.SetDataLen(source.size_);
209 pack->raw.header_.pack_header_crc8 =
210 CRC8::Calculate(&pack->raw, sizeof(PackedDataHeader) - sizeof(uint8_t));
211 uint8_t *crc8_pack =
212 reinterpret_cast<uint8_t *>(reinterpret_cast<uint8_t *>(pack) + PACK_BASE_SIZE +
213 source.size_ - sizeof(uint8_t));
214 *crc8_pack = CRC8::Calculate(pack, PACK_BASE_SIZE - sizeof(uint8_t) + source.size_);
215}
static uint8_t Calculate(const void *raw, size_t len)
计算数据的 CRC8 校验码 / Computes the CRC8 checksum for the given data
Definition crc.hpp:66
size_t size_
数据大小(字节)。 The size of the data (in bytes).
void * addr_
数据存储地址。 The storage address of the data.

◆ Publish() [1/2]

template<typename Data >
void LibXR::Topic::Publish ( Data & data)
inline

发布数据 Publishes data

Template Parameters
Data数据类型 Data type
Parameters
data需要发布的数据 Data to be published

Definition at line 554 of file message.hpp.

555 {
556 Publish(&data, sizeof(Data));
557 }
void Publish(Data &data)
发布数据 Publishes data
Definition message.hpp:554

◆ Publish() [2/2]

void Topic::Publish ( void * addr,
uint32_t size )

以原始地址和大小发布数据 Publishes data using raw address and size

Parameters
addr数据的地址 Address of the data
size数据大小 Size of the data

Definition at line 133 of file message.cpp.

134{
135 block_->data_.mutex.Lock();
136 if (block_->data_.check_length)
137 {
138 ASSERT(size == block_->data_.max_length);
139 }
140 else
141 {
142 ASSERT(size <= block_->data_.max_length);
143 }
144
145 if (block_->data_.cache)
146 {
147 memcpy(block_->data_.data.addr_, addr, size);
148 block_->data_.data.size_ = size;
149 }
150 else
151 {
152 block_->data_.data.addr_ = addr;
153 block_->data_.data.size_ = size;
154 }
155
156 RawData data = block_->data_.data;
157
158 auto foreach_fun = [&](SuberBlock &block)
159 {
160 switch (block.type)
161 {
162 case SuberType::SYNC:
163 {
164 auto sync = reinterpret_cast<SyncBlock *>(&block);
165 memcpy(sync->buff.addr_, data.addr_, data.size_);
166 sync->sem.Post();
167 break;
168 }
169 case SuberType::ASYNC:
170 {
171 auto async = reinterpret_cast<ASyncBlock *>(&block);
172 if (async->waiting)
173 {
174 memcpy(async->buff.addr_, data.addr_, data.size_);
175 async->data_ready = true;
176 }
177 break;
178 }
179 case SuberType::QUEUE:
180 {
181 auto queue_block = reinterpret_cast<QueueBlock *>(&block);
182 queue_block->fun(data, queue_block->queue, false);
183 break;
184 }
186 {
187 auto cb_block = reinterpret_cast<CallbackBlock *>(&block);
188 cb_block->cb.Run(false, data);
189 break;
190 }
191 }
192 return ErrorCode::OK;
193 };
194
195 block_->data_.subers.Foreach<SuberBlock>(foreach_fun);
196
197 block_->data_.mutex.Unlock();
198}
提供一个回调函数的封装,实现参数绑定和回调执行。 Provides a wrapper for callback functions, enabling argument binding and inv...
Definition libxr_cb.hpp:22
原始数据封装类。 A class for encapsulating raw data.
void(* fun)(RawData &, void *, bool)
处理数据的回调函数 Callback function to handle data
Definition message.hpp:340

◆ RegisterCallback()

void LibXR::Topic::RegisterCallback ( Callback & cb)

注册回调函数 Registers a callback function

Parameters
cb需要注册的回调函数 The callback function to register

Definition at line 51 of file message.cpp.

52{
53 CallbackBlock block;
54 block.cb = cb;
55 block.type = SuberType::CALLBACK;
56 auto node = new (std::align_val_t(LIBXR_CACHE_LINE_SIZE))
58 block_->data_.subers.Add(*node);
59}
数据节点模板,继承自 BaseNode,用于存储具体数据类型。 Template data node that inherits from BaseNode to store specific data...

◆ WaitTopic()

Topic::TopicHandle Topic::WaitTopic ( const char * name,
uint32_t timeout = UINT32_MAX,
Domain * domain = nullptr )
static

等待主题的创建并返回其句柄 Waits for a topic to be created and returns its handle

Parameters
name主题名称 The name of the topic
timeout等待的超时时间(默认 UINT32_MAX)Timeout duration to wait (default: UINT32_MAX)
domain主题所属的域(默认为 nullptr)The domain in which to search for the topic (default: nullptr)
Returns
TopicHandle 如果找到主题,则返回其句柄,否则返回 nullptr TopicHandle if the topic is found, otherwise returns nullptr

Definition at line 217 of file message.cpp.

218{
219 TopicHandle topic = nullptr;
220 do
221 {
222 topic = Find(name, domain);
223 if (topic == nullptr)
224 {
225 if (timeout <= Thread::GetTime())
226 {
227 return nullptr;
228 }
229 Thread::Sleep(1);
230 }
231 } while (topic == nullptr);
232
233 return topic;
234}
static uint32_t GetTime()
获取当前系统时间(毫秒) Gets the current system time in milliseconds
Definition thread.cpp:41
static void Sleep(uint32_t milliseconds)
让线程进入休眠状态 Puts the thread to sleep
Definition thread.cpp:16
RBTree< uint32_t >::Node< Block > * TopicHandle
主题句柄,指向存储数据的红黑树节点。Handle pointing to a red-black tree node storing data.
Definition message.hpp:134

Field Documentation

◆ block_

TopicHandle LibXR::Topic::block_ = nullptr
private

主题句柄,指向当前主题的内存块 Topic handle pointing to the memory block of the current topic

Definition at line 737 of file message.hpp.

◆ def_domain_

Domain* LibXR::Topic::def_domain_ = nullptr
inlinestaticprivate

默认的主题域,所有未指定域的主题都会归入此域 Default domain where all topics without a specified domain are assigned

Definition at line 749 of file message.hpp.

◆ domain_

RBTree<uint32_t>* LibXR::Topic::domain_ = nullptr
inlinestaticprivate

主题域的红黑树结构,存储不同的主题 Red-Black Tree structure for storing different topics in the domain

Definition at line 743 of file message.hpp.


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