consistent

Documentation

Overview

Package consistent implements an experimental interface for using B2 as a coordination primitive.

Index

• type Group
  • func NewGroup(bucket *b2.Bucket, name string) *Group
  • func (g *Group) List(ctx context.Context) ([]string, error)
  • func (g *Group) Mutex(ctx context.Context, name string) *Mutex
  • func (g *Group) NewReader(ctx context.Context, name string) (Reader, error)
  • func (g *Group) NewWriter(ctx context.Context, key, name string) (Writer, error)
  • func (g *Group) Operate(ctx context.Context, name string, f func([]byte) ([]byte, error)) error
  • func (g *Group) OperateJSON(ctx context.Context, name string, t interface{}, ...) error
  • func (g *Group) OperateStream(ctx context.Context, name string, f func(io.Reader) (io.Reader, error)) error
• type Mutex
  • func (m *Mutex) Lock()
  • func (m *Mutex) Unlock()
• type Reader
  • func (r Reader) Close() error
  • func (r Reader) Read(p []byte) (int, error)
• type Writer
  • func (w Writer) Close() error
  • func (w Writer) Write(p []byte) (int, error)

Types

type Group

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

Group represents a collection of B2 objects that can be modified in a consistent way. Objects in the same group contend with each other for updates, but there can only be so many (maximum of 10; fewer if there are other bucket attributes set) groups in a given bucket.

func NewGroup

func NewGroup(bucket *b2.Bucket, name string) *Group

NewGroup creates a new consistent Group for the given bucket.

func (*Group) List

func (g *Group) List(ctx context.Context) ([]string, error)

List returns a list of all the group objects.

func (*Group) Mutex

func (g *Group) Mutex(ctx context.Context, name string) *Mutex

Mutex returns a new mutex on the given group. Only one caller can hold the lock on a mutex with a given name, for a given group.

func (*Group) NewReader

func (g *Group) NewReader(ctx context.Context, name string) (Reader, error)

NewReader creates a Reader with the current version of the object, as well as that object's update key.

func (*Group) NewWriter

func (g *Group) NewWriter(ctx context.Context, key, name string) (Writer, error)

NewWriter creates a Writer and prepares it to be updated. The key argument should come from the Key field of a Reader; if Writer.Close() returns with no error, then the underlying group object was successfully updated from the data available from the Reader with no intervening writes. New objects can be created with an empty key.

func (*Group) Operate

func (g *Group) Operate(ctx context.Context, name string, f func([]byte) ([]byte, error)) error

Operate uses OperateStream to act on byte slices.

func (*Group) OperateJSON

func (g *Group) OperateJSON(ctx context.Context, name string, t interface{}, f func(interface{}) (interface{}, error)) error

OperateJSON is a convenience function for transforming JSON data in B2 in a consistent way. Callers should pass a function f which accepts a pointer to a struct of a given type and transforms it into another struct (ideally but not necessarily of the same type). Callers should also pass an example struct, t, or a pointer to it, that is the same type. t will not be altered. If there is no existing file, f will be called with an pointer to an empty struct of type t. Otherwise, it will be called with a pointer to a struct filled out with the given JSON.

func (*Group) OperateStream

func (g *Group) OperateStream(ctx context.Context, name string, f func(io.Reader) (io.Reader, error)) error

Operate calls f with the contents of the group object given by name, and updates that object with the output of f if f returns no error. Operate guarantees that no other callers have modified the contents of name in the meantime (as long as all other callers are using this package). It may call f any number of times and, as a result, the potential data transfer is unbounded. Callers should have f fail after a given number of attempts if this is unacceptable.

The io.Reader that f returns is guaranteed to be read until at least the first error. Callers must ensure that this is sufficient for the reader to clean up after itself.

type Mutex

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

A Mutex is a sync.Locker that is backed by data in B2.

func (*Mutex) Lock

func (m *Mutex) Lock()

Lock locks the mutex. If the mutex is already locked, lock will wait, polling at 1 second intervals, until it can acquire the lock.

func (*Mutex) Unlock

func (m *Mutex) Unlock()

Unlock unconditionally unlocks the mutex. This allows programs to clear stale locks.

type Reader

type Reader struct {
	Key string
	// contains filtered or unexported fields
}

Reader is an io.ReadCloser. Key must be passed to NewWriter.

func (Reader) Close

func (r Reader) Close() error

func (Reader) Read

func (r Reader) Read(p []byte) (int, error)

type Writer

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

Writer is an io.ReadCloser.

func (Writer) Close

func (w Writer) Close() error

Close writes any remaining data into B2 and updates the group to reflect the contents of the new object. If the group object has been modified, Close() will fail.

func (Writer) Write

func (w Writer) Write(p []byte) (int, error)

Write implements io.Write.