window

Documentation

Overview

Package window provides a type for efficiently recording events as they occur over a given span of time. Events added to the window will remain until the time expires.

Example (Accumulator)

package main

import (
	"fmt"
	"time"

	"github.com/Backblaze/blazer/x/window"
)

type Accumulator struct {
	w *window.Window
}

func (a Accumulator) Add(s string) {
	a.w.Insert([]string{s})
}

func (a Accumulator) All() []string {
	v := a.w.Reduce()
	return v.([]string)
}

func NewAccum(size time.Duration) Accumulator {
	r := func(i, j interface{}) interface{} {
		a, ok := i.([]string)
		if !ok {
			a = nil
		}
		b, ok := j.([]string)
		if !ok {
			b = nil
		}
		for _, s := range b {
			a = append(a, s)
		}
		return a
	}
	return Accumulator{w: window.New(size, time.Second, r)}
}

func main() {
	a := NewAccum(time.Minute)
	a.Add("this")
	a.Add("is")
	a.Add("that")
	fmt.Printf("total: %v\n", a.All())
}

Output:

total: [this is that]

Example (Counter)

package main

import (
	"fmt"
	"time"

	"github.com/Backblaze/blazer/x/window"
)

type Counter struct {
	w *window.Window
}

func (c Counter) Add() {
	c.w.Insert(1)
}

func (c Counter) Count() int {
	v := c.w.Reduce()
	return v.(int)
}

func New(size time.Duration) Counter {
	r := func(i, j interface{}) interface{} {
		a, ok := i.(int)
		if !ok {
			a = 0
		}
		b, ok := j.(int)
		if !ok {
			b = 0
		}
		return a + b
	}
	return Counter{w: window.New(size, time.Second, r)}
}

func main() {
	c := New(time.Minute)
	c.Add()
	c.Add()
	c.Add()
	fmt.Printf("total: %d\n", c.Count())
}

Output:

total: 3

Index

• type Reducer
• type Window
  • func New(size, resolution time.Duration, r Reducer) *Window
  • func (w *Window) Insert(e interface{})
  • func (w *Window) Reduce() interface{}

Examples

• Package (Accumulator)
• Package (Counter)

Types

type Reducer

type Reducer func(i, j interface{}) interface{}

A Reducer should take two values from the window and combine them into a third value that will be stored in the window. The values i or j may be nil. The underlying types for both arguments and the output should be identical.

If the reducer is any kind of slice or list, then data usage will grow linearly with the number of events added to the window.

Reducer will be called on its own output: Reducer(Reducer(x, y), z).

type Window

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

A Window efficiently records events that have occurred over a span of time extending from some fixed interval ago to now. Events that pass beyond this horizon are discarded.

func New

func New(size, resolution time.Duration, r Reducer) *Window

New returns an initialized window for events over the given duration at the given resolution. Windows with tight resolution (i.e., small values for that argument) will be more accurate, at the cost of some memory.

A size of 0 means "forever"; old events will never be removed.

func (*Window) Insert

func (w *Window) Insert(e interface{})

Insert adds the given event.

func (*Window) Reduce

func (w *Window) Reduce() interface{}

Reduce runs the window's reducer over the valid values and returns the result.