Abstract interface providing basic read and write facilities to a repository. More...

#include <rtctk/componentFramework/repositoryIf.hpp>

Inheritance diagram for rtctk::componentFramework::RepositoryIf:

Classes
class	AccessOutOfBounds

class	BatchRequest
	An object representing one or more asynchronous I/O requests to a repository. More...

class	BatchResponse

class	BufferTooSmall

class	DataPointAlreadyExists

class	DataPointDoesNotExist

class	IncompatibleType

class	MetaData
	Class for passing/receiving metadata to/from the repository. More...

class	MultipleRequestsFailed

class	OperationNotAllowed

class	ReadRequest
	A request object to pass information about datapoints that should be read from the repository. More...

class	Response
	An object used to wait for a request to complete. More...

class	ServiceFailure

class	UnsupportedType

class	WriteRequest
	A request object to pass information about datapoints that should be written to the repository. More...

Public Types
using	PathList = std::vector<DataPointPath>

using	Clock = taiclock::TaiClock

using	Timestamp = Clock::time_point

using	CallbackType = std::function<void(const DataPointPath&)>
	Signature of the callback functions that can be registered with the repository requests.

Public Member Functions
	RepositoryIf ()=default

virtual	~RepositoryIf ()=default

BatchResponse	SendRequest (const BatchRequest &request)

BatchResponse	SendRequest (const BatchRequest &request) const

template<typename T >
void	CreateDataPoint (const DataPointPath &path)
	Creates a new datapoint in the repository.

template<typename T >
void	CreateDataPoint (const DataPointPath &path, const T &initial_value)
	Creates a new datapoint in the repository with an initial value.

void	CreateDataPoint (const DataPointPath &path, const char *initial_value)

void	DeleteDataPoint (const DataPointPath &path, bool recurse=false)
	Deletes a datapoint.

const std::type_info &	GetDataPointType (const DataPointPath &path) const
	Fetches the type of the datapoint.

size_t	GetDataPointSize (const DataPointPath &path) const
	Fetches the size of the datapoint's data.

RtcVectorUInt64	GetDataPointShape (const DataPointPath &path) const
	Fetches the shape of the datapoint's data.

bool	DataPointExists (const DataPointPath &path) const
	Checks for the existence of a datapoint in the repository.

std::pair< PathList, PathList >	GetChildren (const DataPointPath &path, bool recurse=false) const
	Queries the child datapoints and paths for a given parent path.

template<typename T >
T	GetDataPoint (const DataPointPath &path) const
	Fetches a datapoint from the repository.

template<typename T >
void	SetDataPoint (const DataPointPath &path, const T &value)
	Sets a datapoint in the repository.

void	SetDataPoint (const DataPointPath &path, const char *value)

template<typename T >
void	ReadDataPoint (const DataPointPath &path, T &buffer) const
	Reads a datapoint from the repository.

template<typename T >
void	WriteDataPoint (const DataPointPath &path, const T &buffer)
	Writes a datapoint to the repository.

void	WriteDataPoint (const DataPointPath &path, const char *buffer)

template<typename... T>
void	WriteDataPoints (const T &... args)

template<typename... T>
void	ReadDataPoints (T &... args) const

virtual void	CreateDataPoint (const DataPointPath &path, const std::type_info &type)
	Creates a new datapoint in the repository with a specified type.

virtual Response	SendReadRequest (const ReadRequest &request) const
	Sends a request to read data from the repository.

virtual Response	SendWriteRequest (const WriteRequest &request)
	Sends a request to write data to the repository.

Static Public Member Functions
static const std::type_info &	StringToType (const std::string &arg)
	Converts an RTC type string to a type_info.

static std::string	TypeToString (const std::type_info &arg)
	Converts a type_info to an RTC type string.

Protected Types
using	RequestList = std::vector<std::any>

Protected Member Functions
virtual BatchResponse	ProcessRequests (const RequestList &requests)=0

virtual void	DeleteDataPointLegacy (const DataPointPath &path)
	Deletes a datapoint.

virtual const std::type_info &	GetDataPointTypeLegacy (const DataPointPath &path) const
	Fetches the type of the datapoint.

