concurrency - ActiveState ActiveGo 1.8
...

Package concurrency

import "github.com/coreos/etcd/clientv3/concurrency"
Overview
Index

Overview ▾

Package concurrency implements concurrency operations on top of etcd such as distributed locks, barriers, and elections.

Index ▾

Variables
func NewLocker(s *Session, pfx string) sync.Locker
func NewSTM(c *v3.Client, apply func(STM) error, so ...stmOption) (*v3.TxnResponse, error)
func NewSTMReadCommitted(ctx context.Context, c *v3.Client, apply func(STM) error) (*v3.TxnResponse, error)
func NewSTMRepeatable(ctx context.Context, c *v3.Client, apply func(STM) error) (*v3.TxnResponse, error)
func NewSTMSerializable(ctx context.Context, c *v3.Client, apply func(STM) error) (*v3.TxnResponse, error)
func WithAbortContext(ctx context.Context) stmOption
func WithIsolation(lvl Isolation) stmOption
func WithPrefetch(keys ...string) stmOption
type Election
    func NewElection(s *Session, pfx string) *Election
    func ResumeElection(s *Session, pfx string, leaderKey string, leaderRev int64) *Election
    func (e *Election) Campaign(ctx context.Context, val string) error
    func (m *Election) Header() *pb.ResponseHeader
    func (e *Election) Key() string
    func (e *Election) Leader(ctx context.Context) (*v3.GetResponse, error)
    func (e *Election) Observe(ctx context.Context) <-chan v3.GetResponse
    func (e *Election) Proclaim(ctx context.Context, val string) error
    func (e *Election) Resign(ctx context.Context) (err error)
    func (e *Election) Rev() int64
type Isolation
type Mutex
    func NewMutex(s *Session, pfx string) *Mutex
    func (m *Mutex) Header() *pb.ResponseHeader
    func (m *Mutex) IsOwner() v3.Cmp
    func (m *Mutex) Key() string
    func (m *Mutex) Lock(ctx context.Context) error
    func (m *Mutex) Unlock(ctx context.Context) error
type STM
type Session
    func NewSession(client *v3.Client, opts ...SessionOption) (*Session, error)
    func (s *Session) Client() *v3.Client
    func (s *Session) Close() error
    func (s *Session) Done() <-chan struct{}
    func (s *Session) Lease() v3.LeaseID
    func (s *Session) Orphan()
type SessionOption
    func WithContext(ctx context.Context) SessionOption
    func WithLease(leaseID v3.LeaseID) SessionOption
    func WithTTL(ttl int) SessionOption

Package files

doc.go election.go key.go mutex.go session.go stm.go

Variables

var (
    ErrElectionNotLeader = errors.New("election: not leader")
    ErrElectionNoLeader  = errors.New("election: no leader")
)

func NewLocker

func NewLocker(s *Session, pfx string) sync.Locker

NewLocker creates a sync.Locker backed by an etcd mutex.

func NewSTM

func NewSTM(c *v3.Client, apply func(STM) error, so ...stmOption) (*v3.TxnResponse, error)

NewSTM initiates a new STM instance, using snapshot isolation by default.

func NewSTMReadCommitted

func NewSTMReadCommitted(ctx context.Context, c *v3.Client, apply func(STM) error) (*v3.TxnResponse, error)

NewSTMReadCommitted is deprecated.

func NewSTMRepeatable

func NewSTMRepeatable(ctx context.Context, c *v3.Client, apply func(STM) error) (*v3.TxnResponse, error)

NewSTMRepeatable is deprecated.

func NewSTMSerializable

func NewSTMSerializable(ctx context.Context, c *v3.Client, apply func(STM) error) (*v3.TxnResponse, error)

NewSTMSerializable is deprecated.

func WithAbortContext

func WithAbortContext(ctx context.Context) stmOption

WithAbortContext specifies the context for permanently aborting the transaction.

func WithIsolation

func WithIsolation(lvl Isolation) stmOption

WithIsolation specifies the transaction isolation level.

func WithPrefetch

func WithPrefetch(keys ...string) stmOption

WithPrefetch is a hint to prefetch a list of keys before trying to apply. If an STM transaction will unconditionally fetch a set of keys, prefetching those keys will save the round-trip cost from requesting each key one by one with Get().

type Election

type Election struct {
    // contains filtered or unexported fields
}

func NewElection

func NewElection(s *Session, pfx string) *Election

NewElection returns a new election on a given key prefix.

func ResumeElection

func ResumeElection(s *Session, pfx string, leaderKey string, leaderRev int64) *Election

ResumeElection initializes an election with a known leader.

func (*Election) Campaign

func (e *Election) Campaign(ctx context.Context, val string) error

Campaign puts a value as eligible for the election. It blocks until it is elected, an error occurs, or the context is cancelled.

