1# memberlist [![GoDoc](https://godoc.org/github.com/hashicorp/memberlist?status.png)](https://godoc.org/github.com/hashicorp/memberlist) 2 3memberlist is a [Go](http://www.golang.org) library that manages cluster 4membership and member failure detection using a gossip based protocol. 5 6The use cases for such a library are far-reaching: all distributed systems 7require membership, and memberlist is a re-usable solution to managing 8cluster membership and node failure detection. 9 10memberlist is eventually consistent but converges quickly on average. 11The speed at which it converges can be heavily tuned via various knobs 12on the protocol. Node failures are detected and network partitions are partially 13tolerated by attempting to communicate to potentially dead nodes through 14multiple routes. 15 16## Building 17 18If you wish to build memberlist you'll need Go version 1.2+ installed. 19 20Please check your installation with: 21 22``` 23go version 24``` 25 26Run `make deps` to fetch dependencies before building 27 28## Usage 29 30Memberlist is surprisingly simple to use. An example is shown below: 31 32```go 33/* Create the initial memberlist from a safe configuration. 34 Please reference the godoc for other default config types. 35 http://godoc.org/github.com/hashicorp/memberlist#Config 36*/ 37list, err := memberlist.Create(memberlist.DefaultLocalConfig()) 38if err != nil { 39 panic("Failed to create memberlist: " + err.Error()) 40} 41 42// Join an existing cluster by specifying at least one known member. 43n, err := list.Join([]string{"1.2.3.4"}) 44if err != nil { 45 panic("Failed to join cluster: " + err.Error()) 46} 47 48// Ask for members of the cluster 49for _, member := range list.Members() { 50 fmt.Printf("Member: %s %s\n", member.Name, member.Addr) 51} 52 53// Continue doing whatever you need, memberlist will maintain membership 54// information in the background. Delegates can be used for receiving 55// events when members join or leave. 56``` 57 58The most difficult part of memberlist is configuring it since it has many 59available knobs in order to tune state propagation delay and convergence times. 60Memberlist provides a default configuration that offers a good starting point, 61but errs on the side of caution, choosing values that are optimized for 62higher convergence at the cost of higher bandwidth usage. 63 64For complete documentation, see the associated [Godoc](http://godoc.org/github.com/hashicorp/memberlist). 65 66## Protocol 67 68memberlist is based on ["SWIM: Scalable Weakly-consistent Infection-style Process Group Membership Protocol"](http://www.cs.cornell.edu/~asdas/research/dsn02-swim.pdf). However, we extend the protocol in a number of ways: 69 70* Several extensions are made to increase propagation speed and 71convergence rate. 72* Another set of extensions, that we call Lifeguard, are made to make memberlist more robust in the presence of slow message processing (due to factors such as CPU starvation, and network delay or loss). 73 74For details on all of these extensions, please read our paper "[Lifeguard : SWIM-ing with Situational Awareness](https://arxiv.org/abs/1707.00788)", along with the memberlist source. We welcome any questions related 75to the protocol on our issue tracker. 76