resource

package
v0.2.14 Latest Latest
Warning

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

 Go to latest Published: Jan 26, 2023 License: AGPL-3.0 Imports: 9 Imported by: 87

Documentation

Overview

Package resource contains types that help identify and classify resources (components/services) of a robot. The three most imporant types in this package are: Subtype (which represents an API for a resource), Model (which represents a specific implementation of an API), and Name (which represents a specific instantiation of a resource.)

Both Subtype and Model have a "triplet" format which begins with a namespace. Subtype has "namespace:type:subtype" with "type" in this case being either "service" or "component." Model has "namespace:modelfamily:modelname" with "modelfamily" being somewhat arbitrary, and useful mostly for organization/grouping. Note that each "tier" contains the tier to the left it. Such that ModelFamily contains Namespace, and Model itself contains ModelFamily.

An example resource (say, a motor) may use the motor API, and thus have the Subtype "rdk:component:motor" and have a model such as "rdk:builtin:gpio". Each individual instance of that motor will have an arbitrary name (defined in the robot's configuration) and that is represented by a Name type, which also includes the Subtype and (optionally) the remote it belongs to. Thus, the Name contains everything (API, remote info, and unique name) to locate and cast a resource to the correct interface when requested by a client. While Model is typically only needed during resource instantiation.

Index

Constants

View Source 
const (
	ResourceNamespaceRDK  = Namespace("rdk")
	ResourceTypeComponent = TypeName("component")
	ResourceTypeService   = TypeName("service")
	DefaultServiceName    = "builtin"
	DefaultMaxInstance    = 1
)

Placeholder definitions for a few known constants.

View Source 
const DefaultModelFamilyName = ModelFamilyName("builtin")

DefaultModelFamilyName is the name "default".

Variables

View Source 
var (
	// DefaultModelFamily is the rdk:builtin model family for built-in resources.
	DefaultModelFamily = ModelFamily{ResourceNamespaceRDK, DefaultModelFamilyName}
)
View Source 
var (

	// DefaultServiceModel is used for builtin services.
	DefaultServiceModel = NewDefaultModel("builtin")
)
View Source 
var DefaultServices []Name

DefaultServices is a list of default robot services. services should add themseleves in an init if they should be included by default.

Functions

func AddDefaultService 

func AddDefaultService(n Name)

AddDefaultService add a default service.

func ContainsReservedCharacter added in v0.0.6 

func ContainsReservedCharacter(val string) error

ContainsReservedCharacter returns error if string contains a reserved character.

func NewReservedCharacterUsedError added in v0.0.6 

func NewReservedCharacterUsedError(val, reservedChar string) error

NewReservedCharacterUsedError is used when a reserved character is wrongly used in a name.

func ReconfigureResource added in v0.0.6 

func ReconfigureResource(ctx context.Context, old, newR interface{}) (interface{}, error)

ReconfigureResource tries to reconfigure/replace an old resource with a new one.

func StopResource added in v0.2.2 

func StopResource(ctx context.Context, res interface{}, extra map[string]interface{}) error

StopResource attempts to stops the given resource.

Types

type Graph 

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

Graph The Graph maintains a collection of resources and their dependencies between each other.

func NewGraph 

func NewGraph() *Graph

NewGraph creates a new resource graph.

func (*Graph) AddChildren 

func (g *Graph) AddChildren(child, parent Name) error

AddChildren add a dependency to a parent, create the parent if it doesn't exists yet.

func (*Graph) AddNode 

func (g *Graph) AddNode(node Name, iface interface{})

AddNode adds a node to the graph.

func (*Graph) Clone 

func (g *Graph) Clone() *Graph

Clone deep copy of the resource graph.

func (*Graph) CopyNodeAndChildren 

func (g *Graph) CopyNodeAndChildren(node Name, origin *Graph) error

CopyNodeAndChildren adds a Node and it's children from another graph.

func (*Graph) FindNodeByName 

func (g *Graph) FindNodeByName(name string) (*Name, bool)

FindNodeByName returns a full resource name based on name, note if name is a duplicate the first one found will be returned.

func (*Graph) FindNodesByShortNameAndSubtype 

func (g *Graph) FindNodesByShortNameAndSubtype(name Name) []Name

FindNodesByShortNameAndSubtype will look for resources matching both the subtype and the Name.

func (*Graph) GetAllChildrenOf 

func (g *Graph) GetAllChildrenOf(node Name) []Name

GetAllChildrenOf returns all direct children of a node.

func (*Graph) GetAllParentsOf 

func (g *Graph) GetAllParentsOf(node Name) []Name

GetAllParentsOf returns all parents of a given node.

func (*Graph) IsNodeDependingOn 

func (g *Graph) IsNodeDependingOn(node, child Name) bool

IsNodeDependingOn returns true if child is depending on node.

func (*Graph) MergeAdd 

func (g *Graph) MergeAdd(toAdd *Graph) error

MergeAdd merges two Graphs, if a node exists in both graphs, then it is silently replaced.

func (*Graph) MergeRemove 

func (g *Graph) MergeRemove(toRemove *Graph)

MergeRemove remove common nodes in both graphs.

func (*Graph) Names 

func (g *Graph) Names() []Name

Names returns the all resource graph names.

func (*Graph) Node 

func (g *Graph) Node(node Name) (interface{}, bool)

Node returns the node named name.

func (*Graph) Remove 

func (g *Graph) Remove(node Name)

Remove remove a given node and all it's dependencies.

func (*Graph) RemoveChildren 

func (g *Graph) RemoveChildren(child, parent Name)

RemoveChildren unlink a child from its parent.

func (*Graph) RenameNode 

func (g *Graph) RenameNode(old, newName Name) error

RenameNode rename a node from old to new keeping it's dependencies. On success the old node is destroyed.

func (*Graph) ReplaceNodesParents 

func (g *Graph) ReplaceNodesParents(node Name, other *Graph) error

ReplaceNodesParents replaces all parent of a given node with the parents of the other graph.

func (*Graph) ReverseTopologicalSort 

func (g *Graph) ReverseTopologicalSort() []Name

ReverseTopologicalSort returns an array of nodes' Name ordered by most edges first.

func (*Graph) SubGraphFrom 

func (g *Graph) SubGraphFrom(node Name) (*Graph, error)

SubGraphFrom returns a Sub-Graph containing all linked dependencies starting with node Name.

func (*Graph) TopologicalSort 

func (g *Graph) TopologicalSort() []Name

TopologicalSort returns an array of nodes' Name ordered by fewest edges first.

type Model added in v0.2.8 

type Model struct {
	ModelFamily `json:","`
	Name        ModelName `json:"name"`
}

Model represents an individual model within a family.

func NewDefaultModel added in v0.2.8 

func NewDefaultModel(model ModelName) Model

NewDefaultModel creates a new Model in the rdk:builtin namespace/family based on parameters passed in.

func NewModel added in v0.2.8 

func NewModel(namespace Namespace, fName ModelFamilyName, model ModelName) Model

NewModel creates a new Model based on parameters passed in.

func NewModelFromString added in v0.2.8 

func NewModelFromString(modelStr string) (Model, error)

NewModelFromString creates a new Name based on a fully qualified resource name string passed in.

func NewModelFromStringIgnoreErrors added in v0.2.8 

func NewModelFromStringIgnoreErrors(modelStr string) Model

NewModelFromStringIgnoreErrors parses a model but ignores all errors and creates an empty model. This is used when validation of the model should happen later.

func (Model) String added in v0.2.8 

func (m Model) String() string

String returns the resource model string for the component.

func (*Model) UnmarshalJSON added in v0.2.8 

func (m *Model) UnmarshalJSON(data []byte) error

UnmarshalJSON parses namespace:family:modelname strings to the full Model{} struct.

func (Model) Validate added in v0.2.8 

func (m Model) Validate() error

Validate ensures that important fields exist and are valid.

type ModelFamily added in v0.2.8 

type ModelFamily struct {
	Namespace Namespace       `json:"namespace"`
	Family    ModelFamilyName `json:"model_family"`
}

ModelFamily is a family of related models.

func NewModelFamily added in v0.2.8 

func NewModelFamily(namespace Namespace, family ModelFamilyName) ModelFamily

NewModelFamily creates a new ModelFamily based on parameters passed in.

func (ModelFamily) String added in v0.2.8 

func (f ModelFamily) String() string

String returns the model family string for the resource.

func (ModelFamily) Validate added in v0.2.8 

func (f ModelFamily) Validate() error

Validate ensures that important fields exist and are valid.

type ModelFamilyName added in v0.2.8 

type ModelFamilyName string

ModelFamilyName is the model family.

type ModelName added in v0.2.8 

type ModelName string

ModelName is the name of a specific model within a family.

type MovingCheckable 

type MovingCheckable interface {
	// IsMoving returns whether the resource is moving or not
	IsMoving(context.Context) (bool, error)
}

MovingCheckable is implemented when a resource of a robot returns whether it is moving or not.

type Name 

type Name struct {
	Subtype
	Remote RemoteName
	Name   string
}

Name represents a known component/service representation of a robot.

func NameFromSubtype 

func NameFromSubtype(subtype Subtype, name string) Name

NameFromSubtype creates a new Name based on a Subtype and name string passed in.

func NewFromString 

func NewFromString(resourceName string) (Name, error)

NewFromString creates a new Name based on a fully qualified resource name string passed in.

func NewName 

func NewName(namespace Namespace, rType TypeName, subtype SubtypeName, name string) Name

NewName creates a new Name based on parameters passed in.

func RemoveRemoteName added in v0.1.0 

func RemoveRemoteName(n Name) Name

RemoveRemoteName returns a new name with remote removed.

func (Name) ContainsRemoteNames 

func (n Name) ContainsRemoteNames() bool

ContainsRemoteNames return true if the resource is a remote resource.

func (Name) PopRemote 

func (n Name) PopRemote() Name

PopRemote pop the first remote from a Name (if any) and returns the new Name.

func (Name) PrependRemote 

func (n Name) PrependRemote(remote RemoteName) Name

PrependRemote returns a Name with a remote prepended.

func (Name) ShortName 

func (n Name) ShortName() string

ShortName returns the short name on Name n in the form of <remote>:<name>.

func (Name) String 

func (n Name) String() string

String returns the fully qualified name for the resource.

func (Name) Validate 

func (n Name) Validate() error

Validate ensures that important fields exist and are valid.

type Namespace 

type Namespace string

Namespace identifies the namespaces robot resources can live in.

type OldStoppable 

type OldStoppable interface {
	// Stop stops all movement for the resource
	Stop(context.Context) error
}

OldStoppable will be deprecated soon. See Stoppable. TODO[RSDK-328].

type RPCSubtype 

type RPCSubtype struct {
	Subtype      Subtype
	ProtoSvcName string
	Desc         *desc.ServiceDescriptor
}

An RPCSubtype provides RPC information about a particular subtype.

type Reconfigurable 

type Reconfigurable interface {
	// TODO(RSDK-895): hold over until all resources have names. This doesn't guarantee
	// everything is named since everything may not be a reconfigurable (but should be).
	Name() Name
	// Reconfigure reconfigures the resource
	Reconfigure(ctx context.Context, newResource Reconfigurable) error
}

Reconfigurable is implemented when component/service of a robot is reconfigurable.

type RemoteName 

type RemoteName string

RemoteName identifies the remote the resource is attached to.

type Stoppable 

type Stoppable interface {
	// Stop stops all movement for the resource
	Stop(context.Context, map[string]interface{}) error
}

Stoppable is implemented when a resource of a robot can stop its movement.

type Subtype 

type Subtype struct {
	Type
	ResourceSubtype SubtypeName `json:"subtype"`
}

Subtype represents a known component/service (resource) API.

func NewDefaultSubtype added in v0.2.8 

func NewDefaultSubtype(subtype SubtypeName, rType TypeName) Subtype

NewDefaultSubtype creates a new Subtype based on parameters passed in.

func NewSubtype 

func NewSubtype(namespace Namespace, rType TypeName, subtype SubtypeName) Subtype

NewSubtype creates a new Subtype based on parameters passed in.

func NewSubtypeFromString added in v0.2.8 

func NewSubtypeFromString(subtypeName string) (Subtype, error)

NewSubtypeFromString creates a new Subtype from string like: %s:%s:%s.

func (Subtype) String 

func (s Subtype) String() string

String returns the resource subtype string for the component.

func (*Subtype) UnmarshalJSON added in v0.2.8 

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

UnmarshalJSON parses namespace:type:subtype strings to the full Subtype struct.

func (Subtype) Validate 

func (s Subtype) Validate() error

Validate ensures that important fields exist and are valid.

type SubtypeName 

type SubtypeName string

SubtypeName identifies the resources subtypes that robot resources can be.

type Type 

type Type struct {
	Namespace    Namespace `json:"namespace"`
	ResourceType TypeName  `json:"type"`
}

Type represents a known component/service type of a robot.

func NewType 

func NewType(namespace Namespace, rType TypeName) Type

NewType creates a new Type based on parameters passed in.

func (Type) String 

func (t Type) String() string

String returns the resource type string for the component.

func (Type) Validate 

func (t Type) Validate() error

Validate ensures that important fields exist and are valid.

type TypeName 

type TypeName string

TypeName identifies the resource types that robot resources can be.

type Updateable 

type Updateable interface {
	// Update updates the resource
	Update(context.Context, map[Name]interface{}) error
}

Updateable is implemented when component/service of a robot should be updated after the robot reconfiguration process is done.

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.