发布订阅主题 / Publish-subscribe topic More...

#include <topic.hpp>

Classes
struct	ASyncBlock
	异步订阅者自己挂的数据块 / Data block owned by one asynchronous subscriber More...

class	ASyncSubscriber
	先 `StartWaiting()`，再自己来取数据的订阅者 / Subscriber that first calls `StartWaiting()` and later pulls the data itself More...

struct	Block
	topic 运行时状态块 / Runtime state block of one topic More...

class	Callback
	每次发布时直接执行函数的订阅句柄 / Subscription handle that runs a function on each publish More...

struct	CallbackBlock
	挂在 topic 订阅链表里的回调记录 / Callback record stored in the topic subscriber list More...

class	Domain
	topic 所属的命名域 / Naming domain that groups topics More...

struct	Message
	带时间戳和 payload 副本的消息对象 / Message object carrying a timestamp and a payload copy More...

struct	MessageView
	带时间戳和 payload 指针的只读消息视图 / Read-only message view carrying a timestamp and a payload pointer More...

struct	QueueBlock
	队列订阅者自己挂的数据块 / Data block owned by one queued subscriber More...

class	QueuedSubscriber
	每次发布都往队列里塞一份数据的订阅者 / Subscriber that pushes one entry into a queue on each publish More...

struct	RawMessageView
	带时间戳和只读原始 payload 视图的消息 / Message carrying a timestamp and a read-only raw payload view More...

class	Server
	将字节流解析成 packet 并发布到已注册 topic 的状态机 / State machine that parses byte streams into packets and publishes them into registered topics More...

struct	SuberBlock
	所有订阅块共用的公共头 / Common header shared by all subscriber blocks More...

struct	SyncBlock
	同步订阅者自己挂的数据块 / Data block owned by one synchronous subscriber More...

class	SyncSubscriber
	调用 `Wait()` 收消息的订阅者 / Subscriber that receives messages by calling `Wait()` More...

Public Types
enum class	ASyncSubscriberState : uint32_t { IDLE = 0 , WAITING = 1 , DATA_READY = UINT32_MAX }
	异步订阅者本地缓冲区的状态 / State of the async subscriber's local buffer More...

enum class	SuberType : uint8_t { SYNC , ASYNC , QUEUE , CALLBACK }
	topic 支持的订阅者种类 / Subscriber kinds supported by a topic More...

typedef RBTree< uint32_t >::Node< Block > *	TopicHandle
	指向一个 topic 运行时状态块的句柄 / Handle pointing to one topic runtime state block

Public Member Functions
void	RegisterCallback (Callback &cb)
	注册一个回调订阅者 / Register one callback subscriber

	Topic ()
	构造一个空 topic 视图 / Construct one empty topic view

	Topic (const char name, TypeID::ID payload_type_id, size_t payload_size, size_t payload_alignment, Domain domain=nullptr, bool multi_publisher=false)
	用显式类型契约构造或查找一个 topic / Construct or look up one topic with an explicit runtime type contract

	Topic (TopicHandle topic)
	从已有句柄构造一个 topic 视图 / Construct one topic view from an existing handle

size_t	PayloadSize () const
	获取该 topic 固定 payload 字节数 / Get the fixed payload size of this topic

size_t	PayloadAlignment () const
	获取该 topic payload 的对齐要求 / Get the payload alignment requirement of this topic

template<typename Data >
void	Publish (Data &data)
	在普通上下文里发布一条消息，并自动取当前时间戳 / Publish one message in normal context and stamp it with the current time

template<typename Data >
void	Publish (Data &data, MicrosecondTimestamp timestamp)
	在普通上下文里按指定时间戳发布一条消息 / Publish one message in normal context with an explicit timestamp

template<typename Data >
void	PublishFromCallback (Data &data, bool in_isr)
	在回调或 ISR 路径里发布一条消息，并自动取当前时间戳 / Publish one message from callback or ISR context and stamp it with the current time

template<typename Data >
void	PublishFromCallback (Data &data, MicrosecondTimestamp timestamp, bool in_isr)
	在回调或 ISR 路径里按指定时间戳发布一条消息 / Publish one message from callback or ISR context with an explicit timestamp

void	PublishBytesFromServer (void *payload_addr, size_t payload_size, MicrosecondTimestamp timestamp)
	供 packet/server 路径按字节发布一条消息 / Publish one message from the packet/server path using bytes already arranged as the exact payload object

