Documentation
¶
Overview ¶
Package resource contains types that help identify and classify resources (components/services) of a robot. The three most important types in this package are: API (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 API and Model have a "triplet" format that begins with a namespace. API 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 API "rdk:component:motor" and have a model such as "rdk:builtin:gpio". Each instance of that motor will have an arbitrary name (defined in the robot's configuration) represented by a Name type, which also includes the API 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. Model on the other hand is typically only needed during resource instantiation.
Index ¶
- Constants
- Variables
- func AsType[T Resource](from Resource) (T, error)
- func ContainsReservedCharacter(val string) error
- func DependencyNotFoundError(name Name) error
- func DependencyTypeError[T Resource](name Name, actual interface{}) error
- func Deregister(api API, model Model)
- func DeregisterAPI(api API)
- func FromDependencies[T Resource](resources Dependencies, name Name) (T, error)
- func IsDependencyNotReadyError(err error) bool
- func IsMustRebuildError(err error) bool
- func IsNotAvailableError(err error) bool
- func IsNotFoundError(err error) bool
- func NativeConfig[T any](conf Config) (T, error)
- func NewBuildTimeoutError(name Name) error
- func NewMustRebuildError(name Name) error
- func NewNotAvailableError(name Name, err error) error
- func NewNotFoundError(name Name) error
- func Register[ResourceT Resource, ConfigT ConfigValidator](api API, model Model, reg Registration[ResourceT, ConfigT])
- func RegisterAPI[ResourceT Resource](api API, creator APIRegistration[ResourceT])
- func RegisterAPIWithAssociation[ResourceT Resource, AssocT AssociatedNameUpdater](api API, creator APIRegistration[ResourceT], ...)
- func RegisterComponent[ResourceT Resource, ConfigT ConfigValidator](api API, model Model, reg Registration[ResourceT, ConfigT])
- func RegisterDefaultService[ResourceT Resource, ConfigT ConfigValidator](api API, model Model, reg Registration[ResourceT, ConfigT])
- func RegisterService[ResourceT Resource, ConfigT ConfigValidator](api API, model Model, reg Registration[ResourceT, ConfigT])
- func RegisteredAPIs() map[API]APIRegistration[Resource]
- func RegisteredResources() map[APIModel]Registration[Resource, ConfigValidator]
- func StatusFunc[ResourceT Resource, StatusU proto.Message](f func(ctx context.Context, res ResourceT) (StatusU, error)) func(ctx context.Context, res ResourceT) (any, error)
- func TransformAttributeMap[T any](attributes utils.AttributeMap) (T, error)
- func TypeError[T Resource](actual Resource) error
- type API
- type APIModel
- type APINamespace
- type APIRegistration
- type APIResourceCollection
- type APIType
- type Actuator
- type AlwaysRebuild
- type AssociatedConfigRegistration
- type AssociatedNameUpdater
- type AssociatedResourceConfig
- type AttributeMapConverter
- type Config
- func (conf *Config) AdjustPartialNames(defaultAPIType string)
- func (conf *Config) Dependencies() []string
- func (conf Config) Equals(other Config) bool
- func (conf Config) MarshalJSON() ([]byte, error)
- func (conf *Config) ResourceName() Name
- func (conf *Config) String() string
- func (conf *Config) UnmarshalJSON(data []byte) error
- func (conf *Config) Validate(path, defaultAPIType string) ([]string, error)
- type ConfigValidator
- type Create
- type CreateRPCClient
- type CreateStatus
- type Dependencies
- type DependencyNotReadyError
- type DeprecatedCreateWithRobot
- type DiscoverError
- type Discovery
- type DiscoveryFunc
- type DiscoveryQuery
- type Graph
- func (g *Graph) AddChild(child, parent Name) error
- func (g *Graph) AddNode(node Name, nodeVal *GraphNode) error
- func (g *Graph) Clone() *Graph
- func (g *Graph) CopyNodeAndChildren(node Name, origin *Graph) error
- func (g *Graph) FindNodesByAPI(api API) []Name
- func (g *Graph) FindNodesByShortNameAndAPI(name Name) []Name
- func (g *Graph) GetAllChildrenOf(node Name) []Name
- func (g *Graph) GetAllParentsOf(node Name) []Name
- func (g *Graph) IsNodeDependingOn(node, child Name) bool
- func (g *Graph) LastUpdatedTime() int64
- func (g *Graph) MarkForRemoval(toMark *Graph)
- func (g *Graph) MergeAdd(toAdd *Graph) error
- func (g *Graph) Names() []Name
- func (g *Graph) Node(node Name) (*GraphNode, bool)
- func (g *Graph) RemoveChild(child, parent Name)
- func (g *Graph) RemoveMarked() []Resource
- func (g *Graph) ReplaceNodesParents(node Name, other *Graph) error
- func (g *Graph) ResolveDependencies(logger golog.Logger) error
- func (g *Graph) ReverseTopologicalSort() []Name
- func (g *Graph) SubGraphFrom(node Name) (*Graph, error)
- func (g *Graph) TopologicalSort() []Name
- func (g *Graph) TopologicalSortInLevels() [][]Name
- type GraphNode
- func (w *GraphNode) CheckReconfigure() error
- func (w *GraphNode) Close(ctx context.Context) error
- func (w *GraphNode) Config() Config
- func (w *GraphNode) HasResource() bool
- func (w *GraphNode) IncrementTimesReconfigured()
- func (w *GraphNode) IsUninitialized() bool
- func (w *GraphNode) MarkForRemoval()
- func (w *GraphNode) MarkedForRemoval() bool
- func (w *GraphNode) NeedsReconfigure() bool
- func (w *GraphNode) Resource() (Resource, error)
- func (w *GraphNode) ResourceModel() Model
- func (w *GraphNode) SetLastError(err error)
- func (w *GraphNode) SetNeedsUpdate()
- func (w *GraphNode) SetNewConfig(newConfig Config, dependencies []string)
- func (w *GraphNode) SwapResource(newRes Resource, newModel Model)
- func (w *GraphNode) UnresolvedDependencies() []string
- func (w *GraphNode) UnsafeResource() (Resource, error)
- func (w *GraphNode) UnsetResource()
- func (w *GraphNode) UpdatedAt() int64
- type LinkAssocationConfig
- type LogConfig
- type Model
- type ModelFamily
- type ModelNamespace
- type Name
- type Named
- type NoNativeConfig
- type RPCAPI
- type Registration
- type Resource
- type ResponseMetadata
- type Shaped
- type TriviallyCloseable
- type TriviallyReconfigurable
- type TriviallyValidateConfig
Constants ¶
const ( // APINamespaceRDK is the namespace to use for APIs defined by the standard robot API. APINamespaceRDK = APINamespace("rdk") // APINamespaceRDKInternal is the namespace to use for internal services. APINamespaceRDKInternal = APINamespace("rdk-internal") // APITypeServiceName is for any service in any namespace. APITypeServiceName = "service" // APITypeComponentName is for any component in any namespace. APITypeComponentName = "component" )
const ( DefaultServiceName = "builtin" DefaultMaxInstance = 1 )
Placeholder definitions for a few known constants.
const ModelNamespaceRDK = ModelNamespace("rdk")
ModelNamespaceRDK is the namespace to use for models implemented by the rdk.
Variables ¶
var ( // DefaultModelFamily is the rdk:builtin model family for built-in resources. DefaultModelFamily = ModelNamespaceRDK.WithFamily("builtin") // DefaultServiceModel is used for builtin services. DefaultServiceModel = DefaultModelFamily.WithModel("builtin") )
var ErrDoUnimplemented = errors.New("DoCommand unimplemented")
ErrDoUnimplemented is returned if the DoCommand methods is not implemented.
var ( // MaxReconfigAttempts is the max number of reconfigure attempts per node/resource. MaxReconfigAttempts uint64 = 5 )
Functions ¶
func ContainsReservedCharacter ¶ added in v0.0.6
ContainsReservedCharacter returns error if string contains a reserved character.
func DependencyNotFoundError ¶ added in v0.2.36
DependencyNotFoundError is used when a resource is not found in a dependencies.
func DependencyTypeError ¶ added in v0.2.36
DependencyTypeError is used when a resource doesn't implement the expected interface.
func Deregister ¶ added in v0.2.36
Deregister removes a previously registered resource.
func DeregisterAPI ¶ added in v0.2.36
func DeregisterAPI(api API)
DeregisterAPI removes a previously registered api.
func FromDependencies ¶ added in v0.2.36
func FromDependencies[T Resource](resources Dependencies, name Name) (T, error)
FromDependencies returns a named component from a collection of dependencies.
func IsDependencyNotReadyError ¶ added in v0.2.36
IsDependencyNotReadyError returns if the given error is any kind of dependency not found error.
func IsMustRebuildError ¶ added in v0.2.36
IsMustRebuildError returns whether or not the given error is a MustRebuildError.
func IsNotAvailableError ¶ added in v0.2.36
IsNotAvailableError returns if the given error is any kind of not available error.
func IsNotFoundError ¶ added in v0.2.50
IsNotFoundError returns if the given error is any kind of not found error.
func NativeConfig ¶ added in v0.2.36
NativeConfig returns the native config from the given config via its converted attributes. When generics are better in go to support a mapping of Models -> T's (cannot right now because of type instantiation rules), then this should be a method on the type and hide away both Attributes and ConvertedAttributes.
func NewBuildTimeoutError ¶ added in v0.5.0
NewBuildTimeoutError is used when a resource times out during construction or reconfiguration.
func NewMustRebuildError ¶ added in v0.2.36
NewMustRebuildError is returned when a resource cannot be reconfigured in place and instead must be rebuilt. Almost all models/drivers should be able to reconfigure in place to support the best user experience.
func NewNotAvailableError ¶ added in v0.2.36
NewNotAvailableError is used when a resource is not available because of some error.
func NewNotFoundError ¶ added in v0.2.36
NewNotFoundError is used when a resource is not found.
func Register ¶ added in v0.2.36
func Register[ResourceT Resource, ConfigT ConfigValidator]( api API, model Model, reg Registration[ResourceT, ConfigT], )
Register registers a model for a resource (component/service) with and its construction info.
func RegisterAPI ¶ added in v0.2.36
func RegisterAPI[ResourceT Resource](api API, creator APIRegistration[ResourceT])
RegisterAPI register a ResourceAPI to its corresponding resource api.
func RegisterAPIWithAssociation ¶ added in v0.2.36
func RegisterAPIWithAssociation[ResourceT Resource, AssocT AssociatedNameUpdater]( api API, creator APIRegistration[ResourceT], association AssociatedConfigRegistration[AssocT], )
RegisterAPIWithAssociation register a ResourceAPI to its corresponding resource api along with a way to allow other resources to associate into its config.
func RegisterComponent ¶ added in v0.2.36
func RegisterComponent[ResourceT Resource, ConfigT ConfigValidator]( api API, model Model, reg Registration[ResourceT, ConfigT], )
RegisterComponent registers a model for a component and its construction info. It's a helper for Register.
func RegisterDefaultService ¶ added in v0.2.36
func RegisterDefaultService[ResourceT Resource, ConfigT ConfigValidator]( api API, model Model, reg Registration[ResourceT, ConfigT], )
RegisterDefaultService registers a default model for a service and its construction info. It's a helper for RegisterService.
func RegisterService ¶ added in v0.2.36
func RegisterService[ResourceT Resource, ConfigT ConfigValidator](api API, model Model, reg Registration[ResourceT, ConfigT])
RegisterService registers a model for a service and its construction info. It's a helper for Register.
func RegisteredAPIs ¶ added in v0.2.36
func RegisteredAPIs() map[API]APIRegistration[Resource]
RegisteredAPIs returns a copy of the registered resource apis.
func RegisteredResources ¶ added in v0.2.36
func RegisteredResources() map[APIModel]Registration[Resource, ConfigValidator]
RegisteredResources returns a copy of the registered resources.
func StatusFunc ¶ added in v0.2.36
func StatusFunc[ResourceT Resource, StatusU proto.Message]( f func(ctx context.Context, res ResourceT) (StatusU, error), ) func(ctx context.Context, res ResourceT) (any, error)
StatusFunc adapts the given typed status function to an untyped value.
func TransformAttributeMap ¶ added in v0.2.36
func TransformAttributeMap[T any](attributes utils.AttributeMap) (T, error)
TransformAttributeMap uses an attribute map to transform attributes to the prescribed format.
Types ¶
type API ¶ added in v0.2.36
API represents a known component/service (resource) API. It consists of a Namespace, Type, and API.
func NewAPIFromString ¶ added in v0.2.36
NewAPIFromString creates a new API from a fully qualified string in the format namespace:type:subtype.
func NewPossibleRDKServiceAPIFromString ¶ added in v0.2.36
NewPossibleRDKServiceAPIFromString returns an API from a string that if is a singular name, will be interpreted as an RDK service.
func (API) IsComponent ¶ added in v0.2.36
IsComponent returns if this API is for a component.
func (API) MarshalJSON ¶ added in v0.2.36
MarshalJSON marshals the API name in its triplet form.
func (*API) UnmarshalJSON ¶ added in v0.2.36
UnmarshalJSON parses either a string of the form namespace:type:subtype or a json object into an API object.
type APIModel ¶ added in v0.2.36
An APIModel is the tuple that identifies a model implementing an API.
type APINamespace ¶ added in v0.2.36
type APINamespace string
APINamespace identifies the namespaces robot resources can live in.
func (APINamespace) WithComponentType ¶ added in v0.2.36
func (n APINamespace) WithComponentType(subtypeName string) API
WithComponentType returns an API with the given component name.
func (APINamespace) WithServiceType ¶ added in v0.2.36
func (n APINamespace) WithServiceType(subtypeName string) API
WithServiceType returns an API with the given service name.
func (APINamespace) WithType ¶ added in v0.2.36
func (n APINamespace) WithType(name string) APIType
WithType returns an API Type with the given name.
type APIRegistration ¶ added in v0.2.36
type APIRegistration[ResourceT Resource] struct { Status CreateStatus[ResourceT] RPCServiceServerConstructor func(apiColl APIResourceCollection[ResourceT]) interface{} RPCServiceHandler rpc.RegisterServiceHandlerFromEndpointFunc RPCServiceDesc *grpc.ServiceDesc ReflectRPCServiceDesc *desc.ServiceDescriptor RPCClient CreateRPCClient[ResourceT] // MaxInstance sets a limit on the number of this api allowed on a robot. // If MaxInstance is not set then it will default to 0 and there will be no limit. MaxInstance int MakeEmptyCollection func() APIResourceCollection[Resource] // contains filtered or unexported fields }
APIRegistration stores api-specific functions and clients.
func LookupAPIRegistration ¶ added in v0.2.36
func LookupAPIRegistration[ResourceT Resource](api API) (APIRegistration[ResourceT], bool, error)
LookupAPIRegistration looks up a ResourceAPI by the given api. false is returned if there is none or error if an error occurs.
func LookupGenericAPIRegistration ¶ added in v0.2.36
func LookupGenericAPIRegistration(api API) (APIRegistration[Resource], bool)
LookupGenericAPIRegistration looks up a ResourceAPI by the given api. false is returned if there is none.
func (APIRegistration[ResourceT]) RegisterRPCService ¶ added in v0.2.36
func (rs APIRegistration[ResourceT]) RegisterRPCService( ctx context.Context, rpcServer rpc.Server, apiColl APIResourceCollection[ResourceT], ) error
RegisterRPCService registers this api into the given RPC server.
type APIResourceCollection ¶ added in v0.2.36
type APIResourceCollection[T Resource] interface { Resource(name string) (T, error) ReplaceAll(resources map[Name]T) error Add(resName Name, res T) error Remove(name Name) error ReplaceOne(resName Name, res T) error }
APIResourceCollection defines a collection of typed resources.
func NewAPIResourceCollection ¶ added in v0.2.36
func NewAPIResourceCollection[T Resource](api API, r map[Name]T) (APIResourceCollection[T], error)
NewAPIResourceCollection creates a new API resource collection, which holds and replaces resources belonging to that api.
func NewEmptyAPIResourceCollection ¶ added in v0.2.36
func NewEmptyAPIResourceCollection[T Resource](api API) APIResourceCollection[T]
NewEmptyAPIResourceCollection creates a new API resource collection, which holds and replaces resources belonging to that api.
type APIType ¶ added in v0.2.36
type APIType struct { Namespace APINamespace `json:"namespace"` Name string `json:"type"` }
APIType represents a known component/service type of a robot.
func (APIType) Validate ¶ added in v0.2.36
Validate ensures that important fields exist and are valid.
func (APIType) WithSubtype ¶ added in v0.2.36
WithSubtype returns an API with the given subtype name.
type Actuator ¶ added in v0.2.36
type Actuator interface { // IsMoving returns whether the resource is moving or not IsMoving(context.Context) (bool, error) // Stop stops all movement for the resource Stop(context.Context, map[string]interface{}) error }
Actuator is any resource that can move.
type AlwaysRebuild ¶ added in v0.2.36
type AlwaysRebuild struct{}
AlwaysRebuild is to be embedded by any resource that must always rebuild and not reconfigure.
func (AlwaysRebuild) Reconfigure ¶ added in v0.2.36
func (a AlwaysRebuild) Reconfigure(ctx context.Context, deps Dependencies, conf Config) error
Reconfigure always returns a must rebuild error.
type AssociatedConfigRegistration ¶ added in v0.2.36
type AssociatedConfigRegistration[AssocT AssociatedNameUpdater] struct { // AttributeMapConverter is used to convert raw attributes to the resource's native associated config. AttributeMapConverter AttributeMapConverter[AssocT] // contains filtered or unexported fields }
An AssociatedConfigRegistration describes how to convert all attributes for a type of resource associated with another resource (e.g. data capture on a resource).
func LookupAssociatedConfigRegistration ¶ added in v0.2.36
func LookupAssociatedConfigRegistration(api API) (AssociatedConfigRegistration[AssociatedNameUpdater], bool)
LookupAssociatedConfigRegistration finds the resource association config registration for the given api.
type AssociatedNameUpdater ¶ added in v0.2.36
AssociatedNameUpdater allows an associated config to have its names updated externally.
type AssociatedResourceConfig ¶ added in v0.2.36
type AssociatedResourceConfig struct { API API Attributes utils.AttributeMap ConvertedAttributes interface{} RemoteName string }
An AssociatedResourceConfig describes configuration of a resource for an associated resource.
func (AssociatedResourceConfig) MarshalJSON ¶ added in v0.2.36
func (assoc AssociatedResourceConfig) MarshalJSON() ([]byte, error)
MarshalJSON marshals JSON from the config.
func (*AssociatedResourceConfig) UnmarshalJSON ¶ added in v0.2.36
func (assoc *AssociatedResourceConfig) UnmarshalJSON(data []byte) error
UnmarshalJSON unmarshals JSON into the config.
type AttributeMapConverter ¶ added in v0.2.36
type AttributeMapConverter[ConfigT any] func(attributes utils.AttributeMap) (ConfigT, error)
An AttributeMapConverter converts an attribute map into a native config type for a resource.
type Config ¶ added in v0.2.36
type Config struct { Name string API API Model Model Frame *referenceframe.LinkConfig DependsOn []string LogConfiguration LogConfig AssociatedResourceConfigs []AssociatedResourceConfig Attributes utils.AttributeMap ConvertedAttributes ConfigValidator ImplicitDependsOn []string // contains filtered or unexported fields }
A Config describes the configuration of a resource.
func NewEmptyConfig ¶ added in v0.2.36
NewEmptyConfig returns a new, empty config for the given name and model.
func (*Config) AdjustPartialNames ¶ added in v0.2.36
AdjustPartialNames assumes this config comes from a place where the resource name, API names, Model names, and associated config type names are partially stored (JSON/Proto/Database) and will fix them up to the builtin values they are intended for.
func (*Config) Dependencies ¶ added in v0.2.36
Dependencies returns the deduplicated union of user-defined and implicit dependencies.
func (Config) Equals ¶ added in v0.2.36
Equals checks if the two configs are deeply equal to each other. Validation related fields and implicit dependencies will be ignored.
func (Config) MarshalJSON ¶ added in v0.2.36
MarshalJSON marshals JSON from the config.
func (*Config) ResourceName ¶ added in v0.2.36
ResourceName returns the ResourceName for the component.
func (*Config) UnmarshalJSON ¶ added in v0.2.36
UnmarshalJSON unmarshals JSON into the config.
type ConfigValidator ¶ added in v0.2.36
A ConfigValidator validates a configuration and also returns dependencies that were implicitly discovered.
type Create ¶ added in v0.2.36
type Create[ResourceT Resource] func( ctx context.Context, deps Dependencies, conf Config, logger golog.Logger, ) (ResourceT, error)
A Create creates a resource (component/service) from a collection of dependencies and a given config.
type CreateRPCClient ¶ added in v0.2.36
type CreateRPCClient[ResourceT Resource] func( ctx context.Context, conn rpc.ClientConn, remoteName string, name Name, logger golog.Logger, ) (ResourceT, error)
A CreateRPCClient will create the client for the resource.
type CreateStatus ¶ added in v0.2.36
CreateStatus creates a status from a given resource. The return type is expected to be comprised of string keys (or it should be possible to decompose it into string keys) and values comprised of primitives, list of primitives, maps with string keys (or at least can be decomposed into one), or lists of the aforementioned type of maps. Results with other types of data are not guaranteed.
type Dependencies ¶ added in v0.2.36
Dependencies are a set of resources that a resource requires for reconfiguration.
type DependencyNotReadyError ¶ added in v0.2.36
A DependencyNotReadyError is used whenever we reference a dependency that has not been constructed and registered yet.
func (*DependencyNotReadyError) Error ¶ added in v0.2.36
func (e *DependencyNotReadyError) Error() string
func (*DependencyNotReadyError) PrettyPrint ¶ added in v0.6.0
func (e *DependencyNotReadyError) PrettyPrint() string
PrettyPrint returns a formatted string representing a `DependencyNotReadyError` error. This can be useful as a `DependencyNotReadyError` often wraps a series of lower level `DependencyNotReadyError` errors.
type DeprecatedCreateWithRobot ¶ added in v0.2.36
type DeprecatedCreateWithRobot[ResourceT Resource] func( ctx context.Context, r any, conf Config, logger golog.Logger, ) (ResourceT, error)
A DeprecatedCreateWithRobot creates a resource from a robot and a given config.
type DiscoverError ¶ added in v0.2.36
type DiscoverError struct {
Query DiscoveryQuery
}
DiscoverError indicates that a Discover function has returned an error.
func (*DiscoverError) Error ¶ added in v0.2.36
func (e *DiscoverError) Error() string
type Discovery ¶ added in v0.2.36
type Discovery struct { Query DiscoveryQuery Results interface{} }
Discovery holds a Query and a corresponding discovered component configuration. A discovered component configuration can be comprised of primitives, a list of primitives, maps with string keys (or at least can be decomposed into one), or lists of the forementioned type of maps. Results with other types of data are not guaranteed.
type DiscoveryFunc ¶ added in v0.2.36
DiscoveryFunc is a function that discovers component configurations.
type DiscoveryQuery ¶ added in v0.2.36
DiscoveryQuery is a tuple of API and model used to lookup discovery functions.
func NewDiscoveryQuery ¶ added in v0.2.36
func NewDiscoveryQuery(api API, model Model) DiscoveryQuery
NewDiscoveryQuery returns a discovery query for a given API and model.
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 (*Graph) AddChild ¶ added in v0.2.36
AddChild add a dependency to a parent, create the parent if it doesn't exists yet.
func (*Graph) AddNode ¶
AddNode adds a node to the graph. Once added, the graph owns the node and to access it further, use Node.
func (*Graph) CopyNodeAndChildren ¶
CopyNodeAndChildren adds a Node and it's children from another graph.
func (*Graph) FindNodesByAPI ¶ added in v0.2.36
FindNodesByAPI finds nodes with the given API.
func (*Graph) FindNodesByShortNameAndAPI ¶ added in v0.2.36
FindNodesByShortNameAndAPI will look for resources matching both the API and the name.
func (*Graph) GetAllChildrenOf ¶
GetAllChildrenOf returns all direct children of a node.
func (*Graph) GetAllParentsOf ¶
GetAllParentsOf returns all parents of a given node.
func (*Graph) IsNodeDependingOn ¶
IsNodeDependingOn returns true if child is depending on node.
func (*Graph) LastUpdatedTime ¶ added in v0.2.36
LastUpdatedTime returns the last logical clock time a resource updated.
func (*Graph) MarkForRemoval ¶ added in v0.2.36
MarkForRemoval marks the given graph for removal at a later point by RemoveMarked.
func (*Graph) MergeAdd ¶
MergeAdd merges two Graphs, if a node exists in both graphs, then it is silently replaced.
func (*Graph) RemoveChild ¶ added in v0.2.36
RemoveChild unlink a child from its parent.
func (*Graph) RemoveMarked ¶ added in v0.2.36
RemoveMarked removes previously marked nodes from the graph and returns all the resources removed that should now be closed by the caller.
func (*Graph) ReplaceNodesParents ¶
ReplaceNodesParents replaces all parent of a given node with the parents of the other graph.
func (*Graph) ResolveDependencies ¶ added in v0.2.36
ResolveDependencies attempts to link up unresolved dependencies after new changes to the graph.
func (*Graph) ReverseTopologicalSort ¶
ReverseTopologicalSort returns an array of nodes' Name ordered by most edges first. This can also be seen as being ordered where each name has no prior name depending on it.
func (*Graph) SubGraphFrom ¶
SubGraphFrom returns a Sub-Graph containing all linked dependencies starting with node Name.
func (*Graph) TopologicalSort ¶
TopologicalSort returns an array of nodes' Name ordered by fewest edges first. This can also be seen as being ordered where each name has no subsequent name depending on it.
func (*Graph) TopologicalSortInLevels ¶ added in v0.2.36
TopologicalSortInLevels returns an array of array of nodes' Name ordered by fewest edges first. This can also be seen as being ordered where each name has no subsequent name depending on it.
type GraphNode ¶ added in v0.2.36
type GraphNode struct {
// contains filtered or unexported fields
}
A GraphNode contains the current state of a resource. It starts out as either uninitialized, unconfigured, or configured. Based on these states, the underlying Resource may or may not be available. Additionally, the node can be informed that the resource either needs to be updated or eventually removed. During its life, errors may be set on the node to indicate that the resource is no longer available to external users.
func NewConfiguredGraphNode ¶ added in v0.2.36
NewConfiguredGraphNode returns a node that is already configured with the supplied config and resource.
func NewUnconfiguredGraphNode ¶ added in v0.2.36
NewUnconfiguredGraphNode returns a node that contains enough information to construct the underlying resource.
func NewUninitializedNode ¶ added in v0.2.36
func NewUninitializedNode() *GraphNode
NewUninitializedNode returns a node that is brand new and not yet initialized.
func (*GraphNode) CheckReconfigure ¶ added in v0.11.0
CheckReconfigure returns whether or not the resource is able to be (re)configured based on how many previous attempts were made— nil if it is able to be (re)configured, or the appropriate error with the reason why it cannot (re)configure.
func (*GraphNode) Config ¶ added in v0.2.36
Config returns the current config that this resource is using. This value should only be assumed to be associated with the current resource.
func (*GraphNode) HasResource ¶ added in v0.2.36
HasResource returns if calling Resource would result in no error.
func (*GraphNode) IncrementTimesReconfigured ¶ added in v0.11.0
func (w *GraphNode) IncrementTimesReconfigured()
IncrementTimesReconfigured increments the number of times the resource has been reconfigured by 1. Value resetting handled in other methods situationally.
func (*GraphNode) IsUninitialized ¶ added in v0.2.36
IsUninitialized returns if this resource is in an uninitialized state.
func (*GraphNode) MarkForRemoval ¶ added in v0.2.36
func (w *GraphNode) MarkForRemoval()
MarkForRemoval marks this node for removal at a later time.
func (*GraphNode) MarkedForRemoval ¶ added in v0.2.36
MarkedForRemoval returns if this node is marked for removal.
func (*GraphNode) NeedsReconfigure ¶ added in v0.2.36
NeedsReconfigure returns whether or not this node needs reconfiguration performed on its underlying resource.
func (*GraphNode) Resource ¶ added in v0.2.36
Resource returns the underlying resource if it is not pending removal, has no error on it, and is initialized.
func (*GraphNode) ResourceModel ¶ added in v0.2.36
ResourceModel returns the current model that this resource is. This value should only be assumed to be associated with the current resource.
func (*GraphNode) SetLastError ¶ added in v0.2.36
SetLastError sets the latest error on this node. This will cause the resource to become unavailable to external users of the graph. The resource manager may still access the underlying resource via UnsafeResource.
func (*GraphNode) SetNeedsUpdate ¶ added in v0.2.36
func (w *GraphNode) SetNeedsUpdate()
SetNeedsUpdate is used to inform the node that it should reconfigure itself with the same config in order to process dependency updates. If the node was previously marked for removal, this makes no changes.
func (*GraphNode) SetNewConfig ¶ added in v0.2.36
SetNewConfig is used to inform the node that it has been modified and requires a reconfiguration. If the node was previously marked for removal, this unmarks it.
func (*GraphNode) SwapResource ¶ added in v0.2.36
SwapResource emplaces the new resource. It may be the same as before and expects the caller to close the old one. This is considered to be a working resource and as such we unmark it for removal and indicate it no longer needs reconfiguration.
func (*GraphNode) UnresolvedDependencies ¶ added in v0.2.36
UnresolvedDependencies returns the set of names that are yet to be resolved as dependencies for the node.
func (*GraphNode) UnsafeResource ¶ added in v0.2.36
UnsafeResource always returns the underlying resource, if initialized, even if it is in an error state. This should only be called during reconfiguration.
func (*GraphNode) UnsetResource ¶ added in v0.10.0
func (w *GraphNode) UnsetResource()
UnsetResource unsets the current resource. This function does not clean up or close the resource and should be used carefully.
type LinkAssocationConfig ¶ added in v0.2.36
LinkAssocationConfig allows one resource to associate a specific association config to its own config. This is generally done by a specific resource (e.g. data capture of many components).
type Model ¶ added in v0.2.8
type Model struct { Family ModelFamily `json:","` Name string `json:"name"` }
Model represents an individual model within a family. It consists of a Namespace, Family, and Name.
func NewModelFromString ¶ added in v0.2.8
NewModelFromString creates a new Name based on a fully qualified resource name string passed in.
func (Model) MarshalJSON ¶ added in v0.2.36
MarshalJSON marshals the model name in its triplet form.
func (*Model) UnmarshalJSON ¶ added in v0.2.8
UnmarshalJSON parses namespace:family:modelname strings to the full Model{} struct.
type ModelFamily ¶ added in v0.2.8
type ModelFamily struct { Namespace ModelNamespace `json:"namespace"` Name string `json:"model_family"` }
ModelFamily is a family of related models.
func NewModelFamily ¶ added in v0.2.8
func NewModelFamily(namespace, family string) ModelFamily
NewModelFamily returns a new family from the given namespace and family.
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.
func (ModelFamily) WithModel ¶ added in v0.2.36
func (f ModelFamily) WithModel(name string) Model
WithModel returns a new model with the given name.
type ModelNamespace ¶ added in v0.2.36
type ModelNamespace string
ModelNamespace identifies the namespaces resource models can live in.
func (ModelNamespace) WithFamily ¶ added in v0.2.36
func (n ModelNamespace) WithFamily(name string) ModelFamily
WithFamily returns a new model family with the given name.
type Name ¶
Name represents a known component/service representation of a robot.
func DefaultServices ¶
func DefaultServices() []Name
DefaultServices returns all servies that will be constructed by default if not specified in a config.
func NewFromString ¶
NewFromString creates a new Name based on a fully qualified resource name string passed in.
func RemoveRemoteName ¶ added in v0.1.0
RemoveRemoteName returns a new name with remote removed.
func (Name) AsNamed ¶ added in v0.2.36
AsNamed is a helper to let this name return itself as a basic resource that does nothing.
func (Name) ContainsRemoteNames ¶
ContainsRemoteNames return true if the resource is a remote resource.
func (Name) PopRemote ¶
PopRemote pop the first remote from a Name (if any) and returns the new Name.
func (Name) PrependRemote ¶
PrependRemote returns a Name with a remote prepended.
func (*Name) UnmarshalJSON ¶ added in v0.2.36
UnmarshalJSON unmarshals a resource name from a string.
type Named ¶ added in v0.2.36
type Named interface { Name() Name DoCommand(ctx context.Context, cmd map[string]interface{}) (map[string]interface{}, error) }
Named is to be embedded by any resource that just needs to return a name.
type NoNativeConfig ¶ added in v0.2.36
type NoNativeConfig struct {
TriviallyValidateConfig
}
NoNativeConfig is used by types that have no significant native config.
type RPCAPI ¶ added in v0.2.36
type RPCAPI struct { API API ProtoSvcName string Desc *desc.ServiceDescriptor }
An RPCAPI provides RPC information about a particular API.
type Registration ¶ added in v0.2.36
type Registration[ResourceT Resource, ConfigT any] struct { Constructor Create[ResourceT] // AttributeMapConverter is used to convert raw attributes to the resource's native config. AttributeMapConverter AttributeMapConverter[ConfigT] // An AssocationConfigLinker describes how to associate a // resource association config to a specific resource model (e.g. builtin data capture). AssociatedConfigLinker LinkAssocationConfig[ConfigT] // TODO(RSDK-418): remove this legacy constructor once all resources that use it no longer need to receive the entire robot. DeprecatedRobotConstructor DeprecatedCreateWithRobot[ResourceT] // Not for public use yet; currently experimental WeakDependencies []internal.ResourceMatcher // Discover looks around for information about this specific model. Discover DiscoveryFunc // contains filtered or unexported fields }
A Registration stores construction info for a resource (component/service). A single constructor is mandatory.
func LookupRegistration ¶ added in v0.2.36
func LookupRegistration(api API, model Model) (Registration[Resource, ConfigValidator], bool)
LookupRegistration looks up a creator by the given api and model. nil is returned if there is no creator registered.
func (Registration[ResourceT, ConfigT]) ConfigReflectType ¶ added in v0.2.36
func (r Registration[ResourceT, ConfigT]) ConfigReflectType() reflect.Type
ConfigReflectType returns the reflective resource config type.
type Resource ¶ added in v0.2.36
type Resource interface { Name() Name // Reconfigure must reconfigure the resource atomically and in place. If this // cannot be guaranteed, then usage of AlwaysRebuild or TriviallyReconfigurable // is permissible. Reconfigure(ctx context.Context, deps Dependencies, conf Config) error // DoCommand sends/receives arbitrary data DoCommand(ctx context.Context, cmd map[string]interface{}) (map[string]interface{}, error) // Close must safely shut down the resource and prevent further use. // Close must be idempotent. // Later reconfiguration may allow a resource to be "open" again. Close(ctx context.Context) error }
A Resource is the fundamental building block of a robot; it is either a component or a service that is accessible through robot. In general, some other specific type that is the component or service implements this interface. All resources must know their own name and be able to reconfigure themselves (or signal that they must be rebuilt). Resources that fail to reconfigure or rebuild may be closed and must return errors when in a closed state for all non Close methods.
type ResponseMetadata ¶ added in v0.7.3
ResponseMetadata contains extra info associated with a Resource's standard response.
func ResponseMetadataFromProto ¶ added in v0.7.3
func ResponseMetadataFromProto(proto *commonpb.ResponseMetadata) ResponseMetadata
ResponseMetadataFromProto turns the protobuf message into a ResponseMetadata struct.
func (ResponseMetadata) AsProto ¶ added in v0.7.3
func (rm ResponseMetadata) AsProto() *commonpb.ResponseMetadata
AsProto turns the ResponseMetadata struct into a protobuf message.
type Shaped ¶ added in v0.2.50
type Shaped interface { // Geometries returns the list of geometries associated with the resource, in any order. The poses of the geometries reflect their // current location relative to the frame of the resource. Geometries(context.Context, map[string]interface{}) ([]spatialmath.Geometry, error) }
Shaped is any resource that can have geometries.
type TriviallyCloseable ¶ added in v0.2.36
type TriviallyCloseable struct{}
TriviallyCloseable is to be embedded by any resource that does not care about handling Closes. When is used, it is assumed that the resource does not need to return errors when furture non-Close methods are called.
type TriviallyReconfigurable ¶ added in v0.2.36
type TriviallyReconfigurable struct{}
TriviallyReconfigurable is to be embedded by any resource that does not care about changes to its config or dependencies.
func (TriviallyReconfigurable) Reconfigure ¶ added in v0.2.36
func (t TriviallyReconfigurable) Reconfigure(ctx context.Context, deps Dependencies, conf Config) error
Reconfigure always succeeds.
type TriviallyValidateConfig ¶ added in v0.2.36
type TriviallyValidateConfig struct{}
TriviallyValidateConfig is to be embedded by any resource config that does not care about its validation or implicit dependencies; use this carefully.