Lib.rs

ringmaster 是 NSCLDAQ 中维护对 NSCLDAQ 环形缓冲区知识和访问的程序。ringmaster 的主要目的是确保当客户端（生产者或消费者）退出（正常或异常）时，标记环形缓冲区中指示它是客户端（生产者/消费者 ClientInformation 结构）的位再次标记为未使用。

ringmaster 扮演的第二个角色，虽然可能不那么明显，但同样重要，就是将本地环形缓冲区中的数据提升到远程系统中的代理环形缓冲区。

这个包包含了对 Tcl NSCLDAQ 环形缓冲区的 Rust 版本的移植。写作它的动机是，随着 NSCLDAQ 在 singularity 容器中运行得越来越多，但需要在系统启动时启动 ringmaster，拥有一个没有依赖容器的自包含 ringmaster 更简单。这在 Debian-11 中尤其如此，因为 singularity 包似乎无法为 init 脚本激活包。

运行 ringmaster

Rust 环形 master 很通用，它可以被告知端口管理器监听连接的位置，以便它可以连接到它并宣传其服务。它还可以被告知环形缓冲区的实际位置，以便在 C++ 世界中使用 mmap 而不是 Posix 共享内存，因为 Posix 地区中不可枚举。因此，ringmaster 采用以下选项

• --portman-port - 此选项的值是端口管理器监听连接的端口号。默认值为 30000，这是 NSCLDAQ 通常设置 ringmaster 的端口号。
• --directory - 在其中创建环形缓冲区共享内存支持文件的目录。默认值为 /dev/shm，这是 Linux 保存其 POSIX 共享内存区域的位置。
• --log-file - 环形 master 将在此文件中创建其日志。

环形 master 应用程序协议

环形 master 的客户端通过终止于换行符的 ASCII 文本消息与之通信。环形 master 根据以下描述的每个请求进行适当的响应。

CONNECT ringname producer|consumer.n {comment string}

指示一个进程已作为客户端连接到名为 ringname 的环形缓冲区，在槽位 n 上作为生产者或消费者。注释字符串在功能上未被使用，只是日志消息的一部分。客户端必须是本地客户端，因为共享内存只在 localhost 上可见。可能的回复有

• OK\r\n - 成功。
• ERROR 失败原因\n - 如果请求失败。此请求失败可能有几个原因
  • 环形缓冲区的 ringname 服务器不认识。
  • 请求是从远程主机发出的。
  • 请求的槽位号在环形缓冲区中不存在。
  • pid 实际上并不拥有生产者或消费者槽位号。

注意，与 portmanager 端口分配一样，发起 CONNECT 请求的客户端必须保持与环形主机的连接，如果连接断开，效果与客户端发起 DISCONNECT 请求相同。

在 ERROR 的情况下，环形主机将断开客户端连接。

DISCONNECT ringname 生产者|消费者.n pid

断开指定进程 ID 与名为 ringname 的环形缓冲区的连接。监控 CONNECT 套接字的线程将在不久的将来退出（它在连接上有一个定时读取挂起，并将检查读取是否超时以确定是否应该退出）。可能的回复有

• OK\n - 成功。在监控线程退出后返回回复。
• ERROR - 错误原因字符串\n - 失败时。可能的错误包括
  • 请求来自远程主机。
  • ringname 不存在。
  • 请求的槽位号在环形缓冲区中不存在。

无论此请求成功或失败，环形主机都将断开客户端连接。

REGISTER ringname

当环形主机启动时，它将调查目标目录以查找环形缓冲区。目录中具有适当魔数字符串的前几个字节的文件将被注册。如果 NSCLDAQ 程序添加了新的环形缓冲区，它将向环形主机发送一个 REGISTER 请求。然后环形主机将 ringname 添加到它所知道的环形缓冲区集合中。

对客户端的可能回复

• OK\n - 成功。
• ERROR 错误原因字符串 - 以下是一些可能导致此请求失败的原因
  • 请求来自远程主机。
  • 环形缓冲区不为环形主机所知。

一旦发出回复，连接将被断开。

UNREGISTER ringname

当环形缓冲区被销毁时，将向环形缓冲区发出此请求。环形主机

1. 停止/加入所有监控剩余环形客户端的线程。
2. 如果可能，杀掉任何客户端进程（通常环形主机必须以 root 身份运行才能允许这样做）。
3. 从内部数据结构中删除对环形缓冲区的任何知识。

一旦采取所有这些行动，将向客户端发出回复并断开与客户端的连接。可能的回复有

• OK\n - 成功完成。
• ERROR 错误原因字符串 - 请求失败。这可以发生因为
  • 请求来自远程主机。
  • ringname 服务器不认识。

REMOTE ringname

此请求必须不来自本地主机。它用于从本地环形缓冲区到远程系统的环形数据提升设置。通常这是通过 NSCLDAQ CRemoteAccess 类来设置此环形主机本地环形缓冲区和远程系统本地代理环形缓冲区之间的数据流。

环形主机关于操作成功或失败的回复，然后派生一个子进程，该子进程将继承套接字以实际从环形缓冲区发送数据。子进程将作为普通消费者客户端向环形主机注册。

可能的回复有

• OK BINARY FOLOWS - 成功时，一旦发出此消息，客户端必须准备从环形缓冲区接收数据。
• ERROR 一些错误字符串 - 失败时。通常这将是一中
  • ringname 不为环形主机所知。
  • 请求不是来自远程主机（我们不允许hoisters本地主机，因为它们可以使用NSCLDAQ程序ringtostdout或ringselector通过管道访问数据，如果它们没有使用NSCLDAQ库构建。
  • 由于某些原因，无法启动用于提升数据的子进程。

列表

这可以在本地或远程主机上执行。它返回

OK ringlist\n

其中ringlist是一个Tcl（出于历史原因）格式的列表，描述了环形的使用。有关Tcl列表的格式，请参阅Tcl手册页面。列表中有每个已知环形缓冲区的一个元素。每个元素是一个包含以下内容的两个元素子列表：

• 环的名称。
• 按顺序排列的关于环的信息列表。
  • 环的大小（以字节为单位）。
  • 在生产者停滞之前可以放入环中的字节数。
  • 环支持的消费者数量。
  • 生产者的PID，如果没有则为-1。
  • 在消费者停滞之前，最落后的消费者可以获取的最大字节数 - 如果没有消费者，则为0。
  • 最追赶上消费者的最小字节数，如果没有则为0。
  • 关于每个消费者的信息列表。此列表可能为空，有每个消费者的一个元素。每个消费者子列表的元素包括：
    • 消费者的进程ID
    • 该消费者的回压字节数。