void	PublishBytesFromServerCallback (void *payload_addr, size_t payload_size, MicrosecondTimestamp timestamp, bool in_isr)
	供回调/ISR 上下文里的 packet/server 路径按字节发布一条消息 / Publish one packet/server message from callback/ISR context using bytes already arranged as the exact payload object

template<typename Data >
ErrorCode	PackData (const Data &data, PackedData< Data > &packet)
	将一个精确类型消息打包成 packet / Pack one exact-typed message into one packet using the topic's runtime contract and current timestamp

template<typename Data >
ErrorCode	PackData (const Data &data, PackedData< Data > &packet, MicrosecondTimestamp timestamp)
	将一个精确类型消息按指定时间戳打包成 packet / Pack one exact-typed message into one packet with the given timestamp

ErrorCode	PackRaw (ConstRawData data, RawData packet)
	将一段 raw payload 按当前 topic 元数据打包成 packet / Pack a raw payload byte view into one packet using the current topic metadata and current timestamp

ErrorCode	PackRaw (ConstRawData data, RawData packet, MicrosecondTimestamp timestamp)
	将一段 raw payload 按当前 topic 元数据和指定时间戳打包成 packet / Pack a raw payload byte view into one packet using the current topic metadata and timestamp

	operator TopicHandle ()
	把 topic 视图转换为底层句柄 / Convert this topic view to the underlying handle

uint32_t	GetKey () const
	读取 topic 键值 / Read the key value of this topic

Static Public Member Functions
static void	Lock (TopicHandle topic)
	在普通上下文里锁住一个 topic 发布路径 / Lock one topic publish path in normal context

static void	Unlock (TopicHandle topic)
	在普通上下文里释放一个 topic 发布路径 / Unlock one topic publish path in normal context

static void	LockFromCallback (TopicHandle topic)
	在回调或 ISR 路径里锁住一个 topic 发布路径 / Lock one topic publish path from callback or ISR context

static void	UnlockFromCallback (TopicHandle topic)
	在回调或 ISR 路径里释放一个 topic 发布路径 / Unlock one topic publish path from callback or ISR context

static MicrosecondTimestamp	NowTimestamp ()
	读取当前时间戳 / Read the current timestamp

template<typename Data >
static Topic	CreateTopic (const char name, Domain domain=nullptr, bool multi_publisher=false)
	用精确类型创建或查找一个 topic / Create or look up one topic using one exact payload type

static TopicHandle	Find (const char name, Domain domain=nullptr)
	按名称查找一个已存在 topic / Find one existing topic by name

template<typename Data >
static TopicHandle	FindOrCreate (const char name, Domain domain=nullptr, bool multi_publisher=false)
	按精确类型查找或创建一个 topic / Find or create one topic with an exact payload type

static TopicHandle	WaitTopic (const char name, uint32_t timeout=UINT32_MAX, Domain domain=nullptr)
	等待指定名称的 topic 出现 / Wait until a topic with the given name exists

Detailed Description

发布订阅主题 / Publish-subscribe topic

一个 Topic 表示一种精确类型的消息通道：它在每次发布时同步通知挂在上面的同步、异步、队列或回调订阅者，但自身不缓存最近一次消息。 One Topic represents one exact-typed message channel: it synchronously notifies the attached synchronous, asynchronous, queued, or callback subscribers on each publish, but does not cache the latest message itself.

Definition at line 55 of file topic.hpp.

Member Typedef Documentation

◆ TopicHandle

RBTree<uint32_t>::Node<Block>* LibXR::Topic::TopicHandle

指向一个 topic 运行时状态块的句柄 / Handle pointing to one topic runtime state block

Definition at line 125 of file topic.hpp.

Member Enumeration Documentation

◆ ASyncSubscriberState

enum class LibXR::Topic::ASyncSubscriberState : uint32_t

strong

异步订阅者本地缓冲区的状态 / State of the async subscriber's local buffer

异步订阅者本地缓冲区状态 / State of one asynchronous subscriber local buffer

Enumerator
IDLE	当前没有等待，也没有待消费的新数据 / No wait is pending and no unread data is buffered.
WAITING	等待下一次发布填充本地缓冲区 / Waiting for the next publish to fill the local buffer.
DATA_READY	本地缓冲区已有一份待消费的新数据 / One unread fresh sample is buffered locally.

Definition at line 11 of file async.hpp.

