Documentation
¶
Index ¶
- Constants
- Variables
- func EdgeCmpFn(e1, e2 pgraph.Edge) (bool, error)
- func RegisterResource(kind string, fn func() Res)
- func RegisteredResourcesNames() []string
- func Repr(kind, name string) string
- func ResCmp(r1, r2 Res) error
- func Stringer(res Res) string
- func Validate(res Res) error
- func VertexCmpFn(v1, v2 pgraph.Vertex) (bool, error)
- type AutoEdge
- type AutoEdgeMeta
- type AutoGroupMeta
- type AutoGrouper
- type BaseUID
- type CollectableRes
- type Edge
- type EdgeableRes
- type Error
- type Fs
- type GroupableRes
- type Init
- type InterruptableRes
- type KindedRes
- type MetaParams
- type MetaRes
- type NamedRes
- type RecvableRes
- type RefreshableRes
- type Res
- type ResUID
- type ResourceSlice
- type Send
- type SendableRes
- type World
- type YAMLRes
Constants ¶
const ( // ErrWatchExit represents an exit from the Watch loop via chan closure. ErrWatchExit = Error("watch exit") // ErrSignalExit represents an exit from the Watch loop via exit signal. ErrSignalExit = Error("signal exit") )
Variables ¶
var DefaultMetaParams = &MetaParams{ Noop: false, Retry: 0, Delay: 0, Poll: 0, Limit: rate.Inf, Burst: 0, }
DefaultMetaParams are the defaults that are used for undefined metaparams. Don't modify this variable. Use .Copy() if you'd like some for yourself.
Functions ¶
func EdgeCmpFn ¶
EdgeCmpFn returns if two edges are equivalent. It errors if they can't be compared because one is not an edge. This returns true if equal. TODO: shouldn't the first argument be an `error` instead?
func RegisterResource ¶
RegisterResource registers a new resource by providing a constructor function that returns a resource object ready to be unmarshalled from YAML.
func RegisteredResourcesNames ¶
func RegisteredResourcesNames() []string
RegisteredResourcesNames returns the kind of the registered resources.
func Repr ¶
Repr returns a representation of a resource from its kind and name. This is used as the definitive format so that it can be changed in one place.
func ResCmp ¶
ResCmp compares two resources by checking multiple aspects. This is the main entry point for running all the compare steps on two resource.
Types ¶
type AutoEdge ¶
type AutoEdge interface {
Next() []ResUID // call to get list of edges to add
Test([]bool) bool // call until false
}
The AutoEdge interface is used to implement the autoedges feature.
type AutoEdgeMeta ¶
type AutoEdgeMeta struct {
// Disabled specifies that automatic edges should be disabled for this
// resource.
Disabled bool
}
AutoEdgeMeta provides some parameters specific to automatic edges. TODO: currently this only supports disabling the feature per-resource, but in the future you could conceivably have some small pattern to control it better
func (*AutoEdgeMeta) Cmp ¶
func (obj *AutoEdgeMeta) Cmp(aem *AutoEdgeMeta) error
Cmp compares two AutoEdgeMeta structs and determines if they're equivalent.
type AutoGroupMeta ¶
type AutoGroupMeta struct {
// Disabled specifies that automatic grouping should be disabled for
// this resource.
Disabled bool
}
AutoGroupMeta provides some parameters specific to automatic grouping. TODO: currently this only supports disabling the feature per-resource, but in the future you could conceivably have some small pattern to control it better
func (*AutoGroupMeta) Cmp ¶
func (obj *AutoGroupMeta) Cmp(agm *AutoGroupMeta) error
Cmp compares two AutoGroupMeta structs and determines if they're equivalent.
type AutoGrouper ¶
type AutoGrouper interface {
// listed in the order these are typically called in...
Name() string // friendly identifier
Init(*pgraph.Graph) error // only call once
VertexNext() (pgraph.Vertex, pgraph.Vertex, error) // mostly algorithmic
VertexCmp(pgraph.Vertex, pgraph.Vertex) error // can we merge these ?
VertexMerge(pgraph.Vertex, pgraph.Vertex) (pgraph.Vertex, error) // vertex merge fn to use
EdgeMerge(pgraph.Edge, pgraph.Edge) pgraph.Edge // edge merge fn to use
VertexTest(bool) (bool, error) // call until false
}
AutoGrouper is the required interface to implement an autogrouping algorithm.
type BaseUID ¶
type BaseUID struct {
Name string // name and kind are the values of where this is coming from
Kind string
Reversed *bool // piggyback edge information here
}
The BaseUID struct is used to provide a unique resource identifier.
func (*BaseUID) IFF ¶
IFF looks at two UID's and if and only if they are equivalent, returns true. If they are not equivalent, it returns false. Most resources will want to override this method, since it does the important work of actually discerning if two resources are identical in function.
func (*BaseUID) IsReversed ¶
IsReversed is part of the ResUID interface, and true means this resource happens before the generator.
type CollectableRes ¶
type CollectableRes interface {
Res
CollectPattern(string) // XXX: temporary until Res collection is more advanced
}
CollectableRes is an interface for resources that support collection. It is currently temporary until a proper API for all resources is invented.
type Edge ¶
type Edge struct {
Name string
Notify bool // should we send a refresh notification along this edge?
// contains filtered or unexported fields
}
Edge is a struct that represents a graph's edge.
func (*Edge) SetRefresh ¶
SetRefresh sets the pending refresh status of this edge.
type EdgeableRes ¶
type EdgeableRes interface {
Res // implement everything in Res but add the additional requirements
// AutoEdgeMeta lets you get or set meta params for the automatic edges
// trait.
AutoEdgeMeta() *AutoEdgeMeta
// UIDs includes all params to make a unique identification of this
// object.
UIDs() []ResUID // most resources only return one
// AutoEdges returns a struct that implements the AutoEdge interface.
// This interface can be used to generate automatic edges to other
// resources.
AutoEdges() (AutoEdge, error)
}
EdgeableRes is the interface a resource must implement to support automatic edges. Both the vertices involved in an edge need to implement this for it to be able to work.
type Fs ¶
type Fs interface {
//fmt.Stringer // TODO: add this method?
afero.Fs // TODO: why doesn't this interface exist in the os pkg?
URI() string // returns the URI for this file system
//DirExists(path string) (bool, error)
//Exists(path string) (bool, error)
//FileContainsAnyBytes(filename string, subslices [][]byte) (bool, error)
//FileContainsBytes(filename string, subslice []byte) (bool, error)
//FullBaseFsPath(basePathFs *BasePathFs, relativePath string) string
//GetTempDir(subPath string) string
//IsDir(path string) (bool, error)
//IsEmpty(path string) (bool, error)
//NeuterAccents(s string) string
//ReadAll(r io.Reader) ([]byte, error) // not needed
ReadDir(dirname string) ([]os.FileInfo, error)
ReadFile(filename string) ([]byte, error)
//SafeWriteReader(path string, r io.Reader) (err error)
TempDir(dir, prefix string) (name string, err error)
TempFile(dir, prefix string) (f afero.File, err error) // slightly different from upstream
//UnicodeSanitize(s string) string
//Walk(root string, walkFn filepath.WalkFunc) error
WriteFile(filename string, data []byte, perm os.FileMode) error
}
Fs is an interface that represents this file system API that we support. TODO: this should be in the gapi package or elsewhere.
type GroupableRes ¶
type GroupableRes interface {
Res // implement everything in Res but add the additional requirements
// AutoGroupMeta lets you get or set meta params for the automatic
// grouping trait.
AutoGroupMeta() *AutoGroupMeta
// GroupCmp compares two resources and decides if they're suitable for
//grouping. This usually needs to be unique to your resource.
GroupCmp(res GroupableRes) error
// GroupRes groups resource argument (res) into self.
GroupRes(res GroupableRes) error
// IsGrouped determines if we are grouped.
IsGrouped() bool // am I grouped?
// SetGrouped sets a flag to tell if we are grouped.
SetGrouped(bool)
// GetGroup returns everyone grouped inside me.
GetGroup() []GroupableRes // return everyone grouped inside me
// SetGroup sets the grouped resources into me.
SetGroup([]GroupableRes)
}
GroupableRes is the interface a resource must implement to support automatic grouping. Default implementations for most of the methods declared in this interface can be obtained for your resource by anonymously adding the traits.Groupable struct to your resource implementation.
type Init ¶
type Init struct {
// Program is the name of the program.
Program string
// Hostname is the uuid for the host.
Hostname string
// Running must be called after your watches are all started and ready.
Running func() error
// Event sends an event notifying the engine of a possible state change.
Event func() error
// Events returns a channel that we must watch for messages from the
// engine. When it closes, this is a signal to shutdown.
Events chan event.Kind
// Read processes messages that come in from the Events channel. It is a
// helper method that knows how to handle the pause mechanism correctly.
Read func(event.Kind) error
// Dirty marks the resource state as dirty. This signals to the engine
// that CheckApply will have some work to do in order to converge it.
Dirty func()
// Refresh returns whether the resource received a notification. This
// flag can be used to tell a svc to reload, or to perform some state
// change that wouldn't otherwise be noticed by inspection alone. You
// must implement the Refreshable trait for this to work.
Refresh func() bool
// Send exposes some variables you wish to send via the Send/Recv
// mechanism. You must implement the Sendable trait for this to work.
Send func(interface{}) error
// Recv provides a map of variables which were sent to this resource via
// the Send/Recv mechanism. You must implement the Recvable trait for
// this to work.
Recv func() map[string]*Send
// World provides a connection to the outside world. This is most often
// used for communicating with the distributed database.
World World
// VarDir is a facility for local storage. It is used to return a path
// to a directory which may be used for temporary storage. It should be
// cleaned up on resource Close if the resource would like to delete the
// contents. The resource should not assume that the initial directory
// is empty, and it should be cleaned on Init if that is a requirement.
VarDir func(string) (string, error)
// Debug signals whether we are running in debugging mode. In this case,
// we might want to log additional messages.
Debug bool
// Logf is a logging facility which will correctly namespace any
// messages which you wish to pass on. You should use this instead of
// the log package directly for production quality resources.
Logf func(format string, v ...interface{})
}
Init is the structure of values and references which is passed into all resources on initialization. None of these are available in Validate, or before Init runs.
type InterruptableRes ¶
type InterruptableRes interface {
Res
// Ask the resource to shutdown quickly. This can be called at any point
// in the resource lifecycle after Init. Close will still be called. It
// will only get called after an exit or pause request has been made. It
// is designed to unblock any long running operation that is occurring
// in the CheckApply portion of the life cycle. If the resource has
// already exited, running this method should not block. (That is to say
// that you should not expect CheckApply or Watch to be able to alive
// and able to read from a channel to satisfy your request.) It is best
// to probably have this close a channel to multicast that signal around
// to anyone who can detect it in a select. If you are in a situation
// which cannot interrupt, then you can return an error.
// FIXME: implement, and check the above description is what we expect!
Interrupt() error
}
InterruptableRes is an interface that adds interrupt functionality to resources. If the resource implements this interface, the engine will call the Interrupt method to shutdown the resource quickly. Running this method may leave the resource in a partial state, however this may be desired if you want a faster exit or if you'd prefer a partial state over letting the resource complete in a situation where you made an error and you wish to exit quickly to avoid data loss. It is usually triggered after multiple ^C signals.
type KindedRes ¶
type KindedRes interface {
// Kind returns a string representing the kind of resource this is.
Kind() string
// SetKind sets the resource kind and should only be called by the
// engine.
SetKind(string)
}
KindedRes is an interface that is required for a resource to have a kind.
type MetaParams ¶
type MetaParams struct {
// Noop specifies that no changes should be made by the resource. It
// relies on the individual resource implementation, and can't protect
// you from a poorly or maliciously implemented resource.
Noop bool `yaml:"noop"`
// Retry is the number of times to retry on error. Use -1 for infinite.
Retry int16 `yaml:"retry"`
// Delay is the number of milliseconds to wait between retries.
Delay uint64 `yaml:"delay"`
// Poll is the number of seconds between poll intervals. Use 0 to Watch.
Poll uint32 `yaml:"poll"`
// Limit is the number of events per second to allow through.
Limit rate.Limit `yaml:"limit"`
// Burst is the number of events to allow in a burst.
Burst int `yaml:"burst"`
// Sema is a list of semaphore ids in the form `id` or `id:count`. If
// you don't specify a count, then 1 is assumed. The sema of `foo` which
// has a count equal to 1, is different from a sema named `foo:1` which
// also has a count equal to 1, but is a different semaphore.
Sema []string `yaml:"sema"`
}
MetaParams provides some meta parameters that apply to every resource.
func (*MetaParams) Cmp ¶
func (obj *MetaParams) Cmp(meta *MetaParams) error
Cmp compares two AutoGroupMeta structs and determines if they're equivalent.
func (*MetaParams) Copy ¶
func (obj *MetaParams) Copy() *MetaParams
Copy copies this struct and returns a new one.
func (*MetaParams) UnmarshalYAML ¶
func (obj *MetaParams) UnmarshalYAML(unmarshal func(interface{}) error) error
UnmarshalYAML is the custom unmarshal handler for the MetaParams struct. It is primarily useful for setting the defaults. TODO: this is untested
func (*MetaParams) Validate ¶
func (obj *MetaParams) Validate() error
Validate runs some validation on the meta params.
type MetaRes ¶
type MetaRes interface {
// MetaParams lets you get or set meta params for the resource.
MetaParams() *MetaParams
}
MetaRes is the interface a resource must implement to support meta params. All resources must implement this.
type RecvableRes ¶
type RecvableRes interface {
Res
// SetRecv stores the map of sendable data which should arrive here. It
// is called by the GAPI when building the resource.
SetRecv(recv map[string]*Send)
// Recv is used by the resource to get information on changes. This data
// can be used to invalidate caches, restart watches, or it can be
// ignored entirely.
Recv() map[string]*Send
}
RecvableRes is the interface a resource must implement to support receiving on public parameters. The resource only has to include the correct trait for this interface to be fulfilled, as no additional methods need to be added. To get information about received changes, you can use the Recv method from the input API that comes in via Init.
type RefreshableRes ¶
type RefreshableRes interface {
Res // implement everything in Res but add the additional requirements
// Refresh returns the refresh notification state.
Refresh() bool
// SetRefresh sets the refresh notification state.
SetRefresh(bool)
}
RefreshableRes is the interface a resource must implement to support refresh notifications. Default implementations for all of the methods declared in this interface can be obtained for your resource by anonymously adding the traits.Refreshable struct to your resource implementation.
type Res ¶
type Res interface {
fmt.Stringer // String() string
KindedRes
NamedRes // TODO: consider making this optional in the future
MetaRes // All resources must have meta params.
// Default returns a struct with sane defaults for this resource.
Default() Res
// Validate determines if the struct has been defined in a valid state.
Validate() error
// Init initializes the resource and passes in some external information
// and data from the engine.
Init(*Init) error
// Close is run by the engine to clean up after the resource is done.
Close() error
// Watch is run by the engine to monitor for state changes. If it
// detects any, it notifies the engine which will usually run CheckApply
// in response.
Watch() error
// CheckApply determines if the state of the resource is connect and if
// asked to with the `apply` variable, applies the requested state.
CheckApply(apply bool) (checkOK bool, err error)
// Cmp compares itself to another resource and returns an error if they
// are not equivalent.
Cmp(Res) error
}
Res is the minimum interface you need to implement to define a new resource.
func NewNamedResource ¶
NewNamedResource returns an empty resource object from a registered kind. It also sets the name. It is a wrapper around NewResource. It also errors if the name is empty.
func NewResource ¶
NewResource returns an empty resource object from a registered kind. It errors if the resource kind doesn't exist.
type ResUID ¶
type ResUID interface {
fmt.Stringer // String() string
GetName() string
GetKind() string
IFF(ResUID) bool
IsReversed() bool // true means this resource happens before the generator
}
ResUID is a unique identifier for a resource, namely it's name, and the kind ("type").
type ResourceSlice ¶
type ResourceSlice []Res
ResourceSlice is a linear list of resources. It can be sorted.
func (ResourceSlice) Len ¶
func (rs ResourceSlice) Len() int
func (ResourceSlice) Less ¶
func (rs ResourceSlice) Less(i, j int) bool
func (ResourceSlice) Swap ¶
func (rs ResourceSlice) Swap(i, j int)
type Send ¶
type Send struct {
Res SendableRes // a handle to the resource which is sending a value
Key string // the key in the resource that we're sending
Changed bool // set to true if this key was updated, read only!
}
Send points to a value that a resource will send.
type SendableRes ¶
type SendableRes interface {
Res // implement everything in Res but add the additional requirements
// Sends returns a struct containing the defaults of the type we send.
Sends() interface{}
// Send is used in CheckApply to send the desired data. It returns an
// error if the data is malformed or doesn't type check.
Send(st interface{}) error
// Sent returns the most recently sent data. This is used by the engine.
Sent() interface{}
}
SendableRes is the interface a resource must implement to support sending named parameters. You must specify to the engine what kind of values (and with their types) you will be sending. This is used for static type checking. Formerly, you had to make sure not to overwrite omitted parameters, otherwise it will be as if you've now declared a fixed state for that param. For that example, if a parameter `Foo string` had the zero value to mean that it was undefined, and you learned that the value is actually `up`, then sending on that param would cause that state to be managed, when it was previously not. This new interface actually provides a different namespace for sending keys.
type World ¶
type World interface {
ResWatch() chan error
ResExport([]Res) error
// FIXME: should this method take a "filter" data struct instead of many args?
ResCollect(hostnameFilter, kindFilter []string) ([]Res, error)
StrWatch(namespace string) chan error
StrIsNotExist(error) bool
StrGet(namespace string) (string, error)
StrSet(namespace, value string) error
StrDel(namespace string) error
// XXX: add the exchange primitives in here directly?
StrMapWatch(namespace string) chan error
StrMapGet(namespace string) (map[string]string, error)
StrMapSet(namespace, value string) error
StrMapDel(namespace string) error
Scheduler(namespace string, opts ...scheduler.Option) (*scheduler.Result, error)
Fs(uri string) (Fs, error)
}
World is an interface to the rest of the different graph state. It allows the GAPI to store state and exchange information throughout the cluster. It is the interface each machine uses to communicate with the rest of the world.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package event provides some primitives that are used for message passing.
|
Package event provides some primitives that are used for message passing. |
|
packagekit
Package packagekit provides an interface to interact with packagekit.
|
Package packagekit provides an interface to interact with packagekit. |