17/ZDCF
零MQ设备配置文件
- 状态：稳定版
- 编辑：Pieter Hintjens ph@imatix.com
- 贡献者：Steffen Mueller smueller@cpan.org
零MQ设备配置文件（ZDCF）指定了一种配置零MQ设备的标准语言。它提供信息来配置一个零MQ上下文和一组零MQ套接字。本规范旨在使构建、共享和重用零MQ设备以及构建设备管理系统变得更容易。
许可证
版权所有 (c) 2010-2012 iMatix Corporation 及贡献者
本规范是自由软件；您可以根据自由软件基金会发布的 GNU 通用公共许可证（GPL）条款对其进行再分发和/或修改；您可以选择使用许可证的第 3 版，或（由您选择）任何后续版本。
发布本规范是希望它会有用，但不提供任何担保；甚至不提供适销性或特定用途适用性的默示担保。详情请参见 GNU 通用公共许可证。
您应该已经随本程序收到了 GNU 通用公共许可证的副本；如果没有，请参见 https://gnu.ac.cn/licenses。
变更流程
本规范是一个自由开放的标准（参见“自由开放标准的定义”），并由数字标准组织 (Digistan) 的面向共识的规范系统 (COSS) 管理（参见“面向共识的规范系统”）。
语言
本文档中的关键词“必须 (MUST)”、“不得 (MUST NOT)”、“必需 (REQUIRED)”、“应 (SHALL)”、“不应 (SHALL NOT)”、“应该 (SHOULD)”、“不应该 (SHOULD NOT)”、“建议 (RECOMMENDED)”、“可以 (MAY)”和“可选 (OPTIONAL)”应按照 RFC 2119 中的描述进行解释（参见“RFC 中表示要求级别的关键词”）。
目标
ZDCF 的目标是
- 为设备配置提供标准的、可重用的语义。
- 允许在任何树形结构语法中兼容地表达。
- 对不同的编程语言尽可能广泛地可访问。
- 涵盖所有零MQ上下文和套接字配置选项。
架构
ZDCF 使用树形结构语义，可以使用任意语法（如 ZPL（参见“ZFL 属性语言”）、JSON（参见“JSON 介绍”）、XML 或其他）来实现。尽管本文档和名称“ZDCF”是指文件，但从技术上讲，ZDCF 的实现并没有理由不接受内存中的数据结构，如嵌套字典或哈希映射。
在以下规范中，任何对字典的引用都应理解为任何将字符串键映射到另一个数据结构的数据结构。
全局属性
在顶层，ZDCF 结构是一个字典。空字典经过特殊处理，表示一个空的 ZDCF；这是一个有效的 JSON 格式文件。
{
}
任何其他 ZDCF 文件都必须在顶层字典的“version”属性中，包含编写该 ZDCF 文件所依据的 ZDCF 规范版本号，该版本号是一个浮点数。有关实现如何处理版本信息的说明，请参见下文。
除了规范版本之外，ZDCF 文件的顶层字典可能包含“apps”，这是一个应用程序名称到独立应用程序定义的映射字典。每个这样的应用程序都包含一个可选的上下文对象和零个或多个设备对象。概念上，一个应用程序映射到一个进程，该进程由一个上下文和零个或多个设备线程组成。
以下是用 JSON 表达的 ZDCF 文件的典型示例
{
"version": 1.0,
"apps": {
"listener": {
"context": {
"iothreads": 1,
"verbose": true
},
"devices": {
"main": {
"type": "zmq_queue",
"sockets": {
"frontend": {
"type": "SUB",
"option": {
"hwm": 1000,
"swap": 25000000
},
"bind": "tcp://eth0:5555"
},
"backend": {
"bind": "tcp://eth0:5556"
}
}
}
}
}
}
}
以下是用 ZPL 表达的相同属性树示例（参见“ZFL 属性语言”）。
version = 1.0
apps
listener
context
iothreads = 1
verbose = 1
devices
main
type = zmq_queue
sockets
frontend
type = SUB
option
hwm = 1000
swap = 25000000
bind = tcp://eth0:5555
backend
bind = tcp://eth0:5556
以及简单的 XML 示例
<zdcf>
<version>1.0</version>
<apps>
<context iothreads = "1" verbose = "1" />
<main type = "zmq_queue">
<sockets>
<frontend type = "SUB">
<option hwm = "1000" swap = "25000000" />
<bind>tcp://eth0:5555</bind>
</frontend>
<backend>
<bind>tcp://eth0:5556</bind>
</backend>
</sockets>
</main>
</apps>
</zdcf>
应用程序对象
如上所述，每个应用程序对象表示一个进程，该进程可能包含多个在线程中运行的零MQ设备。应用程序可以在字典中有一个名为“context”的条目作为上下文对象。它可能有一个名为“devices”的字典，将设备名称映射到设备对象。总而言之，应用程序可以有以下属性：
- 其在“apps”字典中的名称。
- “context” - 可选的上下文对象
- “devices” - 将零个或多个设备名称映射到设备对象的字典
上下文对象
上下文对象在每个应用程序中都是可选的，并具有以下属性：
- 其在应用程序字典中的名称为“context”。
- “iothreads” - (整数) - 指定上下文的 I/O 线程数。如果未指定或应用程序中没有显式上下文对象，则默认为 1。
- “verbose” - (布尔值) - 如果为“true”，解析 JSON 的程序应输出跟踪信息。如果未指定，则默认为“false”。
设备对象
设备对象可以在应用程序的“devices”部分出现零次或多次，并具有以下属性：
- 它们的名称在其应用程序的“devices”字典中是唯一的。
- “type” - (字符串) - 可选。指定设备类型。以“z”开头的类型保留给内置零MQ设备使用。应用程序可以根据需要定义其他设备类型。
- “sockets” - 将零个或多个套接字名称映射到套接字对象的字典
在编写本文时存在的内置设备类型有：
- “zmq_queue” - ZMQ_QUEUE
- “zmq_forwarder” - ZMQ_FORWARDER
- “zmq_streamer” - ZMQ_STREAMER
有关内置设备类型的详情，请参见 zmq_device(3)。
套接字对象
套接字对象可以在设备对象的“sockets”部分出现零次或多次，并具有以下属性：
- 名称在其包含的设备中是唯一的。
- “type” - (字符串) - 指定套接字类型。
- “bind” - (字符串) - 指定零个或多个要将套接字绑定到的端点。
- “connect” - (字符串) - 指定零个或多个要将套接字连接到的端点。
- “option” - (对象) - 一个套接字选项对象，用于指定套接字的配置。
在编写本文时存在的套接字类型有：
- “sub” - ZMQ_SUB
- “pub” - ZMQ_PUB
- “req” - ZMQ_REQ
- “rep” - ZMQ_REP
- “dealer” - ZMQ_DEALER
- “router” - ZMQ_ROUTER
- “push” - ZMQ_PUSH
- “pull” - ZMQ_PULL
- “pair” - ZMQ_PAIR
详情请参见 zmq_socket(3)。
套接字选项对象
套接字选项对象在套接字对象内部是可选的。它具有以下属性：
- 其名称为“option”。
- “hwm” - (整数) - 指定 ZMQ_HWM 选项。
- “swap” - (整数) - 指定 ZMQ_SWAP 选项。
- “affinity” - (整数) - 指定 ZMQ_AFFINITY 选项。
- “identity” - (字符串) - 指定 ZMQ_IDENTITY 选项。
- “subscribe” - (字符串) - 指定 ZMQ_SUBSCRIBE 选项。
- “rate” - (整数) - 指定 ZMQ_RATE 选项。
- “recovery_ivl” - (整数) - 指定 ZMQ_RECOVERY_IVL 选项。
- “mcast_loop” - (布尔值) - 指定 ZMQ_MCAST_LOOP 选项。
- “sndbuf” - (整数) - 指定 ZMQ_SNDBUF 选项。
- “rcvbuf” - (整数) - 指定 ZMQ_RCVBUF 选项。
详情请参见 zmq_setsockopt(3)。
值数组
在有意义的情况下，属性可以指定为值数组，至少包括：
- 套接字的“bind”属性。
- 套接字的“connect”属性。
- 选项的“subscribe”属性。
例如
"frontend": {
"option": {
"subscribe": [ "10001", "10002" ]
},
"bind": [ "tcp://eth0:5555", "inproc://device" ]
}
处理规范版本
作为 ZDCF 文件的作者，您必须包含编写该 ZDCF 文件所依据的规范版本。规范版本是一个浮点数，并且必须按浮点数进行比较。规范版本中小数部分的任何更改都被认为是向后兼容的更改。规范版本中整数部分的任何更改都被理解为不向后兼容的更改。
处理 ZDCF 内容的软件必须遵守以下规则：
- 它应接受任何与其声称支持的规范版本相符、且符合规范的 ZDCF 内容。
- 它不应接受任何针对整数版本高于该处理 ZDCF 内容的软件所能接受的规范而编写的 ZDCF 内容。
换句话说，您可以自由地实现与旧版本规范的向后兼容性，但请不要静默地尝试接受针对您未实现的规范编写的内容。您的用户会因此感谢您。如果在实现时，您可以访问到的规范版本是 5.3，那么您可以接受针对 5.4 编写的内容，前提是这是一个向后兼容的规范更改。但是，您应该拒绝 ZDCF 6.0，直到您更新了您的实现来处理它。