{
  IDLE = 0,     
  WAITING = 1,  
  DATA_READY = UINT32_MAX  
};

◆ SuberType

enum class LibXR::Topic::SuberType : uint8_t

strong

topic 支持的订阅者种类 / Subscriber kinds supported by a topic

Enumerator
SYNC	同步等待型订阅者 / Synchronous wait-based subscriber.
ASYNC	异步本地缓冲型订阅者 / Asynchronous local-buffer subscriber.
QUEUE	队列转发型订阅者 / Queue-forwarding subscriber.
CALLBACK	回调执行型订阅者 / Callback-executing subscriber.

Definition at line 224 of file topic.hpp.

  {
    SYNC,      
    ASYNC,     
    QUEUE,     
    CALLBACK,  
  };

Constructor & Destructor Documentation

◆ Topic() [1/3]

Topic::Topic ( )

构造一个空 topic 视图 / Construct one empty topic view

Definition at line 114 of file topic.cpp.

114{}

◆ Topic() [2/3]

Topic::Topic	(	const char *	name,
		TypeID::ID	payload_type_id,
		size_t	payload_size,
		size_t	payload_alignment,
		Domain *	domain = nullptr,
		bool	multi_publisher = false )

用显式类型契约构造或查找一个 topic / Construct or look up one topic with an explicit runtime type contract

Parameters

name	topic 名称 / Topic name
payload_type_id	payload 类型标识 / Payload type identifier
payload_size	该 topic 固定 payload 字节数 / Fixed payload size of this topic
payload_alignment	该 topic payload 所需对齐，必须是非零 2 次幂 / Required payload alignment of this topic; must be a non-zero power of two
domain	可选主题域 / Optional topic domain
multi_publisher	是否允许多发布者串行化 / Whether to allow serialized multi-publisher use

Note: 同名 topic 已存在但类型契约不同，或它以单发布者创建而本次要求多发布者时，在所有构建类型中进入致命错误。 If a topic with this name exists with a different type contract, or was created for a single publisher while multi_publisher is requested, a fatal error is raised in every build type.

Definition at line 116 of file topic.cpp.

{
  ASSERT(name != nullptr);
  ASSERT(payload_type_id != nullptr);
  ASSERT(payload_size != 0);
  ASSERT(payload_alignment != 0);
  ASSERT((payload_alignment & (payload_alignment - 1)) == 0);
 
  if (domain == nullptr)
  {
    domain = EnsureDefaultDomain();
  }
 
  auto crc32 = CRC32::Calculate(name, strlen(name));
 
  auto topic = domain->node_->data_.Search<Block>(crc32);
 
  if (topic)
  {
    RequireTypeContract(topic, payload_type_id, payload_size, payload_alignment);
 
    if (multi_publisher)
    {
      RequireMultiPublisher(topic);
    }
 
    block_ = topic;
  }
  else
  {
    block_ = new RBTree<uint32_t>::Node<Block>;
    block_->data_.payload_type_id = payload_type_id;
    block_->data_.payload_size = payload_size;
    block_->data_.payload_alignment = payload_alignment;
    block_->data_.crc32 = crc32;
 
    if (multi_publisher)
    {
      block_->data_.mutex = new Mutex();
      block_->data_.busy.store(LockState::USE_MUTEX, std::memory_order_release);
    }
    else
    {
      block_->data_.mutex = nullptr;
      block_->data_.busy.store(LockState::UNLOCKED, std::memory_order_release);
    }
 
    domain->node_->data_.Insert(*block_, crc32);
  }
}

◆ Topic() [3/3]

Topic::Topic ( TopicHandle topic )

从已有句柄构造一个 topic 视图 / Construct one topic view from an existing handle

Parameters

topic 既有 topic 句柄 / Existing topic handle

Definition at line 168 of file topic.cpp.

168: block_(topic) {}

Member Function Documentation

◆ CreateTopic()

template<typename Data >

static Topic LibXR::Topic::CreateTopic	(	const char *	name,
		Domain *	domain = nullptr,
		bool	multi_publisher = false )

inlinestatic

用精确类型创建或查找一个 topic / Create or look up one topic using one exact payload type

Template Parameters

Data	payload 类型 / Payload type

Parameters

name	topic 名称 / Topic name
domain	可选主题域 / Optional topic domain
multi_publisher	是否允许多发布者串行化 / Whether to allow serialized multi-publisher use

