irange

Documentation

Index

• Variables
• func Len(R Range) int
• type Entry
• type ID
  • func (id ID) String() string
• type Info
• type Iterator
• type Metadata
• type Range
  • func Diff(R Range, S Range) Range
  • func Exclude(R Range, n int64) (Range, error)
  • func Include(R Range, n int64) Range
  • func Intersect(R Range, S Range) Range
  • func Interval(a int64, b int64) Range
  • func Join(R Range, S Range) Range
  • func Meet(R Range, S Range) Range
  • func Parse(s string) (Range, error)
  • func Union(R Range, S Range) Range
  • func (R Range) Contains(n int64) bool
  • func (R Range) Contents() []int64
  • func (R Range) Diff(S Range) Range
  • func (R Range) Exclude(n int64) (Range, error)
  • func (R Range) Include(n int64) Range
  • func (R Range) Intersect(S Range) Range
  • func (R Range) IsEmpty() bool
  • func (R Range) IsEqualTo(S Range) bool
  • func (R Range) Iterator() Iterator
  • func (R Range) IteratorWithStrategy(S Strategy) Iterator
  • func (R Range) Join(S Range) Range
  • func (R Range) Len() int
  • func (R Range) MarshalJSON() ([]byte, error)
  • func (R Range) Meet(S Range) Range
  • func (R Range) Next() (int64, Range, error)
  • func (R Range) NextWithStrategy(S Strategy) (int64, Range, error)
  • func (R Range) String() string
  • func (R Range) Union(S Range) Range
• type State
  • func (s State) String() string
• type Status
• type Storage
• type Strategy

Variables

var Empty = Range{[]*interval{}}

Empty is the empty range

Functions

func Len

func Len(R Range) int

Len returns the number of elements in R. Note that this is the length of R as a slice, not its metric length.

Types

type Entry

type Entry interface {
	ID() ID              // an ID that identifies the entry
	Value() int64        // the value of the entry
	Deadline() time.Time // the time at which the entry will go stale
	Failures() int       // the number of times this entry has failed
}

Entry holds metadata about an active entry in a range stored in a Range storage engine.

type ID

type ID ulid.ULID

ID uniquely identifies an active entry in a range.

var NilID ID = ID(ulid.Nil)

NilID is a zero value for ID. It represents an invalid entry.

func (ID) String

func (id ID) String() string

String returns a string representation of the ID.

type Info

type Info interface {
	Value() int64        // the value of this entry
	State() State        // the state of this entry
	AppName() string     // the application name provided by the client to which the entry was assigned, or the empty string if there is no such client
	Hostname() string    // the hostname provided by the client to which the entry was assigned, or the empty string if there is no such client
	Start() time.Time    // the time the entry was assigned to a client, or the zero time if there is no such client
	Deadline() time.Time // the time at which this entry will go stale, or the zero time if the entry has not been assigned to a client
	Failures() int       // the number of times this entry has failed
}

Info describes an entry in a range stored in a Range storage system.

type Iterator

type Iterator interface {
	io.Closer
	// Err returns the last error, if any, encountered during iteration. Err may be called after Close.
	Err() error
	// Next advances the iterator. Returns true on successful advance of the iterator; false otherwise. Next must be called before the first call to Value.
	Next() bool
	// Value returns the current value.
	Value() (int64, error)
}

Iterator is the interface satisfied by iterators built from Range objects.

type Metadata

type Metadata struct {
	AppName  string // a name that identifies the client
	Hostname string // the hostname of the client
}

Metadata holds user-provided metadata describing a client

type Range

type Range struct {
	S []*interval
}

Range represents a disjoint union of intervals of int64s, \bigcup_i [a_i, b_i]. We insist that each interval is non-empty.

func Diff

func Diff(R Range, S Range) Range

Diff returns the range of int64s that lie in R but not in S.

func Exclude

func Exclude(R Range, n int64) (Range, error)

Exclude returns the range constructed from R by removing n. Returns errors.ErrNotInRange if n does not lie in R. For a call that always succeeds, use Diff.

func Include

func Include(R Range, n int64) Range

Include returns the range constructed from R by including n.

func Intersect

func Intersect(R Range, S Range) Range

Intersect is a synonym for Meet.

func Interval

func Interval(a int64, b int64) Range

Interval returns a new range [a..b]

func Join

func Join(R Range, S Range) Range

Join returns that range of int64s that lie in either R or S.

func Meet

func Meet(R Range, S Range) Range

Meet returns the range of int64s that lie in both R and S.

func Parse

func Parse(s string) (Range, error)

Parse parses s and returns a range. s should be of the form "[A,B,...,C]" where each of A, B, ..., C are either integers that will fit into an int64 or substrings of the form E..F where E and F are integers that will fit into an int64.

func Union

func Union(R Range, S Range) Range

Union is a synonym for Join.

func (Range) Contains

