anchor

Documentation

Overview

Package anchor defines anchor.Store, an extension to bs.Store that indexes "anchors," which are constant lookup names for changing blobs.

Index

• Variables
• func Each(ctx context.Context, g Getter, f func(string, bs.Ref, time.Time) error) error
• func Expire(ctx context.Context, s Store, oldest time.Time, min int) error
• func Get(ctx context.Context, g Getter, name string, at time.Time) (bs.Ref, error)
• func Put(ctx context.Context, s Store, name string, ref bs.Ref, at time.Time) error
• func PutProto(ctx context.Context, s Store, m proto.Message) (bs.Ref, bool, error)
• func Sync(ctx context.Context, stores []Store) error
• type Anchor
  • func (*Anchor) Descriptor() ([]byte, []int)
  • func (x *Anchor) GetAt() *timestamp.Timestamp
  • func (x *Anchor) GetRef() []byte
  • func (*Anchor) ProtoMessage()
  • func (x *Anchor) ProtoReflect() protoreflect.Message
  • func (x *Anchor) Reset()
  • func (x *Anchor) String() string
• type Getter
• type Store
• type UpdateFunc

Variables

var (
	// ErrNoAnchorMap is the error produced by AnchorMapRef when no anchor map yet exists.
	ErrNoAnchorMap = errors.New("no anchor map")

	// ErrUpdateConflict is the error produced by UpdateAnchorMap when "optimistic locking" fails.
	ErrUpdateConflict = errors.New("update conflict")

	// ErrNotAnchorStore is an error that implementations should use
	// to indicate that a bs.Store is being used as an anchor.Store but isn't one.
	ErrNotAnchorStore = errors.New("not anchor store")
)

var File_anchor_proto protoreflect.FileDescriptor

Functions

func Each

func Each(ctx context.Context, g Getter, f func(string, bs.Ref, time.Time) error) error

Each iterates through all anchors in g in an indeterminate order, calling a callback for each one. If the callback returns an error, Each exits early with that error.

func Expire

func Expire(ctx context.Context, s Store, oldest time.Time, min int) error

Expire expires anchors older than oldest. However, it never shortens an anchor's history to fewer than min items.

func Get

func Get(ctx context.Context, g Getter, name string, at time.Time) (bs.Ref, error)

Get gets the latest ref for the anchor with the given name whose timestamp is not later than the given time. If no such anchor is found, this returns bs.ErrNotFound.

func Put

func Put(ctx context.Context, s Store, name string, ref bs.Ref, at time.Time) error

Put stores a new anchor with the given name, ref, and timestamp. If an anchor for the given name already exists with the same ref at the same time, this silently does nothing. TODO: accept "oldest" and "limit" options here (as in Expire)?

func PutProto

func PutProto(ctx context.Context, s Store, m proto.Message) (bs.Ref, bool, error)

PutProto does what bs.PutProto does, but additionally stores type info about the stored protobuf in a special entry in the anchor map.

The entry, which is at the anchor key protoTypesAnchorName, is a schema.Map mapping blob refs to schema.Sets full of types. Each type is the ref of a protobuf "descriptor."

func Sync

func Sync(ctx context.Context, stores []Store) error

Sync copies every store's anchors to every other store. Strategy: each store does a one-way copy to its immediate neighbor to the right (mod N). Then each store does a one-way copy to its second neighbor to the right (mod N). This repeats len(stores)-1 times, at which point all stores have all anchors.

Types

type Anchor

type Anchor struct {
	Ref []byte               `protobuf:"bytes,1,opt,name=ref,proto3" json:"ref,omitempty"`
	At  *timestamp.Timestamp `protobuf:"bytes,2,opt,name=at,proto3" json:"at,omitempty"`
	// contains filtered or unexported fields
}

Anchor is a timestamped ref.

func (*Anchor) Descriptor

func (*Anchor) Descriptor() ([]byte, []int)

Deprecated: Use Anchor.ProtoReflect.Descriptor instead.

func (*Anchor) GetAt

func (x *Anchor) GetAt() *timestamp.Timestamp

func (*Anchor) GetRef

func (x *Anchor) GetRef() []byte

func (*Anchor) ProtoMessage

func (*Anchor) ProtoMessage()

func (*Anchor) ProtoReflect

func (x *Anchor) ProtoReflect() protoreflect.Message

func (*Anchor) Reset

func (x *Anchor) Reset()

func (*Anchor) String

func (x *Anchor) String() string

type Getter

type Getter interface {
	bs.Getter

	// AnchorMapRef produces the ref of the Getter's anchor map.
	// If no anchor map yet exists, this must return ErrNoAnchorMap.
	AnchorMapRef(context.Context) (bs.Ref, error)
}

Getter is a bs.Getter that can additionally get anchors. See Store.

type Store

type Store interface {
	Getter
	bs.Store

	// UpdateAnchorMap is used to update the anchor map in the Store.
	// Implementations must call the given UpdateFunc with the ref of the current anchor map.
	// If no anchor map yet exists, this must be the zero Ref.
	// The callback will presumably perform updates on the map, returning its new ref.
	// The implementation should store this as the new anchor map ref.
	// However, concurrent callers may make conflicting updates to the anchor map.
	// Therefore implementations are encouraged to use "optimistic locking":
	// after the callback returns, check that the anchor map still lives at the original ref and,
	// if it does, perform the update,
	// and if it doesn't, then return ErrUpdateConflict
	// (because some other caller has updated the map in the meantime).
	UpdateAnchorMap(context.Context, UpdateFunc) error
}

Store is a bs.Store that can additionally store anchors. Anchors are in a schema.Map that lives in the store. The store tracks the anchor map's changing ref.

type UpdateFunc

type UpdateFunc = func(bs.Ref) (bs.Ref, error)

UpdateFunc is the type of the callback passed to UpdateAnchorMap.