Returns: 对应的 topic 视图 / Topic view of the requested topic

Definition at line 362 of file topic.hpp.

  {
    CheckTopicPayload<Data>();
    return Topic(name, TypeID::GetID<Data>(), sizeof(Data), alignof(Data), domain,
                 multi_publisher);
  }

◆ Find()

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

static

按名称查找一个已存在 topic / Find one existing topic by name

Parameters

name	topic 名称 / Topic name
domain	可选主题域 / Optional topic domain

Returns: 找到则返回句柄，否则返回空 / Returns the handle when found, otherwise null

Definition at line 188 of file topic.cpp.

{
  ASSERT(name != nullptr);
 
  if (domain == nullptr)
  {
    if (def_domain_ == nullptr)
    {
      return nullptr;
    }
    domain = def_domain_;
  }
 
  auto crc32 = CRC32::Calculate(name, strlen(name));
 
  return domain->node_->data_.Search<Block>(crc32);
}

◆ FindOrCreate()

template<typename Data >

static TopicHandle LibXR::Topic::FindOrCreate	(	const char *	name,
		Domain *	domain = nullptr,
		bool	multi_publisher = false )

inlinestatic

按精确类型查找或创建一个 topic / Find or create one topic with an exact payload type

Template Parameters

Data	payload 类型 / Payload type

Parameters

name	topic 名称 / Topic name
domain	可选主题域 / Optional topic domain
multi_publisher	是否允许多发布者串行化 / Whether to allow serialized multi-publisher use

Returns: topic 句柄 / Topic handle

Note: 已有 topic 的冲突检查与构造函数相同，在所有构建类型中生效。 Conflicts with an existing topic are checked as in the constructor, in every build type.

Definition at line 399 of file topic.hpp.

  {
    CheckTopicPayload<Data>();
    auto topic = Find(name, domain);
    if (topic != nullptr)
    {
      RequireTypeContract(topic, TypeID::GetID<Data>(), sizeof(Data), alignof(Data));
      if (multi_publisher)
      {
        RequireMultiPublisher(topic);
      }
    }
    else
    {
      topic = CreateTopic<Data>(name, domain, multi_publisher).block_;
    }
    return topic;
  }

◆ GetKey()

uint32_t Topic::GetKey ( ) const

读取 topic 键值 / Read the key value of this topic

Returns: topic 键值 / Topic key value

Definition at line 227 of file topic.cpp.

{
  if (block_)
  {
    return block_->key;
  }
  else
  {
    return 0;
  }
}

◆ Lock()

void Topic::Lock ( Topic::TopicHandle topic )

static

在普通上下文里锁住一个 topic 发布路径 / Lock one topic publish path in normal context

Parameters

topic 目标 topic 句柄 / Target topic handle

Definition at line 32 of file topic.cpp.

{
  if (topic->data_.mutex)
  {
    topic->data_.mutex->Lock();
  }
  else
  {
    LockState expected = LockState::UNLOCKED;
    if (!topic->data_.busy.compare_exchange_strong(expected, LockState::LOCKED))
    {
      // 非 mutex topic 禁止并发发布
      ASSERT(false);
      return;
    }
  }
}

◆ LockFromCallback()

void Topic::LockFromCallback ( Topic::TopicHandle topic )

static

在回调或 ISR 路径里锁住一个 topic 发布路径 / Lock one topic publish path from callback or ISR context

Parameters

topic 目标 topic 句柄 / Target topic handle

Definition at line 62 of file topic.cpp.

{
  if (topic->data_.mutex)
  {
    ASSERT(false);
  }
  else
  {
    LockState expected = LockState::UNLOCKED;
    if (!topic->data_.busy.compare_exchange_strong(expected, LockState::LOCKED))
    {
      // 回调发布路径要求外围先串行化
      ASSERT(false);
      return;
    }
  }
}

◆ NowTimestamp()

MicrosecondTimestamp Topic::NowTimestamp ( )

static

读取当前时间戳 / Read the current timestamp

Returns: 当前时间戳 / Current timestamp

Definition at line 80 of file publish.cpp.

80{ return Timebase::GetMicroseconds(); }

LibXR::Timebase::GetMicroseconds

static MicrosecondTimestamp GetMicroseconds()

获取当前时间的微秒级时间戳。 Gets the current timestamp in microseconds.

Definition ch32_timebase.cpp:60

