Merge pull request #16 from microyahoo/notes

add notes for concurrency election

Author: microyahoo

client/v3/concurrency/election.go

@@ -70,16 +70,19 @@ func (e *Election) Campaign(ctx context.Context, val string) error {
 	s := e.session
 	client := e.session.Client()
 
+	// 如果 session 没有指定 lease id，则会为每个 session 生成新的 lease id
+	// key 的格式为 prefix+leaseID
 	k := fmt.Sprintf("%s%x", e.keyPrefix, s.Lease())
+	// 当 key 不存在时，createRevision 是 0
 	txn := client.Txn(ctx).If(v3.Compare(v3.CreateRevision(k), "=", 0))
-	txn = txn.Then(v3.OpPut(k, val, v3.WithLease(s.Lease())))
+	txn = txn.Then(v3.OpPut(k, val, v3.WithLease(s.Lease()))) // 为 key attach 租约
 	txn = txn.Else(v3.OpGet(k))
 	resp, err := txn.Commit()
 	if err != nil {
 		return err
 	}
 	e.leaderKey, e.leaderRev, e.leaderSession = k, resp.Header.Revision, s
-	if !resp.Succeeded {
+	if !resp.Succeeded { // 如果 key 已经存在了
 		kv := resp.Responses[0].GetResponseRange().Kvs[0]
 		e.leaderRev = kv.CreateRevision
 		if string(kv.Value) != val {
@@ -107,6 +110,7 @@ func (e *Election) Campaign(ctx context.Context, val string) error {
 }
 
 // Proclaim lets the leader announce a new value without another election.
+// leader 宣布新的值，即修改 leaderKey 对应的 value。如果提交失败则清空 leaderKey
 func (e *Election) Proclaim(ctx context.Context, val string) error {
 	if e.leaderSession == nil {
 		return ErrElectionNotLeader
@@ -134,6 +138,7 @@ func (e *Election) Resign(ctx context.Context) (err error) {
 		return nil
 	}
 	client := e.session.Client()
+	// 将 leaderkey, leaderRev 从数据库中删除，从而发起新的选举
 	cmp := v3.Compare(v3.CreateRevision(e.leaderKey), "=", e.leaderRev)
 	resp, err := client.Txn(ctx).If(cmp).Then(v3.OpDelete(e.leaderKey)).Commit()
 	if err == nil {

client/v3/concurrency/mutex.go

@@ -120,9 +120,9 @@ func (m *Mutex) tryAcquire(ctx context.Context) (*v3.TxnResponse, error) {
 	// put self in lock waiters via myKey; oldest waiter holds lock
 	put := v3.OpPut(m.myKey, "", v3.WithLease(s.Lease()))
 	// reuse key in case this session already holds the lock
-	get := v3.OpGet(m.myKey)
+	get := v3.OpGet(m.myKey) // 这里是使用 mykey 来进行查询的
 	// fetch current holder to complete uncontended path with only one RPC
-	getOwner := v3.OpGet(m.pfx, v3.WithFirstCreate()...)
+	getOwner := v3.OpGet(m.pfx, v3.WithFirstCreate()...) // 这里是使用 prefix 来进行查询的
 	// 如果 key 不存在则将 key 写入数据库，如果已经存在则读取 key 的记录信息，所有的操作在一个事务中
 	resp, err := client.Txn(ctx).If(cmp).Then(put, getOwner).Else(get, getOwner).Commit()
 	if err != nil {