virtual size_t	GetDataPointSizeLegacy (const DataPointPath &path) const
	Fetches the size of the datapoint's data.

virtual bool	DataPointExistsLegacy (const DataPointPath &path) const
	Checks for the existence of a datapoint in the repository.

virtual std::pair< PathList, PathList >	GetChildrenLegacy (const DataPointPath &path) const
	Queries the datapoints and child paths for a given path.

Detailed Description

Abstract interface providing basic read and write facilities to a repository.

Note: All adapter implementations of this interface must ensure thread safety of this API.

Thread Safety: thread-safe

Member Typedef Documentation

◆ CallbackType

using rtctk::componentFramework::RepositoryIf::CallbackType = std::function<void(const DataPointPath&)>

Signature of the callback functions that can be registered with the repository requests.

◆ Clock

using rtctk::componentFramework::RepositoryIf::Clock = taiclock::TaiClock

◆ PathList

using rtctk::componentFramework::RepositoryIf::PathList = std::vector<DataPointPath>

◆ RequestList

using rtctk::componentFramework::RepositoryIf::RequestList = std::vector<std::any>

protected

◆ Timestamp

using rtctk::componentFramework::RepositoryIf::Timestamp = Clock::time_point

Constructor & Destructor Documentation

◆ RepositoryIf()

rtctk::componentFramework::RepositoryIf::RepositoryIf ( )

default

◆ ~RepositoryIf()

virtual rtctk::componentFramework::RepositoryIf::~RepositoryIf ( )

virtualdefault

Member Function Documentation

◆ CreateDataPoint() [1/4]

template<typename T >

void rtctk::componentFramework::RepositoryIf::CreateDataPoint ( const DataPointPath & path )

Creates a new datapoint in the repository.

The type of the datapoint is derived from the template argument type.

Template Parameters

T	The type of the datapoint to create. See RepositoryIf::CreateDataPoint for a list of supported types.

Parameters

[in] path The datapoint path that should be created.

Thread Safety: thread-safe

Exception Safety: basic

◆ CreateDataPoint() [2/4]

void rtctk::componentFramework::RepositoryIf::CreateDataPoint	(	const DataPointPath &	path,
		const char *	initial_value )

◆ CreateDataPoint() [3/4]

void rtctk::componentFramework::RepositoryIf::CreateDataPoint	(	const DataPointPath &	path,
		const std::type_info &	type )

virtual

Creates a new datapoint in the repository with a specified type.

Parameters

[in]	path	The datapoint path that should be created.
[in]	type	A type identifier object returned by `typeid` indicating the type of the new datapoint. Supported values are indicated below.

The following are the supported values for the type argument:

typeid(bool)
typeid(int32_t)
typeid(int64_t)
typeid(float)
typeid(double)
typeid(std::string)
typeid(std::vector<bool>)
typeid(std::vector<int32_t>)
typeid(std::vector<int64_t>)
typeid(std::vector<float>)
typeid(std::vector<double>)
typeid(std::vector<std::string>)
typeid(MatrixBuffer<bool>)
typeid(MatrixBuffer<int32_t>)
typeid(MatrixBuffer<int64_t>)
typeid(MatrixBuffer<float>)
typeid(MatrixBuffer<double>)
typeid(MatrixBuffer<std::string>)

Thread Safety: thread-safe

Exception Safety: basic

Deprecated: Use version that takes a default value instead.

Reimplemented in rtctk::componentFramework::OldbAdapterLegacy, rtctk::componentFramework::RuntimeRepoIf, rtctk::componentFramework::test::MockRepository, rtctk::componentFramework::test::MockRuntimeRepoIf, rtctk::componentFramework::OldbAdapterLegacy, and rtctk::componentFramework::RuntimeRepoAdapterLegacy.

◆ CreateDataPoint() [4/4]

template<typename T >

void rtctk::componentFramework::RepositoryIf::CreateDataPoint	(	const DataPointPath &	path,
		const T &	initial_value )

Creates a new datapoint in the repository with an initial value.

