README.md

Description

Zyre does local area discovery and clustering. A Zyre node broadcasts
UDP beacons, and connects to peers that it finds. This class wraps a
Zyre node with a message-based API.

All incoming events are zmsg_t messages delivered via the zyre_recv
call. The first frame defines the type of the message, and following
frames provide further values:

ENTER fromnode headers ipaddress
a new peer has entered the network
EXIT fromnode
a peer has left the network
JOIN fromnode groupname
a peer has joined a specific group
LEAVE fromnode groupname
a peer has left a specific group
WHISPER fromnode message
a peer has sent this node a message
SHOUT fromnode groupname message
a peer has sent one of our groups a message
STOP fromnode
this node has stopped - no further events will be received

In SHOUT and WHISPER the message is a single frame in this version
of Zyre. In ENTER, the headers frame contains a packed dictionary,
see zhash_pack/unpack.

To join or leave a group, use the zyre_join and zyre_leave methods.
To set a header value, use the zyre_set_header method. To send a message
to a single peer, use zyre_whisper. To send a message to a group, use
zyre_shout.

API

// Constructor, creates a new Zyre node. Note that until you start the
// node it is silent and invisible to other nodes on the network.
zyre_t *
zyre_new (zctx_t *ctx);
// Destructor, destroys a Zyre node. When you destroy a node, any
// messages it is sending or receiving will be discarded.
void
zyre_destroy (zyre_t **self_p);
// Set node header; these are provided to other nodes during discovery
// and come in each ENTER message.
void
zyre_set_header (zyre_t *self, char *name, char *format, ...);
// Start node, after setting header values. When you start a node it
// begins discovery and connection. There is no stop method; to stop
// a node, destroy it.
void
zyre_start (zyre_t *self);
// Stop node, this signals to other peers that this node will go away.
// This is polite; however you can also just destroy the node without
// stopping it.
void
zyre_stop (zyre_t *self);
// Join a named group; after joining a group you can send messages to
// the group and all Zyre nodes in that group will receive them.
int
zyre_join (zyre_t *self, const char *group);
// Leave a group
int
zyre_leave (zyre_t *self, const char *group);
// Receive next message from network; the message may be a control
// message (ENTER, EXIT, JOIN, LEAVE) or data (WHISPER, SHOUT).
// Returns zmsg_t object, or NULL if interrupted
zmsg_t *
zyre_recv (zyre_t *self);
// Send message to single peer, specified as a UUID string
// Destroys message after sending
int
zyre_whisper (zyre_t *self, char *peer, zmsg_t **msg_p);
// Send message to a named group
// Destroys message after sending
int
zyre_shout (zyre_t *self, char *group, zmsg_t **msg_p);
// Send string to single peer specified as a UUID string.
// String is formatted using printf specifiers.
int
zyre_whispers (zyre_t *self, char *peer, char *format, ...);
// Send message to a named group
// Destroys message after sending
int
zyre_shouts (zyre_t *self, char *group, char *format, ...);
// Return handle to the Zyre node, for polling
void *
zyre_socket (zyre_t *self);
// Self test of this class
void
zyre_test (bool verbose);