func (R Range) Contains(n int64) bool

Contains returns true if and only if n lies in R.

func (Range) Contents

func (R Range) Contents() []int64

Contents returns the contents of R as a slice.

func (Range) Diff

func (R Range) Diff(S Range) Range

Diff returns the range of int64s that lie in R but not in S.

func (Range) Exclude

func (R Range) Exclude(n int64) (Range, error)

Exclude returns the range constructed from R by removing n. Returns errors.ErrNotInRange if n does not lie in R. For a call that always succeeds, use Diff.

func (Range) Include

func (R Range) Include(n int64) Range

Include returns the range constructed from R by including n.

func (Range) Intersect

func (R Range) Intersect(S Range) Range

Intersect is a synonym for Meet.

func (Range) IsEmpty

func (R Range) IsEmpty() bool

IsEmpty returns true if and only if R is empty.

func (Range) IsEqualTo

func (R Range) IsEqualTo(S Range) bool

IsEqualTo returns true if and only if R and S are equal.

func (Range) Iterator

func (R Range) Iterator() Iterator

Iterator returns an iterator with contents R. Iteration proceeds using the Compact strategy, that is, it works through short intervals first.

func (Range) IteratorWithStrategy

func (R Range) IteratorWithStrategy(S Strategy) Iterator

IteratorWithStrategy returns an iterator with contents R. Iteration proceeds using the strategy S.

func (Range) Join

func (R Range) Join(S Range) Range

Join returns that range of int64s that lie in either R or S.

func (Range) Len

func (R Range) Len() int

Len returns the number of elements in R. Note that this is the length of R as a slice, not its metric length.

func (Range) MarshalJSON

func (R Range) MarshalJSON() ([]byte, error)

MarshalJSON returns a JSON description of R.

func (Range) Meet

func (R Range) Meet(S Range) Range

Meet returns the range of int64s that lie in both R and S.

func (Range) Next

func (R Range) Next() (int64, Range, error)

Next returns the next element of R, chosen using the Compact strategy, and the remaining range.

func (Range) NextWithStrategy

func (R Range) NextWithStrategy(S Strategy) (int64, Range, error)

NextWithStrategy returns the next element of R, chosen using the strategy S, and the remaining range.

func (Range) String

func (R Range) String() string

String returns a string representation of R.

func (Range) Union

func (R Range) Union(S Range) Range

Union is a synonym for Join.

type State

type State uint8

State records the state of an entry in a range.

const (
	Uninitialised State = iota
	Pending
	Active
	Succeeded
	Failed
)

States of entries

func (State) String

func (s State) String() string

type Status

type Status interface {
	Pending() Range   // The pending entries
	Active() Range    // The active entries
	Succeeded() Range // The entries that succeeded
	Failed() Range    // The entries that failed
}

Status describes the status of a range

type Storage

type Storage interface {
	// Create creates a range r with given name. Entries have the given lifetime; they are retried at most maxRetries times on failure, and at most maxConcurrency entries can be active at the same time. If a range with that name already exists, Create returns errors.ErrRangeExists.
	Create(ctx context.Context, name string, r Range, lifetime time.Duration, maxRetries int, maxConcurrency int) error
	// Delete deletes the range with the given name
	Delete(ctx context.Context, name string) error
	// Next returns the next entry in the range with the given name, or errors.ErrEmpty if no such entry exists.  The caller identifies itself to the storage engine via m.
	Next(ctx context.Context, name string, m *Metadata) (Entry, error)
	// Success indicates that the entry with the given ID has succeeded.
	Success(context.Context, ID) error
	// Error indicates that the entry with the given ID has failed and should be retried.
	Error(context.Context, ID) error
	// Requeue indicates that the entry with the given ID should be requeued, without incrementing the number of failures.
	Requeue(context.Context, ID) error
	// Fatal indicates that the entry with the given ID has failed and should not be requeued.
	Fatal(context.Context, ID) error
	// List returns the names of all known ranges.
	List(ctx context.Context) ([]string, error)
	// Status returns the status of the range with the given name.
	Status(ctx context.Context, name string) (Status, error)
	// Info returns information about the given entry in the range with the given name.
	Info(ctx context.Context, name string, entry int64) (Info, error)
}

Storage is an interface satisfied by storage engines for Range objects. Ranges are stored by name, which must be nonempty and must not start or end with whitespace. Calls to Create, Delete, Next, Status, and Info with invalid names return errors.ErrInvalidName.

type Strategy

type Strategy uint8

Strategy represents a strategy for picking the next element of a Range

const (
	First   Strategy = iota // pick the first element of the range
	Last                    // pick the last element of the range
	Compact                 // pick an element from the shortest interval
	Uniform                 // pick a random element, with a uniform distribution
	Random                  // pick a random element, with a bias towards keeping intervals short
)

Strategies for picking the next element of a Range