shard

Documentation

Overview

Package shard provides sharded data types for the App Engine Datastore.

These data types are used by Ori to supply certain values (for instance, counters for rate limits).

Index

• Variables
• type Counter
  • func NewCounter(entity, name string, shardCount int) (*Counter, error)
  • func (c *Counter) Delete(ctx context.Context) error
  • func (c *Counter) Increment(ctx context.Context, delta int64) error
  • func (c *Counter) IncrementX(txCtx context.Context, delta int64) error
  • func (c *Counter) Keys(ctx context.Context) []*datastore.Key
  • func (c *Counter) Value(ctx context.Context) (count int64, err error)

Variables

var (
	// DefaultCount is the default number of shards for a counter.
	DefaultCount = 50

	// DefaultCounterEntity is the default entity name Ori uses to store counters in App Engine Datastore.
	DefaultCounterEntity = "OriCounter"
)

var (
	// ErrBadShardCount is returned by NewCounter when the supplied shard count is not usable.
	ErrBadShardCount = errors.New("Bad number of shards in NewCounter; min is 1, max 1000")
)

Types

type Counter

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

Counter represents a sharded counter stored in the App Engine Datastore and Memcache.

func NewCounter

func NewCounter(entity, name string, shardCount int) (*Counter, error)

NewCounter returns a new counter object. Counter is not safe for concurrent use by multiple goroutines, but you can create many Counters all pointing to the same counter name like so:

for i := 0; i < 100; i++ {
	go func() {
		ctr := shard.NewCounter("entityType", "foo", 100)
		ctr.Increment(ctx, 5)
	}()
}

If different shardCount values are specified for the same counter, the behavior is undefined.

shardCount must be between 1 and 1000, or else ErrBadShardCount is returned. If you can guarantee that shardCount will be between 1 and 1000 (e.g., because you're calling it with a literal value), you can safely ignore the error:

ctr, _ := shard.NewCounter("foo", 100) // 100 is between 1 and 1000, so we can ignore the error

func (*Counter) Delete

func (c *Counter) Delete(ctx context.Context) error

Delete removes all values for the counter from the datastore.

func (*Counter) Increment

func (c *Counter) Increment(ctx context.Context, delta int64) error

Increment adds delta to the counter. You can therefore decrement the counter by supplying a negative number.

You cannot call Increment inside a datastore transaction; for that, use IncrementX.

func (*Counter) IncrementX

func (c *Counter) IncrementX(txCtx context.Context, delta int64) error

IncrementX is the version of Increment you should call if you wish to increment a counter inside a transaction.

func (*Counter) Keys

func (c *Counter) Keys(ctx context.Context) []*datastore.Key

Keys returns the datastore keys for the counter.

func (*Counter) Value

func (c *Counter) Value(ctx context.Context) (count int64, err error)

Value returns the current count of the counter. Note that the value is eventually consistent, and that Value _cannot_ be called inside a datastore transaction.

If err is not nil, the value of count is undefined.