◆ operator TopicHandle()

LibXR::Topic::operator TopicHandle ( )

inline

把 topic 视图转换为底层句柄 / Convert this topic view to the underlying handle

Returns: topic 句柄 / Topic handle

Definition at line 609 of file topic.hpp.

609{ return block_; }

◆ PackData() [1/2]

template<typename Data >

ErrorCode LibXR::Topic::PackData	(	const Data &	data,
		PackedData< Data > &	packet )

inline

将一个精确类型消息打包成 packet / Pack one exact-typed message into one packet using the topic's runtime contract and current timestamp

Template Parameters

Data	负载类型 / Payload type

Parameters

data	待打包 payload / Payload to pack
packet	输出 packet 对象 / Output packed message object

Returns: 操作结果错误码 / Error code

Definition at line 533 of file topic.hpp.

  {
    return PackData(data, packet, NowTimestamp());
  }

◆ PackData() [2/2]

template<typename Data >

ErrorCode LibXR::Topic::PackData	(	const Data &	data,
		PackedData< Data > &	packet,
		MicrosecondTimestamp	timestamp )

将一个精确类型消息按指定时间戳打包成 packet / Pack one exact-typed message into one packet with the given timestamp

按当前 topic 的名字和类型契约把一条消息打包成 packet / Pack one message into one packet using the current topic name and type contract

Template Parameters

Data	负载类型 / Payload type

Parameters

data	待打包 payload / Payload to pack
packet	输出 packet 对象 / Output packed message object
timestamp	指定时间戳 / Explicit timestamp

Returns: 操作结果错误码 / Error code

Template Parameters

Data	payload 类型 / Payload type

Parameters

data	待打包 payload / Payload to pack
packet	输出 packet / Output packed message
timestamp	要写入包头的时间戳 / Timestamp to store into the packet header

Returns: 操作结果错误码 / Error code

Definition at line 112 of file packet.hpp.

{
  CheckTopicPayload<Data>();
  ASSERT(block_ != nullptr);
  ASSERT(block_->data_.payload_type_id == TypeID::GetID<Data>());
  ASSERT(block_->data_.payload_size == sizeof(Data));
 
  PackBytes(block_->data_.crc32, RawData(packet), timestamp, ConstRawData(data));
  return ErrorCode::OK;
}

◆ PackRaw() [1/2]

ErrorCode LibXR::Topic::PackRaw	(	ConstRawData	data,
		RawData	packet )

inline

将一段 raw payload 按当前 topic 元数据打包成 packet / Pack a raw payload byte view into one packet using the current topic metadata and current timestamp

Parameters

data	待打包 payload 字节 / Payload bytes to pack
packet	输出 packet 缓冲区 / Output packet buffer

Returns: 操作结果错误码 / Error code

Definition at line 559 of file topic.hpp.

  {
    return PackRaw(data, packet, NowTimestamp());
  }

◆ PackRaw() [2/2]

ErrorCode LibXR::Topic::PackRaw	(	ConstRawData	data,
		RawData	packet,
		MicrosecondTimestamp	timestamp )

inline

将一段 raw payload 按当前 topic 元数据和指定时间戳打包成 packet / Pack a raw payload byte view into one packet using the current topic metadata and timestamp

Parameters

data	待打包 payload 字节 / Payload bytes to pack
packet	输出 packet 缓冲区 / Output packet buffer
timestamp	指定时间戳 / Explicit timestamp

Returns: 操作结果错误码 / Error code

Definition at line 573 of file topic.hpp.

  {
    if (block_ == nullptr || data.addr_ == nullptr || packet.addr_ == nullptr)
    {
      return ErrorCode::PTR_NULL;
    }
 
    if (data.size_ != block_->data_.payload_size)
    {
      return ErrorCode::SIZE_ERR;
    }
 
    if (packet.size_ < PACK_BASE_SIZE + data.size_)
    {
      return ErrorCode::NO_BUFF;
    }
 
    PackBytes(block_->data_.crc32, packet, timestamp, data);
    return ErrorCode::OK;
  }

◆ PayloadAlignment()

size_t LibXR::Topic::PayloadAlignment ( ) const

inlinenodiscard

获取该 topic payload 的对齐要求 / Get the payload alignment requirement of this topic

Returns: payload 对齐要求 / Payload alignment requirement

Definition at line 434 of file topic.hpp.

  {
    ASSERT(block_ != nullptr);
    return block_->data_.payload_alignment;
  }