The type of the datapoint is derived from the template argument type.

Template Parameters

T	The type of the datapoint to create. See RepositoryIf::CreateDataPoint for a list of supported types.

Parameters

[in]	path	The datapoint path that should be created.
[in]	initial_value	The initial value that should be set for the new datapoint.

Thread Safety: thread-safe

Exception Safety: basic

◆ DataPointExists()

bool rtctk::componentFramework::RepositoryIf::DataPointExists ( const DataPointPath & path ) const

Checks for the existence of a datapoint in the repository.

Parameters

[in] path The datapoint path to check.

Returns: true if the datapoint path exists in the repository and false otherwise.

Thread Safety: thread-safe

Exception Safety: strong

◆ DataPointExistsLegacy()

bool rtctk::componentFramework::RepositoryIf::DataPointExistsLegacy ( const DataPointPath & path ) const

protectedvirtual

Checks for the existence of a datapoint in the repository.

Parameters

[in] path The datapoint path to check.

Returns: true if the datapoint path exists in the repository and false otherwise.

Thread Safety: thread-safe

Exception Safety: strong

Deprecated: Use DataPointExists instead.

Reimplemented in rtctk::componentFramework::OldbAdapterLegacy.

◆ DeleteDataPoint()

void rtctk::componentFramework::RepositoryIf::DeleteDataPoint	(	const DataPointPath &	path,
		bool	recurse = false )

Deletes a datapoint.

Parameters

[in]	path	The path of the datapoint to delete in the repository.
[in]	recurse	Optional flag indicating if datapoints should be deleted recursively.

Thread Safety: thread-safe

Exception Safety: basic

◆ DeleteDataPointLegacy()

void rtctk::componentFramework::RepositoryIf::DeleteDataPointLegacy ( const DataPointPath & path )

protectedvirtual

Deletes a datapoint.

Parameters

[in] path The path of the datapoint to delete in the repository.

Thread Safety: thread-safe

Exception Safety: basic

Deprecated: Use DeleteDataPoint instead.

Reimplemented in rtctk::componentFramework::OldbAdapterLegacy.

◆ GetChildren()

std::pair< RepositoryIf::PathList, RepositoryIf::PathList > rtctk::componentFramework::RepositoryIf::GetChildren	(	const DataPointPath &	path,
		bool	recurse = false ) const

Queries the child datapoints and paths for a given parent path.

This method will synchronously query all the available datapoints that are leaf nodes immediately below the given path and also the non-leaf child paths, i.e. sub-folders when interpreting the repository as a hierarchical folder like structure.

The set of datapoint and child paths is returned as two separate lists. If recurse is false then only the immediate children are returned. Otherwise all datapoint and child sub-folder paths are returned recursively.

Note: The contests of the returned path lists are not necessarily ordered, i.e. no assumption should be made on the ordering.

Parameters

[in]	path	The path in which to search for datapoints and child paths.
[in]	recurse	Optional flag indicating if paths should be queried recursively.

Returns: A std::pair of path lists, with the first list in the pair containing the datapoints found and the second list containing the child paths found. If no datapoints are found then the list for datapoints is empty. Similarly if not child paths are found then the child path list is empty.

Exceptions

PathNotFound	If the path does not exist in the repository.
ServiceFailure	When the underlying back-end system indicates an unexpected failure.

Thread Safety: thread-safe

Exception Safety: strong

◆ GetChildrenLegacy()

std::pair< RepositoryIf::PathList, RepositoryIf::PathList > rtctk::componentFramework::RepositoryIf::GetChildrenLegacy ( const DataPointPath & path ) const

protectedvirtual

Queries the datapoints and child paths for a given path.

This method will query all the available datapoints that are leaf nodes immediately below the given path and also the child paths, i.e. sub-folders when interpreting the repository as a hierarchical folder like structure. The set of immediate datapoint and child paths is returned as two separate lists.

If an error occurs when querying the the repository a rtctk::componentFramework::RtctkException is thrown.

Parameters

[in] path The path in which to search for datapoints and child paths.

