election_api

func MaybeAcquireLeadership ¶

func MaybeAcquireLeadership(client *api.Client, leaderKey string, leadershipCheckInterval int, sessionTTL int, sessionName string, exitOnLockFound bool, j DoJob)

MaybeAcquireLeadership function takes a consul client, leader key string, check interval (in seconds), session ttl (in seconds), session name, exit on lock found as well as a DoJob implementation. It tries to acquire a lock by associating a session to the key. If acquired, it attains mastership setting the value of the key to hostname:pid. The DoJobFunc implementation is run in a go routine. The function could run till it ends voluntarily closing the doneCh channel. The api could could sent a stop signal via the stopCh in case leadership is lost. In such a situation the DoJobFunc implementaion should return. The exitOnLockFound parameter should be set to true in situations where you want your application to exit if lock is found. For continuosly applications needing high availability support this should be set to false. The api leverages the TTL field of sessions. The following text from the consul.io is useful to know.

When creating a session, a TTL can be specified. If the TTL interval expires without being renewed, the session has expired and an invalidation is triggered. This type of failure detector is also known as a heartbeat failure detector. It is less scalable than the gossip based failure detector as it places an increased burden on the servers but may be applicable in some cases. The contract of a TTL is that it represents a lower bound for invalidation; that is, Consul will not expire the session before the TTL is reached, but it is allowed to delay the expiration past the TTL. The TTL is renewed on session creation, on session renew, and on leader failover. When a TTL is being used, clients should be aware of clock skew issues: namely, time may not progress at the same rate on the client as on the Consul servers. It is best to set conservative TTL values and to renew in advance of the TTL to account for network delay and time skew.

The final nuance is that sessions may provide a lock-delay. This is a time duration, between 0 and 60 seconds. When a session invalidation takes place, Consul prevents any of the previously held locks from being re-acquired for the lock-delay interval; this is a safeguard inspired by Google's Chubby. The purpose of this delay is to allow the potentially still live leader to detect the invalidation and stop processing requests that may lead to inconsistent state. While not a bulletproof method, it does avoid the need to introduce sleep states into application logic and can help mitigate many issues. While the default is to use a 15 second delay, clients are able to disable this mechanism by providing a zero delay value.