state

package
v0.0.0-...-b918686 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 19, 2016 License: GPL-3.0 Imports: 12 Imported by: 0

Documentation

Overview

Package state implements the representation of system state.

Index

Constants

View Source 
const (
	// Messages logged in tasks are guaranteed to use the time formatted
	// per RFC3339 plus the following strings as a prefix, so these may
	// be handled programatically and parsed or stripped for presentation.
	LogInfo  = "INFO"
	LogError = "ERROR"
)

Variables

View Source 
var ErrNoState = errors.New("no state entry for key")

ErrNoState represents the case of no state entry for a given key.

Functions

func MockTime 

func MockTime(now time.Time) (restore func())

Types

type Backend 

type Backend interface {
	Checkpoint(data []byte) error
	EnsureBefore(d time.Duration)
	// TODO: take flags to ask for reboot vs restart?
	RequestRestart()
}

A Backend is used by State to checkpoint on every unlock operation and to mediate requests to ensure the state sooner or request restarts.

type Change 

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

Change represents a tracked modification to the system state.

The Change provides both the justification for individual tasks to be performed and the grouping of them.

As an example, if an administrator requests an interface connection, multiple hooks might be individually run to accomplish the task. The Change summary would reflect the request for an interface connection, while the individual Task values would track the running of the hooks themselves.

func (*Change) Abort 

func (c *Change) Abort()

Abort flags the change for cancellation, whether in progress or not. Cancellation will proceed at the next ensure pass.

func (*Change) AddAll 

func (c *Change) AddAll(ts *TaskSet)

AddAll registers all tasks in the set as required for the state change to be accomplished.

func (*Change) AddTask 

func (c *Change) AddTask(t *Task)

AddTask registers a task as required for the state change to be accomplished.

func (*Change) Err 

func (c *Change) Err() error

Err returns an error value based on errors that were logged for tasks registered in this change, or nil if the change is not in ErrorStatus.

func (*Change) Get 

func (c *Change) Get(key string, value interface{}) error

Get unmarshals the stored value associated with the provided key into the value parameter.

func (*Change) ID 

func (c *Change) ID() string

ID returns the individual random key for the change.

func (*Change) Kind 

func (c *Change) Kind() string

Kind returns the nature of the change for managers to know how to handle it.

func (*Change) MarshalJSON 

func (c *Change) MarshalJSON() ([]byte, error)

MarshalJSON makes Change a json.Marshaller

func (*Change) Ready 

func (c *Change) Ready() <-chan struct{}

Ready returns a channel that is closed the first time the change becomes ready.

func (*Change) ReadyTime 

func (c *Change) ReadyTime() time.Time

ReadyTime returns the time when the change became ready.

func (*Change) Set 

func (c *Change) Set(key string, value interface{})

Set associates value with key for future consulting by managers. The provided value must properly marshal and unmarshal with encoding/json.

func (*Change) SetStatus 

func (c *Change) SetStatus(s Status)

SetStatus sets the change status, overriding the default behavior (see Status method).

func (*Change) SpawnTime 

func (c *Change) SpawnTime() time.Time

SpawnTime returns the time when the change was created.

func (*Change) State 

func (c *Change) State() *State

State returns the system State

func (*Change) Status 

func (c *Change) Status() Status

Status returns the current status of the change. If the status was not explicitly set the result is derived from the status of the individual tasks related to the change, according to the following decision sequence:

  • With at least one task in DoStatus, return DoStatus
  • With at least one task in ErrorStatus, return ErrorStatus
  • Otherwise, return DoneStatus

func (*Change) Summary 

func (c *Change) Summary() string

Summary returns a summary describing what the change is about.

func (*Change) Tasks 

func (c *Change) Tasks() []*Task

Tasks returns all the tasks this state change depends on.

func (*Change) UnmarshalJSON 

func (c *Change) UnmarshalJSON(data []byte) error

UnmarshalJSON makes Change a json.Unmarshaller

type HandlerFunc 

type HandlerFunc func(task *Task, tomb *tomb.Tomb) error

HandlerFunc is the type of function for the handlers

type Retry 

type Retry struct {
	After time.Duration
}

Retry is returned from a handler to signal that is ok to rerun the task at a later point. It's to be used also when a task goroutine is asked to stop through its tomb. After can be used to indicate how much to postpone the retry, 0 (the default) means at the next ensure pass and is what should be used if stopped through its tomb.

func (*Retry) Error 

func (r *Retry) Error() string

type State 

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

State represents an evolving system state that persists across restarts.

The State is concurrency-safe, and all reads and writes to it must be performed with the state locked. It's a runtime error (panic) to perform operations without it.

The state is persisted on every unlock operation via the StateBackend it was initialized with.

func New 

func New(backend Backend) *State

New returns a new empty state.

func ReadState 

func ReadState(backend Backend, r io.Reader) (*State, error)

ReadState returns the state deserialized from r.