Returns: A std::pair of path lists, i.e. std::vector<DataPointPath>, with the first list in the pair containing the datapoints found and the second list containing the child paths found. If no datapoints are found then the list for datapoints is empty. Similarly if not child paths are found then the child path list is empty.

Thread Safety: thread-safe

Exception Safety: strong

Deprecated: Use GetChildren instead.

Reimplemented in rtctk::componentFramework::OldbAdapterLegacy.

◆ GetDataPoint()

template<typename T >

T rtctk::componentFramework::RepositoryIf::GetDataPoint ( const DataPointPath & path ) const

Fetches a datapoint from the repository.

The datapoint is read from the repository and returned. If an error occurs then a rtctk::componentFramework::RtctkException is thrown.

Note: This method blocks while waiting for the read request from the repository to complete.

Parameters

[in] path The path of the datapoint that should be fetched from the repository.

Returns: The datapoint's value.

Thread Safety: thread-safe

Exception Safety: basic

◆ GetDataPointShape()

RtcVectorUInt64 rtctk::componentFramework::RepositoryIf::GetDataPointShape ( const DataPointPath & path ) const

Fetches the shape of the datapoint's data.

This method will return one of the following values depending on the category of the datapoint's type:

Scalars: Will always return an empty vector.
Strings: Will return a vector with size 1, where result[0] is the length of the string, i.e. the number of characters in the string.
Vectors: Will return a vector with size 1, where result[0] is the number of elements in the vector.
Matrices: Will return a vector with size 2, where result[0] is the number of rows and result[1] is the number of columns.

Parameters

[in] path The datapoint path for which to fetch the shape.

Returns: A vector describing the shape of the datapoint's data.

Thread Safety: thread-safe

Exception Safety: strong

◆ GetDataPointSize()

size_t rtctk::componentFramework::RepositoryIf::GetDataPointSize ( const DataPointPath & path ) const

Fetches the size of the datapoint's data.

This method will return one of the following values depending on the category of the datapoint's type:

Scalars: Will always return 1 for scalars such as RtcBool, RtcInt32, RtcInt64, RtcFloat, and RtcDouble.
Strings: Will return the length of the string, i.e. the number of characters in the string.
Vectors: Will return the number of elements in the vector.
Matrices: Will return the total number of elements in the matrix, i.e. the number of rows times the number of columns.

Parameters

[in] path The datapoint path for which to fetch the size.

Returns: The number of elements in the datapoint's data.

Thread Safety: thread-safe

Exception Safety: strong

◆ GetDataPointSizeLegacy()

size_t rtctk::componentFramework::RepositoryIf::GetDataPointSizeLegacy ( const DataPointPath & path ) const

protectedvirtual

Fetches the size of the datapoint's data.

This method will return one of the following values depending on the category of the datapoint's type:

Scalars: Will always return 1 for scalars such as RtcBool, RtcInt32, RtcInt64, RtcFloat, and RtcDouble.
Strings: Will return the length of the string, i.e. the number of characters in the string.
Vectors: Will return the number of elements in the vector.
Matrices: Will return the total number of elements in the matrix, i.e. the number of rows times the number of columns.

Returns: The number of elements in the datapoint's data.

Thread Safety: thread-safe

Exception Safety: strong

Deprecated: Use GetDataPointSize instead.

Reimplemented in rtctk::componentFramework::OldbAdapterLegacy.

◆ GetDataPointType()

const std::type_info & rtctk::componentFramework::RepositoryIf::GetDataPointType ( const DataPointPath & path ) const

Fetches the type of the datapoint.

This will return the type used when the datapoint was created with the CreateDataPoint method.

Parameters

[in] path The datapoint path for which to fetch the type.

Returns: The type_info object corresponding to the type of the datapoint.

Thread Safety: thread-safe

Exception Safety: strong

◆ GetDataPointTypeLegacy()

const std::type_info & rtctk::componentFramework::RepositoryIf::GetDataPointTypeLegacy ( const DataPointPath & path ) const

protectedvirtual

Fetches the type of the datapoint.

This will return the type used when the datapoint was created with the CreateDataPoint method.

