Documentation
¶
Overview ¶
relation implements persistent local storage of a unit's relation state, and translation of relation changes into hooks that need to be run.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewRelationsResolver ¶
NewRelationsResolver returns a new Resolver that handles differences in relation state.
Types ¶
type Relationer ¶
type Relationer struct {
// contains filtered or unexported fields
}
Relationer manages a unit's presence in a relation.
func NewRelationer ¶
func NewRelationer(ru *apiuniter.RelationUnit, dir *StateDir) *Relationer
NewRelationer creates a new Relationer. The unit will not join the relation until explicitly requested.
func (*Relationer) CommitHook ¶
func (r *Relationer) CommitHook(hi hook.Info) error
CommitHook persists the fact of the supplied hook's completion.
func (*Relationer) ContextInfo ¶
func (r *Relationer) ContextInfo() *context.RelationInfo
ContextInfo returns a represention of the Relationer's current state.
func (*Relationer) IsImplicit ¶
func (r *Relationer) IsImplicit() bool
IsImplicit returns whether the local relation endpoint is implicit. Implicit relations do not run hooks.
func (*Relationer) Join ¶
func (r *Relationer) Join() error
Join initializes local state and causes the unit to enter its relation scope, allowing its counterpart units to detect its presence and settings changes. Local state directory is not created until needed.
func (*Relationer) PrepareHook ¶
func (r *Relationer) PrepareHook(hi hook.Info) (hookName string, err error)
PrepareHook checks that the relation is in a state such that it makes sense to execute the supplied hook, and ensures that the relation context contains the latest relation state as communicated in the hook.Info. It returns the name of the hook that must be run.
func (*Relationer) SetDying ¶
func (r *Relationer) SetDying() error
SetDying informs the relationer that the unit is departing the relation, and that the only hooks it should send henceforth are -departed hooks, until the relation is empty, followed by a -broken hook.
type Relations ¶
type Relations interface {
// Name returns the name of the relation with the supplied id, or an error
// if the relation is unknown.
Name(id int) (string, error)
// PrepareHook returns the name of the supplied relation hook, or an error
// if the hook is unknown or invalid given current state.
PrepareHook(hookInfo hook.Info) (string, error)
// CommitHook persists the state change encoded in the supplied relation
// hook, or returns an error if the hook is unknown or invalid given
// current relation state.
CommitHook(hookInfo hook.Info) error
// GetInfo returns information about current relation state.
GetInfo() map[int]*context.RelationInfo
// NextHook returns details on the next hook to execute, based on the local
// and remote states.
NextHook(resolver.LocalState, remotestate.Snapshot) (hook.Info, error)
}
Relations exists to encapsulate relation state and operations behind an interface for the benefit of future refactoring.
type State ¶
type State struct {
// RelationId identifies the relation.
RelationId int
// Members is a map from unit name to the last change version
// for which a hook.Info was delivered on the output channel.
Members map[string]int64
// ChangedPending indicates that a "relation-changed" hook for the given
// unit name must be the first hook.Info to be sent to the output channel.
ChangedPending string
}
State describes the state of a relation.
func (*State) Validate ¶
Validate returns an error if the supplied hook.Info does not represent a valid change to the relation state. Hooks must always be validated against the current state before they are run, to ensure that the system meets its guarantees about hook execution order.
type StateDir ¶
type StateDir struct {
// contains filtered or unexported fields
}
StateDir is a filesystem-backed representation of the state of a relation. Concurrent modifications to the underlying state directory will have undefined consequences.
func ReadStateDir ¶
ReadStateDir loads a StateDir from the subdirectory of dirPath named for the supplied RelationId. If the directory does not exist, no error is returned,
func (*StateDir) Ensure ¶
Ensure creates the directory if it does not already exist.
func (*StateDir) Remove ¶
Remove removes the directory if it exists and is empty.
func (*StateDir) State ¶
State returns the current state of the relation.
func (*StateDir) Write ¶
Write atomically writes to disk the relation state change in hi. It must be called after the respective hook was executed successfully. Write doesn't validate hi but guarantees that successive writes of the same hi are idempotent.
Source Files
¶
- relationer.go
- relations.go
- state.go