runtimevar

Documentation

Overview

Package runtimevar provides an interface for reading runtime variables and ability to detect changes and get updates on those variables.

Example

package main

import (
	"context"
	"log"

	"gocloud.dev/runtimevar"
	"gocloud.dev/runtimevar/filevar"
)

type DBConfig struct {
	Host     string
	Port     string
	Username string
	Name     string
}

func initVariable() (*runtimevar.Variable, func()) {
	// Construct a runtimevar.Variable object.
	v, err := filevar.New("/etc/myapp/db.json", runtimevar.NewDecoder(&DBConfig{}, runtimevar.JSONDecode), nil)
	if err != nil {
		log.Fatal(err)
	}

	return v, func() {
		v.Close()
	}
}

func main() {
	v, cleanup := initVariable()
	defer cleanup()

	ctx := context.Background()
	// Call Watch to retrieve initial value before proceeding.
	snap, err := v.Watch(ctx)
	if err != nil {
		log.Fatalf("Error in retrieving initial variable: %v", err)
	}
	log.Printf("Value: %+v", snap.Value.(*DBConfig))

	// Get a Context with cancel func to stop the Watch call.
	ctx, cancel := context.WithCancel(ctx)
	defer cancel()

	// Have a separate goroutine that waits for changes.
	go func() {
		for ctx.Err() == nil {
			snap, err := v.Watch(ctx)
			if err != nil {
				// Handle errors.
				log.Printf("Error: %v", err)
				continue
			}
			// Use updated configuration accordingly.
			log.Printf("Value: %+v", snap.Value.(*DBConfig))
		}
	}()
}

Index

• Variables
• func GobDecode(data []byte, obj interface{}) error
• type Decode
• type Decoder
  • func NewDecoder(obj interface{}, fn Decode) *Decoder
  • func (d *Decoder) Decode(b []byte) (interface{}, error)
• type Snapshot
• type Variable
  • func New(w driver.Watcher) *Variable
  • func (c *Variable) Close() error
  • func (c *Variable) Watch(ctx context.Context) (Snapshot, error)

Examples

• Package

Variables

var (
	StringDecoder = &Decoder{
		Type: reflect.TypeOf(""),
		Func: stringDecode,
	}

	BytesDecoder = &Decoder{
		Type: reflect.TypeOf([]byte{}),
		Func: bytesDecode,
	}
)

Simple Decoder objects.

var (
	JSONDecode = json.Unmarshal
)

Decode functions.

Functions

func GobDecode

func GobDecode(data []byte, obj interface{}) error

GobDecode gob decodes bytes into given object.

Types

type Decode

type Decode func([]byte, interface{}) error

Decode is a function type for unmarshaling/decoding bytes into given object.

type Decoder

type Decoder struct {
	Type reflect.Type
	// Func is a Decode function.
	Func Decode
}

Decoder is a helper for decoding bytes into a particular Go type object. The Variable objects produced by a particular driver.Watcher should always contain the same type for Variable.Value field. A driver.Watcher can use/construct a Decoder object with an associated type (Type) and decoding function (Func) for decoding retrieved bytes into Variable.Value.

func NewDecoder

func NewDecoder(obj interface{}, fn Decode) *Decoder

NewDecoder constructs a Decoder for given object that uses the given Decode function.

func (*Decoder) Decode

func (d *Decoder) Decode(b []byte) (interface{}, error)

Decode decodes given bytes into an object of type Type using Func.

type Snapshot

type Snapshot struct {
	// Value is an object containing a runtime variable  The type of
	// this object is set by the driver and it should always be the same type for the same Variable
	// object. A driver implementation can provide the ability to configure the object type and a
	// decoding scheme where variables are stored as bytes in the backend service.  Clients
	// should not mutate this object as it can be accessed by multiple goroutines.
	Value interface{}

	// UpdateTime is the time when the last changed was detected.
	UpdateTime time.Time
}

Snapshot contains a variable and metadata about it.

type Variable

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

Variable provides the ability to read runtime variables with its blocking Watch method.

func New

func New(w driver.Watcher) *Variable

New constructs a Variable object given a driver.Watcher implementation.

func (*Variable) Close

func (c *Variable) Close() error

Close cleans up any resources used by the Variable object.

func (*Variable) Watch

func (c *Variable) Watch(ctx context.Context) (Snapshot, error)

Watch blocks until there are variable changes, the Context's Done channel closes or a new error occurs.

If the variable changes, the method returns a Snapshot object containing the updated value.

If method returns an error, the returned Snapshot object is a zero value and cannot be used.

The first call to this method should return the current variable unless there are errors in retrieving the value.

Users should not call this method from multiple goroutines as implementations may not guarantee safety in data access. It is typical to use only one goroutine calling this method in a loop.

To stop this function from blocking, caller can passed in Context object constructed via WithCancel and call the cancel function.