func (*State) Cache 

func (s *State) Cache(key, value interface{})

Cache associates value with key for future consulting by managers. The cached value is not persisted.

func (*State) Cached 

func (s *State) Cached(key interface{}) interface{}

Cached returns the cached value associated with the provided key. It returns nil if there is no entry for key.

func (*State) Change 

func (s *State) Change(id string) *Change

Change returns the change for the given ID.

func (*State) Changes 

func (s *State) Changes() []*Change

Changes returns all changes currently known to the state.

func (*State) EnsureBefore 

func (s *State) EnsureBefore(d time.Duration)

EnsureBefore asks for an ensure pass to happen sooner within duration from now.

func (*State) Get 

func (s *State) Get(key string, value interface{}) error

Get unmarshals the stored value associated with the provided key into the value parameter. It returns ErrNoState if there is no entry for key.

func (*State) Lock 

func (s *State) Lock()

Lock acquires the state lock.

func (*State) MarshalJSON 

func (s *State) MarshalJSON() ([]byte, error)

MarshalJSON makes State a json.Marshaller

func (*State) Modified 

func (s *State) Modified() bool

Modified returns whether the state was modified since the last checkpoint.

func (*State) NewChange 

func (s *State) NewChange(kind, summary string) *Change

NewChange adds a new change to the state.

func (*State) NewTask 

func (s *State) NewTask(kind, summary string) *Task

NewTask creates a new task. It usually will be registered with a Change using AddTask or through a TaskSet.

func (*State) NumTask 

func (s *State) NumTask() int

NumTask returns the number of tasks that currently exist in the state (both linked or not yet linked to changes), useful for sanity checking.

func (*State) Prune 

func (s *State) Prune(pruneWait, abortWait time.Duration)

Prune removes changes that became ready for more than pruneWait and aborts tasks spawned for more than abortWait. It also removes tasks unlinked to changes after pruneWait.

func (*State) RequestRestart 

func (s *State) RequestRestart()

RequestRestart asks for a restart of the managing process.

func (*State) Set 

func (s *State) Set(key string, value interface{})

Set associates value with key for future consulting by managers. The provided value must properly marshal and unmarshal with encoding/json.

func (*State) Task 

func (s *State) Task(id string) *Task

Task returns the task for the given ID if the task has been linked to a change.

func (*State) Tasks 

func (s *State) Tasks() []*Task

Tasks returns all tasks currently known to the state and linked to changes.

func (*State) Unlock 

func (s *State) Unlock()

Unlock releases the state lock and checkpoints the state. It does not return until the state is correctly checkpointed. After too many unsuccessful checkpoint attempts, it panics.

func (*State) UnmarshalJSON 

func (s *State) UnmarshalJSON(data []byte) error

UnmarshalJSON makes State a json.Unmarshaller

type Status 

type Status int

Status is used for status values for changes and tasks. 

const (
	// DefaultStatus is the standard computed status for a change or task.
	// For tasks it's always mapped to DoStatus, and for change its mapped
	// to an aggregation of its tasks' statuses. See Change.Status for details.
	DefaultStatus Status = 0

	// HoldStatus means the task should not run, perhaps as a consequence of an error on another task.
	HoldStatus Status = 1

	// DoStatus means the change or task is ready to start.
	DoStatus Status = 2

	// DoingStatus means the change or task is running or an attempt was made to run it.
	DoingStatus Status = 3

	// DoneStatus means the change or task was accomplished successfully.
	DoneStatus Status = 4

	// AbortStatus means the task should stop doing its activities and then undo.
	AbortStatus Status = 5

	// UndoStatus means the change or task should be undone, probably due to an error elsewhere.
	UndoStatus Status = 6

	// UndoingStatus means the change or task is being undone or an attempt was made to undo it.
	UndoingStatus Status = 7

	// UndoneStatus means a task was first done and then undone after an error elsewhere.
	// Changes go directly into the error status instead of being marked as undone.
	UndoneStatus Status = 8

	// ErrorStatus means the change or task has errored out while running or being undone.
	ErrorStatus Status = 9
)

Admitted status values for changes and tasks.

func (Status) Ready 

func (s Status) Ready() bool

Ready returns whether a task or change with this status needs further work or has completed its attempt to perform the current goal.

func (Status) String 

func (s Status) String() string

type Task 

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

Task represents an individual operation to be performed for accomplishing one or more state changes.

See Change for more details.

func (*Task) At 

func (t *Task) At(when time.Time)

At schedules the task, if it's not ready, to happen no earlier than when, if when is the zero time any previous special scheduling is supressed.

func (*Task) AtTime 

func (t *Task) AtTime() time.Time

AtTime returns the time at which the task is scheduled to run. A zero time means no special schedule, i.e. run as soon as prerequisites are met.

func (*Task) Change 

func (t *Task) Change() *Change

Change returns the change the task is registered with.

func (*Task) Errorf 

