1ZGOSSIP(3) CZMQ Manual ZGOSSIP(3)
2
6 zgossip - decentralized configuration management
7
9 // To work with zgossip, use the CZMQ zactor API:
10 //
11 // Create new zgossip instance, passing logging prefix:
12 //
13 // zactor_t *zgossip = zactor_new (zgossip, "myname");
14 //
15 // Destroy zgossip instance
16 //
17 // zactor_destroy (&zgossip);
18 //
19 // Enable verbose logging of commands and activity:
20 //
21 // zstr_send (zgossip, "VERBOSE");
22 //
23 // Bind zgossip to specified endpoint. TCP endpoints may specify
24 // the port number as "*" to aquire an ephemeral port:
25 //
26 // zstr_sendx (zgossip, "BIND", endpoint, NULL);
27 //
28 // Return assigned port number, specifically when BIND was done using an
29 // an ephemeral port:
30 //
31 // zstr_sendx (zgossip, "PORT", NULL);
32 // char *command, *port_str;
33 // zstr_recvx (zgossip, &command, &port_str, NULL);
34 // assert (streq (command, "PORT"));
35 //
36 // Specify configuration file to load, overwriting any previous loaded
37 // configuration file or options:
38 //
39 // zstr_sendx (zgossip, "LOAD", filename, NULL);
40 //
41 // Set configuration path value:
42 //
43 // zstr_sendx (zgossip, "SET", path, value, NULL);
44 //
45 // Save configuration data to config file on disk:
46 //
47 // zstr_sendx (zgossip, "SAVE", filename, NULL);
48 //
49 // Send zmsg_t instance to zgossip:
50 //
51 // zactor_send (zgossip, &msg);
52 //
53 // Receive zmsg_t instance from zgossip:
54 //
55 // zmsg_t *msg = zactor_recv (zgossip);
56 //
57 // This is the zgossip constructor as a zactor_fn:
58 //
59 CZMQ_EXPORT void
60 zgossip (zsock_t *pipe, void *args);
61 // Self test of this class
63 CZMQ_EXPORT void
64 zgossip_test (bool verbose);
65 Please add '@interface' section in './../src/zgossip.c'.
66
68 Implements a gossip protocol for decentralized configuration
69 management. Your applications nodes form a loosely connected network
70 (which can have cycles), and publish name/value tuples. Each node
71 re-distributes the new tuples it receives, so that the entire network
72 eventually achieves a consistent state. The current design does not
73 expire tuples.
74 Provides these commands (sent as multipart strings to the actor):
76 · BIND endpoint — binds the gossip service to specified endpoint
78 · PORT — returns the last TCP port, if any, used for binding
80 · LOAD configfile — load configuration from specified file
82 · SET configpath value — set configuration path = value
84 · SAVE configfile — save configuration to specified file
86 · CONNECT endpoint — connect the gossip service to the specified peer
88 · PUBLISH key value — publish a key/value pair to the gossip cluster
90 · STATUS — return number of key/value pairs held by gossip service
92 Returns these messages:
94 · PORT number — reply to PORT command
96 · STATUS number — reply to STATUS command
98 · DELIVER key value — new tuple delivered from network
100 The gossip protocol distributes information around a loosely-connected
102 network of gossip services. The information consists of name/value
103 pairs published by applications at any point in the network. The goal
104 of the gossip protocol is to create eventual consistency between all
105 the using applications.
106 The name/value pairs (tuples) can be used for configuration data, for
108 status updates, for presence, or for discovery. When used for
109 discovery, the gossip protocol works as an alternative to e.g. UDP
110 beaconing.
111 The gossip network consists of a set of loosely-coupled nodes that
113 exchange tuples. Nodes can be connected across arbitrary transports, so
114 the gossip network can have nodes that communicate over inproc, over
115 IPC, and/or over TCP, at the same time.
116 Each node runs the same stack, which is a server-client hybrid using a
118 modified Harmony pattern (from Chapter 8 of the Guide):
119 http://zguide.zeromq.org/page:all#True-Peer-Connectivity-Harmony-Pattern
120 Each node provides a ROUTER socket that accepts client connections on
122 an key defined by the application via a BIND command. The state machine
123 for these connections is in zgossip.xml, and the generated code is in
124 zgossip_engine.inc.
125 Each node additionally creates outbound connections via DEALER sockets
127 to a set of servers ("remotes"), and under control of the calling app,
128 which sends CONNECT commands for each configured remote.
129 The messages between client and server are defined in zgossip_msg.xml.
131 We built this stack using the zeromq/zproto toolkit.
132 To join the gossip network, a node connects to one or more peers. Each
134 peer acts as a forwarder. This loosely-coupled network can scale to
135 thousands of nodes. However the gossip protocol is NOT designed to be
136 efficient, and should not be used for application data, as the same
137 tuples may be sent many times across the network.
138 The basic logic of the gossip service is to accept PUBLISH messages
140 from its owning application, and to forward these to every remote, and
141 every client it talks to. When a node gets a duplicate tuple, it throws
142 it away. When a node gets a new tuple, it stores it, and fowards it as
143 just described. At any point the application can access the node’s set
144 of tuples.
145 At present there is no way to expire tuples from the network.
147 The assumptions in this design are:
149 · The data set is slow-changing. Thus, the cost of the gossip
151 protocol is irrelevant with respect to other traffic.
152
154 From zgossip_test method.
155 // Test basic client-to-server operation of the protocol
157 zactor_t *server = zactor_new (zgossip, "server");
158 assert (server);
159 if (verbose)
160 zstr_send (server, "VERBOSE");
161 zstr_sendx (server, "BIND", "inproc://zgossip", NULL);
162 zsock_t *client = zsock_new (ZMQ_DEALER);
164 assert (client);
165 zsock_set_rcvtimeo (client, 2000);
166 int rc = zsock_connect (client, "inproc://zgossip");
167 assert (rc == 0);
168 // Send HELLO, which gets no message
170 zgossip_msg_t *message = zgossip_msg_new ();
171 zgossip_msg_set_id (message, ZGOSSIP_MSG_HELLO);
172 zgossip_msg_send (message, client);
173 // Send PING, expect PONG back
175 zgossip_msg_set_id (message, ZGOSSIP_MSG_PING);
176 zgossip_msg_send (message, client);
177 zgossip_msg_recv (message, client);
178 assert (zgossip_msg_id (message) == ZGOSSIP_MSG_PONG);
179 zgossip_msg_destroy (&message);
180 zactor_destroy (&server);
182 zsock_destroy (&client);
183 // Test peer-to-peer operations
185 zactor_t *base = zactor_new (zgossip, "base");
186 assert (base);
187 if (verbose)
188 zstr_send (base, "VERBOSE");
189 // Set a 100msec timeout on clients so we can test expiry
190 zstr_sendx (base, "SET", "server/timeout", "100", NULL);
191 zstr_sendx (base, "BIND", "inproc://base", NULL);
192 zactor_t *alpha = zactor_new (zgossip, "alpha");
194 assert (alpha);
195 zstr_sendx (alpha, "CONNECT", "inproc://base", NULL);
196 zstr_sendx (alpha, "PUBLISH", "inproc://alpha-1", "service1", NULL);
197 zstr_sendx (alpha, "PUBLISH", "inproc://alpha-2", "service2", NULL);
198 zactor_t *beta = zactor_new (zgossip, "beta");
200 assert (beta);
201 zstr_sendx (beta, "CONNECT", "inproc://base", NULL);
202 zstr_sendx (beta, "PUBLISH", "inproc://beta-1", "service1", NULL);
203 zstr_sendx (beta, "PUBLISH", "inproc://beta-2", "service2", NULL);
204 // got nothing
206 zclock_sleep (200);
207 zactor_destroy (&base);
209 zactor_destroy (&alpha);
210 zactor_destroy (&beta);
211
214 The czmq manual was written by the authors in the AUTHORS file.
215
217 Main web site:
218 Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>
220
222 Copyright (c) the Contributors as noted in the AUTHORS file. This file
223 is part of CZMQ, the high-level C binding for 0MQ:
224 http://czmq.zeromq.org. This Source Code Form is subject to the terms
225 of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
226 distributed with this file, You can obtain one at
227 http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
228 distribution.
229
231 1. zeromq-dev@lists.zeromq.org
232 mailto:zeromq-dev@lists.zeromq.org
233CZMQ 4.0.2 12/31/2016 ZGOSSIP(3)