irange

Documentation

Index

• Constants
• func AreEqual(R Range, S Range) bool
• func Contains(R Range, n int64) bool
• func Contents(R Range) []int64
• func Len(R Range) int
• func Random(R Range) int64
• type Entry
• type ID
  • func (id ID) String() string
• type Info
• type Interval
  • func Span(R Range) Interval
  • func ToInterval(a int64, b int64) Interval
• 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 Join(R Range, S Range) Range
  • func Meet(R Range, S Range) Range
  • func Parse(s string) (Range, error)
  • func ToRange(S ...Interval) Range
• type State
  • func (s State) String() string
• type Status
• type Storage
• type Strategy
  • func (s Strategy) Iterator(R Range) Iterator
  • func (s Strategy) Next(R Range) (int64, Range, error)
  • func (s Strategy) String() string

Constants

const Empty = emptyInterval(0)

Empty is an empty interval.

Functions

func AreEqual

func AreEqual(R Range, S Range) bool

AreEqual returns true if and only if the ranges R and S are equal.

func Contains

func Contains(R Range, n int64) bool

Contains returns true if and only if the range contains n.

func Contents

func Contents(R Range) []int64

Contents returns the contents of the range as a slice.

func Len

func Len(R Range) int

Len returns the number of integers contained in the range.

func Random

func Random(R Range) int64

Random returns a random element from the range, with a uniform distribution. If the range is empty this always returns 0.

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

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

type Interval

type Interval interface {
	Range
	// Min returns the minimum value included in this interval. If the
	// interval is empty this always returns 0.
	Min() int64
	// Max returns the maximum value included in this interval. If the
	// interval is empty this always returns 0.
	Max() int64
}

Interval defines an interval [a,b] \cap \ZZ of integers.

func Span

func Span(R Range) Interval

Span returns the smallest interval containing the range.

func ToInterval

func ToInterval(a int64, b int64) Interval

ToInterval returns the interval [a,b]. If b < a then this interval will be empty.

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. This will panic if Next has not
	// been called or the iterator is closed.
	Value() int64
}

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 interface {
	// IsEmpty returns true if and only if the range is empty.
	IsEmpty() bool
	// Intervals returns a slice of intervals representing the range. Any
	// empty intervals will be removed, and any intervals that can be
	// combined into a single interval will be combined.
	Intervals() []Interval
}

Range defines a union of intervals \bigcup_i [a_i, b_i] \cap \ZZ of integers.

func Diff

func Diff(R Range, S Range) Range

Diff returns the range of elements that lie in the range R but not in S. That is, it returns the difference R \setminus S.

func Exclude

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

Exclude returns the range constructed from the range R by removing n. That is, on success it returns the difference R \setminus {n}. Returns errors.ErrNotInRange if n does not lie in R.

func Include

func Include(R Range, n int64) Range

Include returns the range constructed from the range R by including n. That is, it returns the union R \cup {n}.

func Join

func Join(R Range, S Range) Range

Join returns that range of elements that lie in either the range R or S. That is, it returns the union R \cup S.

func Meet

func Meet(R Range, S Range) Range

Meet returns the range of elements that lie in both ranges R and S. That is, it returns the intersection R \cap 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 ToRange

func ToRange(S ...Interval) Range

ToRange converts the given intervals to a Range.

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
	// RequeueActive requeues all active entries in the range with the
	// given name.
	RequeueActive(ctx context.Context, name string) error
	// RequeueSucceeded requeues all entries that have succeeded in the
	// range with the given name.
	RequeueSucceeded(ctx context.Context, name string) error
	// RequeueFailed requeues all failed entries in the range with the
	// given name.
	RequeueFailed(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
)

Strategies for picking the next element of a Range

func (Strategy) Iterator

func (s Strategy) Iterator(R Range) Iterator

Iterator returns an iterator for the range R. Iteration proceeds using the strategy s.

func (Strategy) Next

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

Next returns the next element of the range R, along with the remaining range.

func (Strategy) String

func (s Strategy) String() string

String returns a string description of the strategy.