CacheInsertPolicyInterface< KeyT, ValueT, CacheEntryT > Class Reference

Abstract class for injecting logic for determining when to prune and insert a cache entry, and what metadata to attach to the cache entry. More...

#include <cache_insert_policy_interface.hpp>

Detailed Description

Abstract class for injecting logic for determining when to prune and insert a cache entry, and what metadata to attach to the cache entry.

"moveit/trajectory_cache/cache_insert_policies/cache_insert_policy_interface.hpp"

Template Parameters

KeyT.	The object to extract features from which to key the cache. Typically the plan request.
ValueT.	The object that the TrajectoryCache was passed to insert. Typically the plan response.
CacheEntryT.	The object stored in the cache entry.

Notably, implementations of this interface are used to determine all the logic leading up to, but not including, the insert call itself.

Additionally, the choice of which implementation to use will constraint the set of FeaturesInterface<FeatureSourceT> implementations that can be used to fetch cache entries with, with a caveat mentioned later.

Users may implement this interface to add additional cache insertion functionality beyond the ones provided by this package (e.g., prioritizing minimum jerk, or minimal path length), and the set of metadata considered when inserting the cache entry.

See also

TrajectoryCache

FeaturesInterface<FeatureSourceT>

Usage ^^^^^ Each policy makes certain decisions about what pieces of metadata to attach to the cache entry for later fetching.

As such, an implementation will necessarily constrain the set of FeaturesInterface<FeatureSourceT> implementations that can be used to fetch entries from the cache that were tagged by a policy.

There is no way to meaningfully express this coupling at compile time, so users must ensure that they read the documentation of each implementation of the interface to determine what FeaturesInterface<FeatureSourceT> implementations can be used with cache entries processed by the implementation.

Two mitigations may be applied to alleviate this:

1. Implementations of this interface may expose helper methods that can be called at runtime that take in arbitrary configuration parameters to them initialize the features that are used to fetch cache entries at point of use.

2. The TrajectoryCache class' insertion methods allow the bubbling down of additional user-specified features to be appended by the TrajectoryCache independent of a policy, which can be used to support features that are not explicitly supported by the policy.

   Care must be taken to ensure that there are no overlaps when doing so, though, because it could potentially result in duplicate metadata entries otherwise.

Consequently, a set of FeaturesInterface<FeatureSourceT> implementations can be used to fetch a cache entry if that set is a subset of the union of:

• The additional_features passed to TrajectoryCache
• The features used by a policy to append metadata to the cache entry

Pruning and Insertion ^^^^^^^^^^^^^^^^^^^^^ Pruning is a two step process:

1. Fetch all "matching" cache entries, as defined by the policy
2. From the fetched "matching" entries, subject each to the shouldPruneMatchingEntry method, again defined by the policy.

This allows a user to define a policy to match and prune on any arbitrary properties of the cache entries and insertion candidate.

Similarly, logic can be injected to determine when the insertion candidate should be inserted.

NOTE: The TrajectoryCache class also has some top-level logic to preserve cache entries that would have been pruned.

Stateful Policies ^^^^^^^^^^^^^^^^^ Finally, as there can be information that must be preserved across the multiple steps of the match-prune-insert process, this interface assumes stateful operation within a single insert call.

For example, preserving information in state will be required to propagate aggregated or rollup information about the entire set of matched cache entries to future calls.

The TrajectoryCache will call reset() on the policy at the end of the insert call.

Call Flow ^^^^^^^^^ The TrajectoryCache will call the following interface methods in the following order:

1. sanitize, once
2. fetchMatchingEntries, once
3. shouldPruneMatchingEntry, once per fetched entry from fetchMatchingEntries
4. shouldInsert, once
5. appendInsertMetadata, once, if shouldInsert returns true
6. reset, once, at the end.

---

The documentation for this class was generated from the following file:

• moveit_ros/trajectory_cache/include/moveit/trajectory_cache/cache_insert_policies/cache_insert_policy_interface.hpp