◆ PayloadSize()

size_t LibXR::Topic::PayloadSize ( ) const

inlinenodiscard

获取该 topic 固定 payload 字节数 / Get the fixed payload size of this topic

Returns: payload 字节数 / Payload size in bytes

Definition at line 423 of file topic.hpp.

  {
    ASSERT(block_ != nullptr);
    return block_->data_.payload_size;
  }

◆ Publish() [1/2]

template<typename Data >

void LibXR::Topic::Publish ( Data & data )

inline

在普通上下文里发布一条消息，并自动取当前时间戳 / Publish one message in normal context and stamp it with the current time

Template Parameters

Data	payload 类型 / Payload type

Parameters

data	待发布的 payload 对象 / Payload object to publish

Definition at line 447 of file topic.hpp.

  {
    PublishTyped(data, NowTimestamp(), false, false);
  }

◆ Publish() [2/2]

template<typename Data >

void LibXR::Topic::Publish	(	Data &	data,
		MicrosecondTimestamp	timestamp )

inline

在普通上下文里按指定时间戳发布一条消息 / Publish one message in normal context with an explicit timestamp

Template Parameters

Data	payload 类型 / Payload type

Parameters

data	待发布的 payload 对象 / Payload object to publish
timestamp	消息时间戳 / Message timestamp

Definition at line 460 of file topic.hpp.

  {
    PublishTyped(data, timestamp, false, false);
  }

◆ PublishBytesFromServer()

void LibXR::Topic::PublishBytesFromServer	(	void *	payload_addr,
		size_t	payload_size,
		MicrosecondTimestamp	timestamp )

inline

供 packet/server 路径按字节发布一条消息 / Publish one message from the packet/server path using bytes already arranged as the exact payload object

Parameters

payload_addr	已满足对齐的 payload 起始地址 / Start address of the already-aligned payload object
payload_size	payload 字节数，必须等于 topic 固定大小 / Payload size, must equal the fixed topic size
timestamp	这条消息的时间戳 / Timestamp of this message

Definition at line 501 of file topic.hpp.

  {
    PublishServerBytes(payload_addr, payload_size, timestamp, false, false);
  }

◆ PublishBytesFromServerCallback()

void LibXR::Topic::PublishBytesFromServerCallback	(	void *	payload_addr,
		size_t	payload_size,
		MicrosecondTimestamp	timestamp,
		bool	in_isr )

inline

供回调/ISR 上下文里的 packet/server 路径按字节发布一条消息 / Publish one packet/server message from callback/ISR context using bytes already arranged as the exact payload object

Parameters

payload_addr	已满足对齐的 payload 起始地址 / Start address of the already-aligned payload object
payload_size	payload 字节数，必须等于 topic 固定大小 / Payload size, must equal the fixed topic size
timestamp	这条消息的时间戳 / Timestamp of this message
in_isr	当前是否位于 ISR / Whether the current path is in ISR context

Definition at line 518 of file topic.hpp.

  {
    PublishServerBytes(payload_addr, payload_size, timestamp, true, in_isr);
  }

◆ PublishFromCallback() [1/2]

template<typename Data >

void LibXR::Topic::PublishFromCallback	(	Data &	data,
		bool	in_isr )

inline

在回调或 ISR 路径里发布一条消息，并自动取当前时间戳 / Publish one message from callback or ISR context and stamp it with the current time

Template Parameters

Data	payload 类型 / Payload type

Parameters

data	待发布的 payload 对象 / Payload object to publish
in_isr	当前是否位于 ISR / Whether the current path is in ISR context

Definition at line 473 of file topic.hpp.

  {
    PublishTyped(data, NowTimestamp(), true, in_isr);
  }

◆ PublishFromCallback() [2/2]

template<typename Data >

void LibXR::Topic::PublishFromCallback	(	Data &	data,
		MicrosecondTimestamp	timestamp,
		bool	in_isr )

inline

在回调或 ISR 路径里按指定时间戳发布一条消息 / Publish one message from callback or ISR context with an explicit timestamp

Template Parameters

Data	payload 类型 / Payload type

Parameters

data	待发布的 payload 对象 / Payload object to publish
timestamp	消息时间戳 / Message timestamp
in_isr	当前是否位于 ISR / Whether the current path is in ISR context

