Documentation ¶
Overview ¶
Package XIR provides Go language bindings to the MergeTB eXperiment Intermediate Representation. XIR is a simple network represenatation where
The primary components are:
- (sub)networks
- nodes
- links
Everything is extensible through a property map member called Props.
Interconnection model supports node-neighbor traversal as well as link-endpoint traversal.
Endpoints are the glue that bind nodes to links. Everything is also upwards traversable. You can follow pointers from an endpoint to a parent node, and then to a parent network, and then to another parent network etc...
Serialization to json is inherent. It does not include the traversal mechanisims as this would create recursively repeditive output.
Properties are represented as map[string]interface{} objects and follow the general notion of being JSON blobs. For Example
{ "construction": { "procs": [ { "cores": {"constraint__": ">", "value__": 2} } ] }, "configuration": { "os": {"constraint": "=", "value__": "ubuntu-18.04"} } }
Every XIR element has a construction and a configuration. Construction contains the fundamental properites of an element and configuration contains and elements soft configuration.
XIR is used in two contexts:
- Experiment specification
- Resource specification
For experiment sepcification, properties map to constraints that define what a valid resource is for the given element. For resource specification properties map to simple values over which constraints can be evaluated.
Index ¶
- Constants
- func B(value uint64) uint64
- func Bps(value uint64) uint64
- func EB(value uint64) uint64
- func Ebps(value uint64) uint64
- func GB(value uint64) uint64
- func GHz(value float64) float64
- func Gbps(value uint64) uint64
- func Hz(value float64) float64
- func IsArray(unk interface{}) bool
- func IsMap(unk interface{}) bool
- func IsValidOp(x Operator) bool
- func KB(value uint64) uint64
- func KHz(value float64) float64
- func Kbps(value uint64) uint64
- func LiftConstraints(x interface{}) interface{}
- func LiftNetConstraints(net *Net)
- func LinkID(es ...EndpointRef) string
- func LinkNetwork(net *Net) error
- func MB(value uint64) uint64
- func MHz(value float64) float64
- func Mbps(value uint64) uint64
- func Ms(value float64) float64
- func Ns(value float64) float64
- func PB(value uint64) uint64
- func ParsePath(path string) []string
- func Pbps(value uint64) uint64
- func Percent(value float64) float64
- func PrepNetwork(net *Net)
- func S(value float64) float64
- func TB(value uint64) uint64
- func THz(value float64) float64
- func Tbps(value uint64) uint64
- func ToFile(net *Net, filename string) error
- func Unit(qual string, value float64, unit string) map[string]interface{}
- func Us(value float64) float64
- type AssetObject
- type Bounds
- type Constraint
- func Choice(value interface{}) Constraint
- func Eq(value interface{}) Constraint
- func ExtractConstraint(m map[string]interface{}) (Constraint, bool)
- func Ge(value interface{}) Constraint
- func Gt(value interface{}) Constraint
- func Le(value interface{}) Constraint
- func Lt(value interface{}) Constraint
- func Select(value interface{}) Constraint
- type Endpoint
- type EndpointRef
- type Endpoints
- type Link
- type Model
- type Mount
- type Neighbor
- type Net
- func (n *Net) AddLink(link *Link)
- func (n *Net) AddNet(net *Net)
- func (n *Net) AddNode(node *Node)
- func (n *Net) AllLinks() []*Link
- func (n *Net) AllNodes() []*Node
- func (n *Net) Clone() *Net
- func (n *Net) DeleteLink(id string) *Link
- func (n *Net) DeleteNode(id string) *Node
- func (n *Net) DeleteSubnet(id string) *Net
- func (n *Net) Dump()
- func (n *Net) GetElementProps(id string) *Props
- func (n *Net) GetLink(id string) (int, *Net, *Link)
- func (n *Net) GetNode(id string) (int, *Net, *Node)
- func (n *Net) GetNodeByName(name string) (int, *Net, *Node)
- func (n *Net) GetSubnet(id string) (int, *Net)
- func (n *Net) Json() ([]byte, error)
- func (n *Net) Label() string
- func (n *Net) Link(es ...*Endpoint) *Link
- func (n *Net) Net(name string) *Net
- func (n *Net) Node(name string) *Node
- func (net *Net) Root() *Net
- func (n *Net) Select(f func(x *Node) bool) []*Node
- func (n *Net) Size() int
- func (n *Net) String() string
- func (n *Net) Table()
- func (n *Net) ToFile(filename string) error
- func (n *Net) ToString() (string, error)
- func (n *Net) Yaml() string
- type Node
- func (n *Node) AddSoftware(p Props) *Nodedeprecated
- func (n *Node) Clone() *Node
- func (n *Node) Endpoint() *Endpoint
- func (n *Node) GetEndpoint(label string) *Endpoint
- func (n *Node) GetEndpointById(id string) *Endpoint
- func (n *Node) GetNeighbor(id string) (*Endpoint, *Endpoint)
- func (n *Node) Label() string
- func (n *Node) Neighbors() []*Endpoint
- func (n *Node) Next(kind string) *Endpoint
- func (n *Node) PNext(proto interface{}) *Endpoint
- func (n *Node) RNext(kind string) *Endpoint
- func (n *Node) Set(p Props) *Node
- func (n *Node) Valence() int
- func (n *Node) Yaml() string
- type Operator
- type Prop
- type Props
- func (p *Props) GetArray(key string) ([]Props, bool)
- func (p *Props) GetBool(key string) (bool, bool)
- func (p *Props) GetConstraint(key string) (Constraint, bool)
- func (p *Props) GetNumber(key string) (float64, bool)
- func (p Props) GetProp(path string) (interface{}, error)
- func (p *Props) GetProps(key string) (Props, bool)
- func (p *Props) GetString(key string) (string, bool)
- func (p *Props) Json() string
- type Software
- type SortedProps
- type Vec2
Constants ¶
const ( EQ Operator = "=" LT = "<" LE = "<=" GT = ">" GE = ">=" CHOICE = "?" SELECT = "[]" )
Variables ¶
This section is empty.
Functions ¶
func LiftConstraints ¶
func LiftConstraints(x interface{}) interface{}
LiftConstraints and ExtractConstraints are a pair of mutually recursive functions that traverse a property tree, identify constraints within the tree and lift any identified constraints into the constraint type
func LiftNetConstraints ¶
func LiftNetConstraints(net *Net)
func LinkID ¶
func LinkID(es ...EndpointRef) string
func LinkNetwork ¶
LinkNetwork performs the business of internal pointer linking within a Net. When we read a Net from a file or database, the traversal pointers are not linked. This function ensures that all the traversal pointers in a Net data structure are linked.
func ParsePath ¶
ParsePath takes in a dot separated path and returns and ordered list of path components. For example node.memory.size* -> [node, memory, size*].
func PrepNetwork ¶
func PrepNetwork(net *Net)
PrepNetwork ensures that all the Neighbor maps are ready. They are not ready upon deserialization. This is a precondition to LinkNetwork
Types ¶
type AssetObject ¶
type AssetObject struct { ID string `json:"id"` Type string `json:"type"` Size int64 `json:"size"` }
Asset is object that will reside on the other side of the mount ID: name of the asset object Type: type of device to mount (fs, block, image) Size: total allocated size, required for block sizes
type Constraint ¶
type Constraint struct { Op Operator `json:"constraint__" mapstructure:"constraint__"` Value interface{} `json:"value__" mapstructure:"value__"` }
func Choice ¶
func Choice(value interface{}) Constraint
func Eq ¶
func Eq(value interface{}) Constraint
func ExtractConstraint ¶
func ExtractConstraint(m map[string]interface{}) (Constraint, bool)
func Ge ¶
func Ge(value interface{}) Constraint
func Gt ¶
func Gt(value interface{}) Constraint
func Le ¶
func Le(value interface{}) Constraint
func Lt ¶
func Lt(value interface{}) Constraint
func Select ¶
func Select(value interface{}) Constraint
func (*Constraint) Int ¶
func (c *Constraint) Int() (int, bool)
Int attempts to return a constaint value as an int. If the underlying value is floating point it will be cast to an int.
type Endpoint ¶
type Endpoint struct { Index int `json:"index"` Props Props `json:"props,omitempty"` Neighbors map[*Endpoint]*Neighbor `json:"-" yaml:"-"` Parent *Node `json:"-" yaml:"-"` }
func (*Endpoint) Label ¶
Label attempts to return an endpoint Label.If the Node has a name in its properties, that is returned. Otherwise the Nodes's ID is returned.
func (*Endpoint) Ref ¶
func (e *Endpoint) Ref() EndpointRef
type EndpointRef ¶
type EndpointRef struct { Node string `json:"node"` Index int `json:"index"` Endpoint *Endpoint `json:"-"` }
func (*EndpointRef) Id ¶
func (e *EndpointRef) Id() string
type Link ¶
type Link struct { Id string `json:"id"` Endpoints []EndpointRef `json:"endpoints"` Props Props `json:"props"` }
type Mount ¶
type Mount struct { Path string `json:"path"` Asset AssetObject `json:"asset"` }
Mount is a device or filesystem mounted to a device Path: where the mount will reside locally
type Net ¶
type Net struct { Id string `json:"id"` Nodes []*Node `json:"nodes"` Links []*Link `json:"links,omitempty"` Nets []*Net `json:"nets,omitempty"` Props Props `json:"props,omitempty"` Parent *Net `json:"-" yaml:"-"` }
func FromFile ¶
FromFile reads an XIR Net from the given file. The file should contain the JSON representation of a Net as produced by ToFile().
func FromString ¶
FromString reads and XIR Net from a string. The string should contain the JSON representation of a Net as produced by ToString().
func (*Net) DeleteLink ¶
DeleteLink deletes a Link from this Net. This is a recursive operation.
func (*Net) DeleteNode ¶
DeleteNode deletes a Node from this Net. This is a recursive operation.
func (*Net) DeleteSubnet ¶
DeleteSubnet deletes a subnet from this network with the specified id. This deletion is not recursive.
func (*Net) GetElementProps ¶
GetElementProps searches for a Node or Link in this network with the specified ID and returns it properties. This search is recursive.
func (*Net) GetLink ¶
GetLink finds a Link with the specified id and returns its index within its parent Net, a pointer to its parent Net and a pointer to the Link itself.
func (*Net) GetNode ¶
GetNode finds a Node with the specified id and returns its index within its parent Net, a pointer to its parent Net, and a pointer to the Node itself.
func (*Net) GetNodeByName ¶
GetNodeByName searches this Net for a node with the given name. This is not a recursive search.
func (*Net) GetSubnet ¶
GetSubnet searches for a Network with the specified ID. This search is not recursive.
func (*Net) Label ¶
Label attempts to return the friendliest label that can be applied to a Net. If the Net has a name in its properties, that is returned. Otherwise the Net's ID is returned.
func (*Net) Link ¶
Link creates a new Link between the provided Endpoints, adds it to this network and returns a pointer to it.
func (*Net) String ¶
String returns a human digestable string representation of a network. This includes all subnetworks.
type Node ¶
type Node struct { Id string `json:"id"` Endpoints Endpoints `json:"endpoints"` Parent *Net `json:"-" yaml:"-"` Props Props `json:"props,omitempty"` Visited bool `json:"-" yaml:"-"` Mounts []*Mount `json:"mounts,omitempty"` }
func (*Node) AddSoftware
deprecated
func (*Node) Endpoint ¶
Endpoint creates a new Endpoint, adds it to this Node and returns a pointer to it.
func (*Node) GetEndpoint ¶
func (*Node) GetEndpointById ¶
func (*Node) Label ¶
Label attempts to return the friendliest label that can be applied to a Node. If the Node has a name in its properties, that is returned. Otherwise the Nodes's ID is returned.
func (*Node) Neighbors ¶
Neighbors returns a list containing all this Node's neighbors. The list of endpoints returned are those of the neighbors.
func (*Node) Set ¶
Set sets the provided properties on this Node. This is a logical merge, any resident properties with the same key will be overwritten. Non-colliding resident properties will remain in tact.
type Props ¶
type Props map[string]interface{}
func (*Props) GetArray ¶
GetArray tries to return the property located at key as an array of props. It returns (value, true) if an object exists at key and is an array of props.
func (*Props) GetBool ¶
GetBool tries to return the property located at key as a boolean. It returns (value, true) if an object exists at key and is a boolean.
func (*Props) GetConstraint ¶
func (p *Props) GetConstraint(key string) (Constraint, bool)
GetConstraint tries to return the property located at key as a constraint. It returns (value, true) if an object exists at key and is a constraint.
func (*Props) GetNumber ¶
GetNumber tries to return the property located at key as a number. It returns (value, true) if an object exists at key and is a number.
func (Props) GetProp ¶
GetProp takes a path and returns the value at that path within the Props object. If no value is present nil is returned.
func (*Props) GetProps ¶
GetProps tries to return the property located at key as a Props object. It returns (value, true) if an object exists at key and is a Props object.
type SortedProps ¶
type SortedProps []Prop
func (SortedProps) Len ¶
func (x SortedProps) Len() int
func (SortedProps) Less ¶
func (x SortedProps) Less(i, j int) bool
func (SortedProps) Swap ¶
func (x SortedProps) Swap(i, j int)