NavState Class Reference

A generic, type-safe, thread-safe blackboard to hold runtime state. More...

#include <NavState.hpp>

Public Types
using	AnyPrinter = std::function<std::string(std::shared_ptr<void>)>
	Type alias for a generic printer functor used by debug_string().

Public Member Functions
void	add_to_group (const std::string &group_key, const std::string &key)
	Adds key to the group group_key (created if missing), atomically: safe when several threads add members to the same group.
std::string	debug_string () const
	Generates a human-readable dump of all stored keys and values.
template<typename T>
const T &	get (const std::string &key) const
	Retrieves a const reference to the stored value of type T for key.
template<typename T>
std::vector< std::shared_ptr< T > >	get_by_type () const
	Retrieves all stored values of type T, regardless of their key.
template<typename T>
const std::vector< std::shared_ptr< T > >	get_group (const std::string &group_key) const
	Retrieves a vector of values (pointers) from a group by the group key.
std::vector< std::string >	get_group_keys (const std::string &group_key) const
	Member keys of group_key, as recorded by set_group() (without dereferencing them).
template<typename T>
std::vector< std::shared_ptr< T > >	get_no_group () const
	Retrieves all stored values of type T that are NOT a member of any group.
template<typename T>
const std::shared_ptr< T >	get_ptr (const std::string &key) const
	Retrieves the shared_ptr to the stored value of type T for key.
template<typename T>
T	get_safe (const std::string &key) const
	Retrieves a snapshot copy of the stored value of type T for key.
template<typename T>
std::vector< std::shared_ptr< T > >	get_to_vector (const std::string &key) const
	Wraps a single stored value of type T in a one-element vector.
bool	has (const std::string &key) const
	Checks whether key exists in the state.
bool	has_group (const std::string &key) const
	Checks whether key exists in the state.
	NavState ()
	Constructs an empty NavState and registers basic type printers.
template<typename T>
void	set (const std::string &key, const std::shared_ptr< T > value_ptr)
	Stores a value of type T associated with key (by shared pointer).
template<typename T>
void	set (const std::string &key, const T &value)
	Stores a value of type T associated with key (by copy).
void	set_group (const std::string &key, const std::vector< std::string > &group_keys)
	Sets a new group of values as a list of strings.
virtual	~NavState ()=default
	Destructor.

Static Public Member Functions
static void	print_stacktrace ()
	Prints the current C++ stack trace to std::cerr.
static void	register_basic_printers ()
	Registers default printers for common scalar types.
template<typename T>
static void	register_printer (std::function< std::string(const T &)> printer)
	Registers a pretty-printer for type T used by debug_string().

Detailed Description

A generic, type-safe, thread-safe blackboard to hold runtime state.

NavState provides:

• Type-erased storage using std::shared_ptr<void>.
• Runtime type verification and safe casting via typeid.
• Support for value-based and shared-pointer-based insertion.
• Debug utilities including stack trace and introspection.

Note

Thread-safety is enforced with an internal std::mutex.

Member Typedef Documentation

AnyPrinter

using AnyPrinter = std::function<std::string(std::shared_ptr<void>)>

Type alias for a generic printer functor used by debug_string().

The functor receives the stored value as a std::shared_ptr<void> and returns a string representation.

Constructor & Destructor Documentation

NavState()

NavState

(

)

Constructs an empty NavState and registers basic type printers.

~NavState()

virtual ~NavState ( )

virtualdefault

Destructor.

Member Function Documentation

add_to_group()

void add_to_group	(	const std::string &	group_key,
		const std::string &	key )

Adds key to the group group_key (created if missing), atomically: safe when several threads add members to the same group.

Nothing happens if it is already a member.

debug_string()

std::string debug_string

(

)

const

Generates a human-readable dump of all stored keys and values.

For types with registered printers, their printer is used; otherwise, the raw pointer address and type hash are shown.

Returns

Multi-line string with one entry per key.

get()

template<typename T>

const T & get

(

const std::string &

key

)

const

Retrieves a const reference to the stored value of type T for key.

The reference refers to the object managed by the internal std::shared_ptr<T>.

Template Parameters

T	Expected stored type.

Parameters

key	Key to retrieve.

Returns

Const reference to the stored T.

Exceptions

std::runtime_error

If key is missing or the stored type does not match T.

get_by_type()

template<typename T>

std::vector< std::shared_ptr< T > > get_by_type

(

)

const

Retrieves all stored values of type T, regardless of their key.

Scans every entry in the state and returns those whose stored type matches T. Entries belonging to group-metadata keys (stored as std::vector<std::string>) are automatically excluded because their type hash will not match T.

Template Parameters

T	Expected stored type.

Returns

Vector of shared_ptr to every stored T. Empty if none are found.

get_group()

template<typename T>

const std::vector< std::shared_ptr< T > > get_group

(

const std::string &

group_key

)

const

Retrieves a vector of values (pointers) from a group by the group key.

The value pointers refer to the object managed by the internal std::shared_ptr<T>.

Template Parameters

T	Expected stored type.

Parameters

group_key

Group key to retrieve.

Returns

vector of shared_ptr to the stored T.

Exceptions

std::runtime_error

If any key is missing or the stored type does not match T.

