reed-lau / etcd-api Goto Github PK

This is a C interface to etcd, plus a command-line tool that exercises the API. In brief, the supported calls are:

• etcd_open (server-list [as an array])

• etcd_open_str (server-list [as a string])

• etcd_close and etcd_close_str

• etcd_get (key) including support for listing keys by prefix

• etcd_set (key, value, [optional] prev-value, [optional] ttl)

• etcd_delete (key)

• etcd_leader

• etcd_watch (prefix, [optional] index)

• etcd_lock (key, ttl, [optional] index)

• etcd_unlock (key, index)

See etcd-api.h for precise types and so on. The library will automatically try requests on a succession of servers in server-list.

The command-line utility etcd-test (showing its origins and primary usage so far) can do get/set/delete/leader for you. Servers can be specified either on the command line (-s) or through the ETCD_SERVERS environment variable.

DEPRECATED The leader program is an example of how to use the etcd primitives for a simple leader-election protocol, for code that needs a leader separate from the etcd leader. It uses the same conventions as etcd-test for specifying the servers. Just for fun, leader.m includes a Murphi model for the protocol.

The above code is deprecated due to the existence of etcd's own lock module. These locks are really leases which expire after a specified timeout, but for now consistency with etcd's terminology is more important than consistency with the name any computer-science graduate would have used. There's also a leader module, but it lacks the critical timeout functionality.

• Issue etcd_lock without an index to try for leadership. This provides notification when the local node gains leadership (if ever).

• Once leadership has been obtained, periodically renew it by issuing etcd_lock with an index. This provides notification when the local node loses leadership (e.g. because it took too long to renew).

• If you care about leadership changes between other nodes, you'll have to monitor for those separately. Unfortunately, neither the lock module nor the leader module seems to support "watch" functionality. There's not much you can do other than use etcd_watch on a separate key (probably in a separate thread) to get some idea when such changes occur.

This project depends on libcurl and YAJL 2.x (for the tree interface).