README
¶
gozyre - Local area clustering for P2P applications
Introduction
A golang interface to the Zyre library.
The interface is not exactly one-to-one, but exposes the basics needed for writing applications.
Usage Examples
Create a new node named 'node1' bound to the 'eth1' interface. The node will be using udp beaconing on port 5670 and reporting the key-value pairs as headers.
import "github.com/misakwa/gozyre"
func main() {
node1 := gozyre.New("node1", "eth1", 5670, map[string]string{"key":"value"}, false)
defer node1.Destroy()
}
Create a new node with autogenerated name and default chosen interface
import "github.com/misakwa/gozyre"
func main() {
node2 := gozyre.New("", "", 0, map[string]string{}, false)
defer node2.Destroy()
}
Much more complete example inspired by the tests
import (
"log"
"time"
"github.com/misakwa/gozyre"
)
func main() {
node1 := gozyre.New("node1", "", 0, map[string]string{}, false)
defer node1.Destroy()
node2 := gozyre.New("node2", "", 0, map[string]string{"X-HELLO": "World"}, false)
defer node2.Destroy()
// Setup gossip discovery with endpoint
var err error
err = node1.Gossip("inproc://zyre-node1", "inproc://gossip-hub")
if err != nil {
log.Fatalf("Unable to setup gossip discovery: %s", err)
}
err = node2.Gossip("inproc://zyre-node2", "inproc://gossip-hub")
if err != nil {
log.Fatalf("Unable to setup gossip discovery: %s", err)
}
// Start nodes
node1.Start()
node2.Start()
// Join group
node1.Join("GLOBAL")
node2.Join("GLOBAL")
// Allow time for discovery
time.Sleep(10 * time.Millisecond)
mch := make(chan []byte)
go func() {
defer close(mch)
mch <- []byte("Hello, World")
}()
// node1 shouts message to global
node1.Shout("GLOBAL", mch)
// Call recieve as many times as there are messages
for {
evt, err := node2.Recv()
if err != nil {
log.Fatalf("Unable to receive node message: %s", err)
}
log.Println("event type = %s", evt.Type())
for frame := range evt.Message() {
log.Printf("%s", frame)
}
evt.Destroy()
}
}
Disclaimer
I haven't used this in production yet and there are most likely bugs everywhere.
TODO
- Implement chat example in go
- Test all the example snippets
- Add more tests
Documentation
¶
Overview ¶
Package gozyre provides a wrapping around the zyre c-library. It provides clustering for peer-to-peer applications. See: https://github.com/zeromq/zyre.
Package gozyre provides ...
Index ¶
- Constants
- Variables
- type Event
- func (ev *Event) Address() string
- func (ev *Event) Destroy()
- func (ev *Event) Group() string
- func (ev *Event) Header(name string) string
- func (ev *Event) Headers() map[string]string
- func (ev *Event) Message() <-chan []byte
- func (ev *Event) Peer() string
- func (ev *Event) Type() EventType
- func (ev *Event) UUID() string
- type EventType
- type Zyre
- func (n *Zyre) Destroy()
- func (n *Zyre) Gossip(endpoint, hub string) error
- func (n *Zyre) Groups() []string
- func (n *Zyre) Join(group string)
- func (n *Zyre) Leave(group string)
- func (n *Zyre) Name() string
- func (n *Zyre) PeerAddress(uuid string) string
- func (n *Zyre) PeerGroups() []string
- func (n *Zyre) PeerHeader(uuid, name string) string
- func (n *Zyre) Peers(group string) []string
- func (n *Zyre) Recv() (*Event, error)
- func (n *Zyre) SetEvasive(timeout time.Duration)
- func (n *Zyre) SetExpire(expired time.Duration)
- func (n *Zyre) SetInterval(interval time.Duration)
- func (n *Zyre) Shout(name string, frames <-chan []byte) error
- func (n *Zyre) Start() error
- func (n *Zyre) Stop()
- func (n *Zyre) UUID() string
- func (n *Zyre) Whisper(name string, frames <-chan []byte) error
Constants ¶
const ( // JoinEvent indicates a node has joined a specific group JoinEvent EventType = "JOIN" // ExitEvent indicates a node has left the network ExitEvent = "EXIT" // EnterEvent indicates a node hash entered the network EnterEvent = "ENTER" // LeaveEvent indicates a peer has left a specific group LeaveEvent = "LEAVE" // StopEvent indicates that a node will go away StopEvent = "STOP" // EvasiveEvent indicates a node is being quiet for too long EvasiveEvent = "EVASIVE" // WhisperEvent indicates a peer has sent a message to this node WhisperEvent = "WHISPER" // ShoutEvent indicates a peer has sent a message to a group ShoutEvent = "SHOUT" // UnknownEvent indicates a message that is unsupported or unknown UnknownEvent = "UNKNOWN" )
Variables ¶
var ( //ZMQVersionMajor is the major version of the underlying ZeroMQ library ZMQVersionMajor = int(C.ZMQ_VERSION_MAJOR) //ZMQVersionMinor is the minor version of the underlying ZeroMQ library ZMQVersionMinor = int(C.ZMQ_VERSION_MINOR) //CZMQVersionMajor is the major version of the underlying CZMQ library CZMQVersionMajor = int(C.CZMQ_VERSION_MAJOR) // CZMQVersionMinor is the minor version of the underlying CZMQ library CZMQVersionMinor = int(C.CZMQ_VERSION_MINOR) // ZyreVersion is the underlying version of the Zyre library ZyreVersion = uint64(C.ZYRE_VERSION) // major * 10000 + minor * 100 + patch, as a single integer // ZyreVersionMajor is the major version of the underlying Zyre library ZyreVersionMajor = int(C.ZYRE_VERSION_MAJOR) // ZyreVersionMinor is the minor version of the underlying Zyre library ZyreVersionMinor = int(C.ZYRE_VERSION_MINOR) // ZyreVersionPatch is the patch version of the underlying Zyre library ZyreVersionPatch = int(C.ZYRE_VERSION_PATCH) )
var ( // ErrStartFailed is to used to represent startup failures ErrStartFailed = errors.New("error starting zyre node") // ErrNodeInterrupted is used to indicate an interruped node when receiving messages ErrNodeInterrupted = errors.New("error receiving message from node") // ErrInvalidEndpoint returned when setting an invalid endpoint ErrInvalidEndpoint = errors.New("error setting endpoint") // ErrAddingFrame is returned when constructing message frames for sending ErrAddingFrame = errors.New("error adding message frame") )
Functions ¶
This section is empty.
Types ¶
type Event ¶
type Event struct {
// contains filtered or unexported fields
}
Event describes a network event
func (*Event) Destroy ¶
func (ev *Event) Destroy()
Destroy removes and frees up the event object memory. The event should not be used after callling this method.
func (*Event) Headers ¶
Headers returns the event headers. These are the headers from the node that initiated this event. XXX: Do we need to lock the headers? The underlying implementation uses a cursor to iterate through the items and may introduce race conditions.
func (*Event) Message ¶
Message returns the frames of data from the message content, each frame as a byte slice XXX: Do we need to lock the channel so that only one consumer can call it? The underlying implementation iterates through the message frames using a cursor and can introduce race conditions.
type Zyre ¶
type Zyre struct {
// contains filtered or unexported fields
}
Zyre struct wraps the C zyre_t struct
func New ¶
New constructs a new node for peer-to-peer discovery Constructor, creates a new Zyre node. Note that until you start the node, it is silent and invisible to other nodes on the network. The node name is provided to other nodes during discovery. If you specify an empty string, Zyre generates a randomized node name from the UUID. Specify an empty string for the interface to have the system choose the default. Specify 0 for the port to use the default port specification from the c library
func (*Zyre) Destroy ¶
func (n *Zyre) Destroy()
Destroy shuts down the node. Any messages that are being sent or received will be discarded.
func (*Zyre) Gossip ¶
Gossip sets up gossip discovery and switches from using the default UDP beaconing It will bind and connect to the gossip endpoint
func (*Zyre) Join ¶
Join joins the named group. After joining a group you can send messages to the group and all nodes in that group will receive them.
func (*Zyre) Name ¶
Name returns our node name, after successful initialization. By default is taken from the UUID and shortened.
func (*Zyre) PeerAddress ¶
PeerAddress returns the endpoint of a connected peer.
func (*Zyre) PeerGroups ¶
PeerGroups returns list of groups known through peers
func (*Zyre) PeerHeader ¶
PeerHeader returns a peer header value. It will return an empty string if peer or header doesn't exist.
func (*Zyre) Peers ¶
Peers returns list of peers in a specified group. It will return a list of all current peers if an empty string is specified
func (*Zyre) SetEvasive ¶
SetEvasive sets the node evasiveness timeout. Default is 5 * time.Millisecond.
func (*Zyre) SetInterval ¶
SetInterval sets the UDP beacon discovery interval. Default is instant beacon exploration followed by pinging every 1 * time.Second
Source Files