Returns: The type_info object corresponding to the type of the datapoint.

Thread Safety: thread-safe

Exception Safety: strong

Deprecated: Use GetDataPointType instead.

Reimplemented in rtctk::componentFramework::OldbAdapterLegacy.

◆ ProcessRequests()

virtual BatchResponse rtctk::componentFramework::RepositoryIf::ProcessRequests ( const RequestList & requests )

protectedpure virtual

Implemented in rtctk::componentFramework::OldbAdapter, rtctk::componentFramework::RuntimeRepoAdapter, rtctk::componentFramework::test::FakeRepository, rtctk::componentFramework::test::MockRepository, and rtctk::componentFramework::test::MockRuntimeRepoIf.

◆ ReadDataPoint()

template<typename T >

void rtctk::componentFramework::RepositoryIf::ReadDataPoint	(	const DataPointPath &	path,
		T &	buffer ) const

Reads a datapoint from the repository.

Fetches the data for a datapoint from the repository and updates a local buffer in-place. If an error occurs then a rtctk::componentFramework::RtctkException is thrown.

Note: This method blocks while waiting for the data to be received from the repository.

Parameters

[in]	path	The path of the datapoint that should be fetched from the repository.
[in]	buffer	A reference to the local buffer that should be filled with the received data.

Thread Safety: thread-safe

Exception Safety: basic

◆ ReadDataPoints()

template<typename... T>

void rtctk::componentFramework::RepositoryIf::ReadDataPoints ( T &... args ) const

◆ SendReadRequest()

RepositoryIf::Response rtctk::componentFramework::RepositoryIf::SendReadRequest ( const ReadRequest & request ) const

virtual

Sends a request to read data from the repository.

This method allows non-blocking and asynchronous reading of datapoints form the repository. The method returns immediately, allowing other work to be done in the calling thread while the read request is completed in the background. If any callback handlers were registered in request, they will be called as soon as the data is available for the respective datapoint.

Note: The buffers for the datapoints added to request must not be accessed until the Wait method of the response object returns successfully, i.e. without a timeout.

If an error occurs then a rtctk::componentFramework::RtctkException is thrown.

Note: This method is not transactional or fully atomic. If an error occurs while reading the datapoints, some or all of the datapoint buffers registered with the read request may be left unmodified. It is however guaranteed that any particular datapoint buffer is either updated completely or not modified at all.

Parameters

[in] request The request object that contains all the datapoints to read.

Returns: A response object that must be used to synchronise with the completion of the read request.

Deprecated: Use SendRequest instead.

Reimplemented in rtctk::componentFramework::OldbAdapterLegacy.

◆ SendRequest() [1/2]

RepositoryIf::BatchResponse rtctk::componentFramework::RepositoryIf::SendRequest ( const BatchRequest & request )

◆ SendRequest() [2/2]

RepositoryIf::BatchResponse rtctk::componentFramework::RepositoryIf::SendRequest ( const BatchRequest & request ) const

◆ SendWriteRequest()

RepositoryIf::Response rtctk::componentFramework::RepositoryIf::SendWriteRequest ( const WriteRequest & request )

virtual

Sends a request to write data to the repository.

This method allows non-blocking writing of datapoints to the repository. The method returns immediately, allowing other work to be done in the calling thread while the write request is completed in the background. If any callback handlers were registered in request, they will be called as soon as the respective datapoint's data has been sent and the buffer will no longer be accessed by the API, i.e. the caller can modify or release the buffer from that point on.

Note: The buffers for the datapoints added to request must not be modified or released until the Wait method of the response object returns successfully, i.e. without a timeout.

If an error occurs then a rtctk::componentFramework::RtctkException is thrown.

Note: This method is not transactional or fully atomic. If an error occurs while writing the datapoints, only some of the datapoints registered with the write request may be actually updated in the repository. It is however guaranteed that any particular datapoint is either updated completely in the repository or not at all.

Parameters

[in] request The request object that contains all the datapoints to write.

Returns: A response object that must be used to synchronise with the completion of the write request.

Deprecated: Use SendRequest instead.

