storage

Documentation

Overview

Package storage defines etcd's stable storage.

Index

• Variables
• func NewStore(b backend.Backend, le lease.Lessor) *store
• func ReportEventReceived()
• type ConsistentIndexGetter
• type ConsistentWatchableKV
  • func New(b backend.Backend, le lease.Lessor, ig ConsistentIndexGetter) ConsistentWatchableKV
• type KV
• type WatchID
• type WatchResponse
• type WatchStream
• type Watchable
• type WatchableKV

Variables

var (
	ErrTxnIDMismatch = errors.New("storage: txn id mismatch")
	ErrCompacted     = errors.New("storage: required revision has been compacted")
	ErrFutureRev     = errors.New("storage: required revision is a future revision")
	ErrCanceled      = errors.New("storage: watcher is canceled")
)

var (
	ErrRevisionNotFound = errors.New("stroage: revision not found")
)

var (
	ErrWatcherNotExist = errors.New("storage: watcher does not exist")
)

Functions

func NewStore

func NewStore(b backend.Backend, le lease.Lessor) *store

NewStore returns a new store. It is useful to create a store inside storage pkg. It should only be used for testing externally.

func ReportEventReceived

func ReportEventReceived()

ReportEventReceived reports that an event is received. This function should be called when the external systems received an event from storage.Watcher.

Types

type ConsistentIndexGetter

type ConsistentIndexGetter interface {
	// ConsistentIndex returns the consistent index of current executing entry.
	ConsistentIndex() uint64
}

ConsistentIndexGetter is an interface that wraps the Get method. Consistent index is the offset of an entry in a consistent replicated log.

type ConsistentWatchableKV

type ConsistentWatchableKV interface {
	WatchableKV
}

ConsistentWatchableKV is a WatchableKV that understands the consistency algorithm and consistent index. If the consistent index of executing entry is not larger than the consistent index of ConsistentWatchableKV, all operations in this entry are skipped and return empty response.

func New

func New(b backend.Backend, le lease.Lessor, ig ConsistentIndexGetter) ConsistentWatchableKV

type KV

type KV interface {
	// Rev returns the current revision of the KV.
	Rev() int64

	// FirstRev returns the first revision of the KV.
	// After a compaction, the first revision increases to the compaction
	// revision.
	FirstRev() int64

	// Range gets the keys in the range at rangeRev.
	// The returned rev is the current revision of the KV when the operation is executed.
	// If rangeRev <=0, range gets the keys at currentRev.
	// If `end` is nil, the request returns the key.
	// If `end` is not nil and not empty, it gets the keys in range [key, range_end).
	// If `end` is not nil and empty, it gets the keys greater than or equal to key.
	// Limit limits the number of keys returned.
	// If the required rev is compacted, ErrCompacted will be returned.
	Range(key, end []byte, limit, rangeRev int64) (kvs []storagepb.KeyValue, rev int64, err error)

	// Put puts the given key, value into the store. Put also takes additional argument lease to
	// attach a lease to a key-value pair as meta-data. KV implementation does not validate the lease
	// id.
	// A put also increases the rev of the store, and generates one event in the event history.
	// The returned rev is the current revision of the KV when the operation is executed.
	Put(key, value []byte, lease lease.LeaseID) (rev int64)

	// DeleteRange deletes the given range from the store.
	// A deleteRange increases the rev of the store if any key in the range exists.
	// The number of key deleted will be returned.
	// The returned rev is the current revision of the KV when the operation is executed.
	// It also generates one event for each key delete in the event history.
	// if the `end` is nil, deleteRange deletes the key.
	// if the `end` is not nil, deleteRange deletes the keys in range [key, range_end).
	DeleteRange(key, end []byte) (n, rev int64)

	// TxnBegin begins a txn. Only Txn prefixed operation can be executed, others will be blocked
	// until txn ends. Only one on-going txn is allowed.
	// TxnBegin returns an int64 txn ID.
	// All txn prefixed operations with same txn ID will be done with the same rev.
	TxnBegin() int64
	// TxnEnd ends the on-going txn with txn ID. If the on-going txn ID is not matched, error is returned.
	TxnEnd(txnID int64) error
	// TxnRange returns the current revision of the KV when the operation is executed.
	TxnRange(txnID int64, key, end []byte, limit, rangeRev int64) (kvs []storagepb.KeyValue, rev int64, err error)
	TxnPut(txnID int64, key, value []byte, lease lease.LeaseID) (rev int64, err error)
	TxnDeleteRange(txnID int64, key, end []byte) (n, rev int64, err error)

	Compact(rev int64) error

	// Hash retrieves the hash of KV state.
	// This method is designed for consistency checking purpose.
	Hash() (uint32, error)

	// Commit commits txns into the underlying backend.
	Commit()

	// Restore restores the KV store from a backend.
	Restore(b backend.Backend) error
	Close() error
}

type WatchID

type WatchID int64

type WatchResponse

type WatchResponse struct {
	// WatchID is the WatchID of the watcher this response sent to.
	WatchID WatchID

	// Events contains all the events that needs to send.
	Events []storagepb.Event

	// Revision is the revision of the KV when the watchResponse is created.
	// For a normal response, the revision should be the same as the last
	// modified revision inside Events. For a delayed response to a unsynced
	// watcher, the revision is greater than the last modified revision
	// inside Events.
	Revision int64

	// CompactRevision is set when the watcher is cancelled due to compaction.
	CompactRevision int64
}

type WatchStream

type WatchStream interface {
	// Watch creates a watcher. The watcher watches the events happening or
	// happened on the given key or range [key, end) from the given startRev.
	//
	// The whole event history can be watched unless compacted.
	// If `startRev` <=0, watch observes events after currentRev.
	//
	// The returned `id` is the ID of this watcher. It appears as WatchID
	// in events that are sent to the created watcher through stream channel.
	//
	Watch(key, end []byte, startRev int64) WatchID

	// Chan returns a chan. All watch response will be sent to the returned chan.
	Chan() <-chan WatchResponse

	// RequestProgress requests the progress of the watcher with given ID. The response
	// will only be sent if the watcher is currently synced.
	// The responses will be sent through the WatchRespone Chan attached
	// with this stream to ensure correct ordering.
	// The responses contains no events. The revision in the response is the progress
	// of the watchers since the watcher is currently synced.
	RequestProgress(id WatchID)

	// Cancel cancels a watcher by giving its ID. If watcher does not exist, an error will be
	// returned.
	Cancel(id WatchID) error

	// Close closes Chan and release all related resources.
	Close()

	// Rev returns the current revision of the KV the stream watches on.
	Rev() int64
}

type Watchable

type Watchable interface {
	// NewWatchStream returns a WatchStream that can be used to
	// watch events happened or happening on the KV.
	NewWatchStream() WatchStream
}

Watchable is the interface that wraps the NewWatchStream function.

type WatchableKV

type WatchableKV interface {
	KV
	Watchable
}

WatchableKV is a KV that can be watched.