Definition at line 487 of file topic.hpp.

  {
    PublishTyped(data, timestamp, true, in_isr);
  }

◆ RegisterCallback()

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

inline

注册一个回调订阅者 / Register one callback subscriber

注册回调函数 / Register a callback function

Parameters

cb	要注册的回调句柄 / Callback handle to register
cb	需要注册的回调函数 / Callback function to register

Note: 包含初始化期动态内存分配，回调订阅应长期存在 / Contains initialization-time dynamic allocation; callback subscriptions are expected to be long-lived; 回调在发布锁内运行，不应重入发布同一个主题 / The callback runs while the publish lock is held and should not re-enter publishing on the same topic; 类型化回调的 payload 类型与 topic 不一致时，在所有构建类型中进入致命错误 / A typed callback whose payload type differs from the topic raises a fatal error in every build type

Definition at line 620 of file callback.hpp.

{
  if (!cb.IsRawPayloadView())
  {
    RequireCallbackType(block_, cb.PayloadTypeID());
  }
 
  auto node = new (std::align_val_t(LibXR::CONCURRENCY_ALIGNMENT))
      LockFreeList::Node<CallbackBlock>(cb, block_->data_.payload_size);
  block_->data_.subers.Add(*node);
}

◆ Unlock()

void Topic::Unlock ( Topic::TopicHandle topic )

static

在普通上下文里释放一个 topic 发布路径 / Unlock one topic publish path in normal context

Parameters

topic 目标 topic 句柄 / Target topic handle

Definition at line 50 of file topic.cpp.

{
  if (topic->data_.mutex)
  {
    topic->data_.mutex->Unlock();
  }
  else
  {
    topic->data_.busy.store(LockState::UNLOCKED, std::memory_order_release);
  }
}

◆ UnlockFromCallback()

void Topic::UnlockFromCallback ( Topic::TopicHandle topic )

static

在回调或 ISR 路径里释放一个 topic 发布路径 / Unlock one topic publish path from callback or ISR context

Parameters

topic 目标 topic 句柄 / Target topic handle

Definition at line 80 of file topic.cpp.

{
  if (topic->data_.mutex)
  {
    ASSERT(false);
  }
  else
  {
    topic->data_.busy.store(LockState::UNLOCKED, std::memory_order_release);
  }
}

◆ WaitTopic()

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

static

等待指定名称的 topic 出现 / Wait until a topic with the given name exists

Parameters

name	topic 名称 / Topic name
timeout	等待超时，默认永久等待 / Timeout in ticks, default wait forever
domain	可选主题域 / Optional topic domain

Returns: 找到则返回句柄，否则返回空 / Returns the handle when found, otherwise null

Definition at line 206 of file topic.cpp.

{
  const uint32_t start_time = Thread::GetTime();
  TopicHandle topic = nullptr;
  do
  {
    topic = Find(name, domain);
    if (topic == nullptr)
    {
      if (timeout != UINT32_MAX &&
          static_cast<uint32_t>(Thread::GetTime() - start_time) >= timeout)
      {
        return nullptr;
      }
      Thread::Sleep(1);
    }
  } while (topic == nullptr);
 
  return topic;
}

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

src/middleware/message/topic.hpp
src/middleware/message/packet/packet.cpp
src/middleware/message/packet/packet.hpp
src/middleware/message/publish.cpp
src/middleware/message/subscriber/callback.hpp
src/middleware/message/topic.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ TopicHandle

Member Enumeration Documentation

◆ ASyncSubscriberState

◆ SuberType

Constructor & Destructor Documentation

◆ Topic() [1/3]

◆ Topic() [2/3]

◆ Topic() [3/3]

Member Function Documentation

◆ CreateTopic()

◆ Find()

◆ FindOrCreate()

◆ GetKey()

◆ Lock()

◆ LockFromCallback()

◆ NowTimestamp()

◆ operator TopicHandle()

◆ PackData() [1/2]

◆ PackData() [2/2]

◆ PackRaw() [1/2]

◆ PackRaw() [2/2]

◆ PayloadAlignment()

◆ PayloadSize()

◆ Publish() [1/2]

◆ Publish() [2/2]

◆ PublishBytesFromServer()

◆ PublishBytesFromServerCallback()

◆ PublishFromCallback() [1/2]

◆ PublishFromCallback() [2/2]

◆ RegisterCallback()

◆ Unlock()

◆ UnlockFromCallback()

◆ WaitTopic()