Reimplemented in rtctk::componentFramework::OldbAdapterLegacy.

◆ SetDataPoint() [1/2]

void rtctk::componentFramework::RepositoryIf::SetDataPoint	(	const DataPointPath &	path,
		const char *	value )

◆ SetDataPoint() [2/2]

template<typename T >

void rtctk::componentFramework::RepositoryIf::SetDataPoint	(	const DataPointPath &	path,
		const T &	value )

Sets a datapoint in the repository.

A new value for the datapoint is sent to the repository and updated. If an error occurs then a rtctk::componentFramework::RtctkException is thrown.

Note: This method blocks while waiting for the data to be sent to the repository.

Parameters

[in]	path	The path of the datapoint that should be updated in the repository.
[in]	value	The new data for the datapoint.

Thread Safety: thread-safe

Exception Safety: basic

◆ StringToType()

const std::type_info & rtctk::componentFramework::RepositoryIf::StringToType ( const std::string & arg )

static

Converts an RTC type string to a type_info.

Parameters

[in] arg The RTC type name string, e.g. RtcString

Returns: type_info of the resolved type

Exceptions

UnsupportedType If the type was not found.

◆ TypeToString()

std::string rtctk::componentFramework::RepositoryIf::TypeToString ( const std::type_info & arg )

static

Converts a type_info to an RTC type string.

Parameters

[in] arg The type_info to be resolved

Returns: RTC type name string, e.g. RtcString

Exceptions

UnsupportedType If the type was not found.

◆ WriteDataPoint() [1/2]

void rtctk::componentFramework::RepositoryIf::WriteDataPoint	(	const DataPointPath &	path,
		const char *	buffer )

◆ WriteDataPoint() [2/2]

template<typename T >

void rtctk::componentFramework::RepositoryIf::WriteDataPoint	(	const DataPointPath &	path,
		const T &	buffer )

Writes a datapoint to the repository.

Data is read from the buffer reference provided and sent to the repository to update the datapoint. If an error occurs then a rtctk::componentFramework::RtctkException is thrown.

This method is preferred over SetDataPoint for large vectors and matrices, since passing a reference to the buffer is more efficient.

Note: This method blocks while waiting for the data to be sent to the repository.

Parameters

[in]	path	The path of the datapoint that should be updated in the repository.
[in]	buffer	A reference to the new data for the datapoint.

Thread Safety: thread-safe

Exception Safety: basic

◆ WriteDataPoints()

template<typename... T>

void rtctk::componentFramework::RepositoryIf::WriteDataPoints ( const T &... args )

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

componentFramework/services/common/src/include/rtctk/componentFramework/repositoryIf.hpp
componentFramework/services/common/src/include/rtctk/componentFramework/repositoryIf.ipp
componentFramework/services/common/src/repositoryIf.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Types

Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ CallbackType

◆ Clock

◆ PathList

◆ RequestList

◆ Timestamp

Constructor & Destructor Documentation

◆ RepositoryIf()

◆ ~RepositoryIf()

Member Function Documentation

◆ CreateDataPoint() [1/4]

◆ CreateDataPoint() [2/4]

◆ CreateDataPoint() [3/4]

◆ CreateDataPoint() [4/4]

◆ DataPointExists()

◆ DataPointExistsLegacy()

◆ DeleteDataPoint()

◆ DeleteDataPointLegacy()

◆ GetChildren()

◆ GetChildrenLegacy()

◆ GetDataPoint()

◆ GetDataPointShape()

◆ GetDataPointSize()

◆ GetDataPointSizeLegacy()

◆ GetDataPointType()

◆ GetDataPointTypeLegacy()

◆ ProcessRequests()

◆ ReadDataPoint()

◆ ReadDataPoints()

◆ SendReadRequest()

◆ SendRequest() [1/2]

◆ SendRequest() [2/2]

◆ SendWriteRequest()

◆ SetDataPoint() [1/2]

◆ SetDataPoint() [2/2]

◆ StringToType()

◆ TypeToString()

◆ WriteDataPoint() [1/2]

◆ WriteDataPoint() [2/2]

◆ WriteDataPoints()