state

Documentation

Overview

Package state provides interfaces to work with swarm cluster state.

The primary interface is Store, which abstracts storage of this cluster state. Store exposes a transactional interface for both reads and writes. To perform a read transaction, View accepts a callback function that it will invoke with a ReadTx object that gives it a consistent view of the state. Similarly, Update accepts a callback function that it will invoke with a Tx object that allows reads and writes to happen without interference from other transactions.

This is an example of making an update to a Store:

err := store.Update(func(tx state.Tx) {
	if err := tx.Nodes().Update(newNode); err != nil {
		return err
	}
	return nil
})
if err != nil {
	return fmt.Errorf("transaction failed: %v", err)
}

WatchableStore is a version of Store that exposes watch functionality. These expose a publish/subscribe queue where code can subscribe to changes of interest. This can be combined with the ViewAndWatch function to "fork" a store, by making a snapshot and then applying future changes to keep the copy in sync. This approach lets consumers of the data use their own data structures and implement their own concurrency strategies. It can lead to more efficient code because data consumers don't necessarily have to lock the main data store if they are maintaining their own copies of the state.

Index

• func Matcher(specifiers ...api.Event) events.MatcherFunc
• func NodeCheckState(n1, n2 *api.Node) bool
• func TaskCheckStateGreaterThan(t1, t2 *api.Task) bool
• func Watch(queue *watch.Queue, specifiers ...api.Event) (eventq chan events.Event, cancel func())
• type Change
• type EventCommit
  • func (e EventCommit) Matches(watchEvent events.Event) bool
• type Proposer

Functions

func Matcher

func Matcher(specifiers ...api.Event) events.MatcherFunc

Matcher returns an events.Matcher that Matches the specifiers with OR logic.

func NodeCheckState

func NodeCheckState(n1, n2 *api.Node) bool

NodeCheckState is a NodeCheckFunc for matching node state.

func TaskCheckStateGreaterThan

func TaskCheckStateGreaterThan(t1, t2 *api.Task) bool

TaskCheckStateGreaterThan is a TaskCheckFunc for checking task state.

func Watch

func Watch(queue *watch.Queue, specifiers ...api.Event) (eventq chan events.Event, cancel func())

Watch takes a variable number of events to match against. The subscriber will receive events that match any of the arguments passed to Watch.

Examples:

// subscribe to all events Watch(q)

// subscribe to all UpdateTask events Watch(q, EventUpdateTask{})

// subscribe to all task-related events Watch(q, EventUpdateTask{}, EventCreateTask{}, EventDeleteTask{})

// subscribe to UpdateTask for node 123 Watch(q, EventUpdateTask{Task: &api.Task{NodeID: 123},

Checks: []TaskCheckFunc{TaskCheckNodeID}})

// subscribe to UpdateTask for node 123, as well as CreateTask // for node 123 that also has ServiceID set to "abc" Watch(q, EventUpdateTask{Task: &api.Task{NodeID: 123},

                Checks: []TaskCheckFunc{TaskCheckNodeID}},
EventCreateTask{Task: &api.Task{NodeID: 123, ServiceID: "abc"},
                Checks: []TaskCheckFunc{TaskCheckNodeID,
                                        func(t1, t2 *api.Task) bool {
                                                return t1.ServiceID == t2.ServiceID
                                        }}})

Types

type Change

type Change struct {
	StoreActions []api.StoreAction
	Version      api.Version
}

A Change includes a version number and a set of store actions from a particular log entry.

type EventCommit

type EventCommit struct {
	Version *api.Version
}

EventCommit delineates a transaction boundary.

func (EventCommit) Matches

func (e EventCommit) Matches(watchEvent events.Event) bool

Matches returns true if this event is a commit event.

type Proposer

type Proposer interface {
	// ProposeValue adds storeAction to the distributed log. If this
	// completes successfully, ProposeValue calls cb to commit the
	// proposed changes. The callback is necessary for the Proposer to make
	// sure that the changes are committed before it interacts further
	// with the store.
	ProposeValue(ctx context.Context, storeAction []api.StoreAction, cb func()) error
	// GetVersion returns the monotonic index of the most recent item in
	// the distributed log.
	GetVersion() *api.Version
	// ChangesBetween returns the changes starting after "from", up to and
	// including "to". If these changes are not available because the log
	// has been compacted, an error will be returned.
	ChangesBetween(from, to api.Version) ([]Change, error)
}

A Proposer can propose actions to a cluster.