get_group_keys()

std::vector< std::string > get_group_keys

(

const std::string &

group_key

)

const

Member keys of group_key, as recorded by set_group() (without dereferencing them).

Useful to grow a group incrementally.

Returns

The member keys, or an empty vector if the group does not exist.

get_no_group()

template<typename T>

std::vector< std::shared_ptr< T > > get_no_group

(

)

const

Retrieves all stored values of type T that are NOT a member of any group.

This is the complement of get_group: it returns every entry whose type matches T and whose key does not appear in any group's member list. Group-metadata keys (the std::vector<std::string> stored by set_group) are excluded by type, so they will never appear in results unless T is std::vector<std::string>.

Template Parameters

T	Expected stored type.

Returns

Vector of shared_ptr to every ungrouped T. Empty if none are found.

get_ptr()

template<typename T>

const std::shared_ptr< T > get_ptr

(

const std::string &

key

)

const

Retrieves the shared_ptr to the stored value of type T for key.

The pointer refers to the object managed by the internal std::shared_ptr<T>.

Template Parameters

T	Expected stored type.

Parameters

key	Key to retrieve.

Returns

shared_ptr to the stored T.

Exceptions

std::runtime_error

If key is missing or the stored type does not match T.

get_safe()

template<typename T>

T get_safe

(

const std::string &

key

)

const

Retrieves a snapshot copy of the stored value of type T for key.

Unlike get(), which returns a reference to the object owned by the internal std::shared_ptr<T> (only valid for as long as no other thread calls set() on the same key), this makes the copy of T while state_mutex_ is still held, so the returned value is a stable, independent snapshot regardless of concurrent writers.

Use this instead of get() whenever the key can be written from a different thread than the one calling this method (for example, values crossing the RT / non-RT boundary, such as "path", "goals", "robot_pose" or "navigation_state"). Prefer get() when the writer and reader are known to run on the same thread (for example, most maps stored by a maps manager and consumed by a localizer/planner on the non-RT cycle) to avoid paying an unnecessary copy for potentially large values.

Template Parameters

T	Expected stored type.

Parameters

key	Key to retrieve.

Returns

An independent copy of the stored T.

Exceptions

std::runtime_error

If key is missing or the stored type does not match T.

get_to_vector()

template<typename T>

std::vector< std::shared_ptr< T > > get_to_vector

(

const std::string &

key

)

const

Wraps a single stored value of type T in a one-element vector.

Convenience to allow uniform code that always works with std::vector<std::shared_ptr<T>> regardless of whether the caller has one sensor or many (via get_group).

• If key is not found or the stored type does not match T, returns an empty vector.

Template Parameters

T	Expected stored type.

Parameters

key	Key of the individual value to retrieve.

Returns

A one-element vector with the shared_ptr to T, or empty on miss/mismatch.

has()

bool has

(

const std::string &

key

)

const

Checks whether key exists in the state.

Parameters

key	Key to query.

Returns

true if present, otherwise false.

has_group()

bool has_group

(

const std::string &

key

)

const

Checks whether key exists in the state.

Parameters

key	Key to query.

Returns

true if present, otherwise false.

print_stacktrace()

void print_stacktrace ( )

static

Prints the current C++ stack trace to std::cerr.

Note

Intended for debugging in exception contexts.

register_basic_printers()

void register_basic_printers ( )

static

Registers default printers for common scalar types.

Registers printers for: int, float, double, std::string, bool, char.

register_printer()

template<typename T>

void register_printer ( std::function< std::string(const T &)> printer )

static

Registers a pretty-printer for type T used by debug_string().

Template Parameters

T	Type to register.

Parameters

printer

Functor that renders const T& to a string.

set() [1/2]

template<typename T>

void set	(	const std::string &	key,
		const std::shared_ptr< T >	value_ptr )

Stores a value of type T associated with key (by shared pointer).

If key does not exist, value_ptr is stored directly. If key exists, the stored std::shared_ptr<T> is replaced by value_ptr.

Template Parameters

T	Value type.

Parameters

key	Key associated with the value.
value_ptr	Shared pointer to the value to store.

Exceptions

std::runtime_error

If key exists with a different stored type; includes a stack trace.

set() [2/2]

template<typename T>

void set	(	const std::string &	key,
		const T &	value )

Stores a value of type T associated with key (by copy).

If key does not exist, a new std::shared_ptr<T> is created and stored. If key exists, the stored value is overwritten in place.

Template Parameters

T	Value type. Must be copy-assignable.

Parameters

key	Key associated with the value.
value	Value to store (copied into internal storage).

Exceptions

std::runtime_error

If key exists with a different stored type; includes a stack trace.

set_group()

void set_group	(	const std::string &	key,
		const std::vector< std::string > &	group_keys )

Sets a new group of values as a list of strings.

It aslo stores the group keys as a value for introspection/debugging purposes. The group consists of a vector of keys, where each key points to a NavState element.

If key does not exist, a new list is created and stored. If key exists, the stored list is overwritten in place.

Parameters

key	Key associated with the group.
group_keys	Value to store. The list of other keys in the NavState that compose this group.

---

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

• easynav_common/include/easynav_common/types/NavState.hpp