func (*Election) Header

func (m *Election) Header() *pb.ResponseHeader

Header is the response header from the last successful election proposal.

func (*Election) Key

func (e *Election) Key() string

Key returns the leader key if elected, empty string otherwise.

func (*Election) Leader

func (e *Election) Leader(ctx context.Context) (*v3.GetResponse, error)

Leader returns the leader value for the current election.

func (*Election) Observe

func (e *Election) Observe(ctx context.Context) <-chan v3.GetResponse

Observe returns a channel that reliably observes ordered leader proposals as GetResponse values on every current elected leader key. It will not necessarily fetch all historical leader updates, but will always post the most recent leader value.

The channel closes when the context is canceled or the underlying watcher is otherwise disrupted.

func (*Election) Proclaim

func (e *Election) Proclaim(ctx context.Context, val string) error

Proclaim lets the leader announce a new value without another election.

func (*Election) Resign

func (e *Election) Resign(ctx context.Context) (err error)

Resign lets a leader start a new election.

func (*Election) Rev

func (e *Election) Rev() int64

Rev returns the leader key's creation revision, if elected.

type Isolation

Isolation is an enumeration of transactional isolation levels which describes how transactions should interfere and conflict.

type Isolation int
const (
    // SerializableSnapshot provides serializable isolation and also checks
    // for write conflicts.
    SerializableSnapshot Isolation = iota
    // Serializable reads within the same transactiona attempt return data
    // from the at the revision of the first read.
    Serializable
    // RepeatableReads reads within the same transaction attempt always
    // return the same data.
    RepeatableReads
    // ReadCommitted reads keys from any committed revision.
    ReadCommitted
)

type Mutex

Mutex implements the sync Locker interface with etcd

type Mutex struct {
    // contains filtered or unexported fields
}

func NewMutex

func NewMutex(s *Session, pfx string) *Mutex

func (*Mutex) Header

func (m *Mutex) Header() *pb.ResponseHeader

Header is the response header received from etcd on acquiring the lock.

func (*Mutex) IsOwner

func (m *Mutex) IsOwner() v3.Cmp

func (*Mutex) Key

func (m *Mutex) Key() string

func (*Mutex) Lock

func (m *Mutex) Lock(ctx context.Context) error

Lock locks the mutex with a cancelable context. If the context is canceled while trying to acquire the lock, the mutex tries to clean its stale lock entry.

func (*Mutex) Unlock

func (m *Mutex) Unlock(ctx context.Context) error

type STM

STM is an interface for software transactional memory.

type STM interface {
    // Get returns the value for a key and inserts the key in the txn's read set.
    // If Get fails, it aborts the transaction with an error, never returning.
    Get(key ...string) string
    // Put adds a value for a key to the write set.
    Put(key, val string, opts ...v3.OpOption)
    // Rev returns the revision of a key in the read set.
    Rev(key string) int64
    // Del deletes a key.
    Del(key string)
    // contains filtered or unexported methods
}

type Session

Session represents a lease kept alive for the lifetime of a client. Fault-tolerant applications may use sessions to reason about liveness.

type Session struct {
    // contains filtered or unexported fields
}

func NewSession

func NewSession(client *v3.Client, opts ...SessionOption) (*Session, error)

NewSession gets the leased session for a client.

func (*Session) Client

func (s *Session) Client() *v3.Client

Client is the etcd client that is attached to the session.

func (*Session) Close

func (s *Session) Close() error

Close orphans the session and revokes the session lease.

func (*Session) Done

func (s *Session) Done() <-chan struct{}

Done returns a channel that closes when the lease is orphaned, expires, or is otherwise no longer being refreshed.

func (*Session) Lease

func (s *Session) Lease() v3.LeaseID

Lease is the lease ID for keys bound to the session.

func (*Session) Orphan

func (s *Session) Orphan()

Orphan ends the refresh for the session lease. This is useful in case the state of the client connection is indeterminate (revoke would fail) or when transferring lease ownership.

type SessionOption

SessionOption configures Session.

type SessionOption func(*sessionOptions)

func WithContext

func WithContext(ctx context.Context) SessionOption

WithContext assigns a context to the session instead of defaulting to using the client context. This is useful for canceling NewSession and Close operations immediately without having to close the client. If the context is canceled before Close() completes, the session's lease will be abandoned and left to expire instead of being revoked.

func WithLease

func WithLease(leaseID v3.LeaseID) SessionOption

WithLease specifies the existing leaseID to be used for the session. This is useful in process restart scenario, for example, to reclaim leadership from an election prior to restart.

func WithTTL

func WithTTL(ttl int) SessionOption

WithTTL configures the session's TTL in seconds. If TTL is <= 0, the default 60 seconds TTL will be used.