func (t *Task) Errorf(format string, args ...interface{})

Errorf logs error information about the progress of the task.

func (*Task) Get 

func (t *Task) Get(key string, value interface{}) error

Get unmarshals the stored value associated with the provided key into the value parameter.

func (*Task) HaltTasks 

func (t *Task) HaltTasks() []*Task

HaltTasks returns the list of tasks registered to wait for t.

func (*Task) ID 

func (t *Task) ID() string

ID returns the individual random key for this task.

func (*Task) Kind 

func (t *Task) Kind() string

Kind returns the nature of this task for managers to know how to handle it.

func (*Task) Log 

func (t *Task) Log() []string

Log returns the most recent messages logged into the task.

Only the most recent entries logged are returned, potentially with different behavior for different task statuses. How many entries are returned is an implementation detail and may change over time.

Messages are prefixed with one of the known message kinds. See details about LogInfo and LogError.

The returned slice should not be read from without the state lock held, and should not be written to.

func (*Task) Logf 

func (t *Task) Logf(format string, args ...interface{})

Logf logs information about the progress of the task.

func (*Task) MarshalJSON 

func (t *Task) MarshalJSON() ([]byte, error)

MarshalJSON makes Task a json.Marshaller

func (*Task) Progress 

func (t *Task) Progress() (done, total int)

Progress returns the current progress for the task. If progress is not explicitly set, it returns (0, 1) if the status is DoStatus and (1, 1) otherwise.

func (*Task) ReadyTime 

func (t *Task) ReadyTime() time.Time

ReadyTime returns the time when the change became ready.

func (*Task) Set 

func (t *Task) Set(key string, value interface{})

Set associates value with key for future consulting by managers. The provided value must properly marshal and unmarshal with encoding/json.

func (*Task) SetProgress 

func (t *Task) SetProgress(done, total int)

SetProgress sets the task progress to cur out of total steps.

func (*Task) SetStatus 

func (t *Task) SetStatus(new Status)

SetStatus sets the task status, overriding the default behavior (see Status method).

func (*Task) SpawnTime 

func (t *Task) SpawnTime() time.Time

SpawnTime returns the time when the change was created.

func (*Task) State 

func (t *Task) State() *State

State returns the system State

func (*Task) Status 

func (t *Task) Status() Status

Status returns the current task status.

func (*Task) Summary 

func (t *Task) Summary() string

Summary returns a summary describing what the task is about.

func (*Task) UnmarshalJSON 

func (t *Task) UnmarshalJSON(data []byte) error

UnmarshalJSON makes Task a json.Unmarshaller

func (*Task) WaitAll 

func (t *Task) WaitAll(ts *TaskSet)

WaitAll registers all the tasks in the set as a requirement for t to make progress.

func (*Task) WaitFor 

func (t *Task) WaitFor(another *Task)

WaitFor registers another task as a requirement for t to make progress.

func (*Task) WaitTasks 

func (t *Task) WaitTasks() []*Task

WaitTasks returns the list of tasks registered for t to wait for.

type TaskRunner 

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

TaskRunner controls the running of goroutines to execute known task kinds.

func NewTaskRunner 

func NewTaskRunner(s *State) *TaskRunner

NewTaskRunner creates a new TaskRunner

func (*TaskRunner) AddHandler 

func (r *TaskRunner) AddHandler(kind string, do, undo HandlerFunc)

AddHandler registers the functions to concurrently call for doing and undoing tasks of the given kind. The undo handler may be nil.

func (*TaskRunner) Ensure 

func (r *TaskRunner) Ensure()

Ensure starts new goroutines for all known tasks with no pending dependencies. Note that Ensure will lock the state.

func (*TaskRunner) Stop 

func (r *TaskRunner) Stop()

Stop kills all concurrent activities and returns after that's done.

func (*TaskRunner) Wait 

func (r *TaskRunner) Wait()

Wait waits for all concurrent activities and returns after that's done.

type TaskSet 

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

A TaskSet holds a set of tasks.

func NewTaskSet 

func NewTaskSet(tasks ...*Task) *TaskSet

NewTaskSet returns a new TaskSet comprising the given tasks.

func (*TaskSet) AddAll 

func (ts *TaskSet) AddAll(anotherTs *TaskSet)

AddAll adds all the tasks in the argument set to the target set ts.

func (*TaskSet) AddTask 

func (ts *TaskSet) AddTask(task *Task)

AddTask adds the the task to the task set.

func (TaskSet) Tasks 

func (ts TaskSet) Tasks() []*Task

Tasks returns the tasks in the task set.

func (*TaskSet) WaitAll 

func (ts *TaskSet) WaitAll(anotherTs *TaskSet)

WaitAll registers all the tasks in the argument set as requirements for ts the target set to make progress.

func (TaskSet) WaitFor 

func (ts TaskSet) WaitFor(another *Task)

WaitFor registers a task as a requirement for the tasks in the set to make progress.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.