Abstract interface providing I/O and additional subscription facilities for a repository. More...

#include <rtctk/componentFramework/repositorySubscriberIf.hpp>

Inheritance diagram for rtctk::componentFramework::RepositorySubscriberIf:

Classes
class	BatchRequest

class	SequenceIdMissmatch

class	SubscribeRequest
	A request object to pass information about datapoints to subscribe to. More...

class	Subscription
	RAII wrapper class used to manage the life-time of individual subscriptions. More...

class	SubscriptionError

class	UnsubscribeRequest
	A request object to pass information about datapoints to unsubscribe from. More...

Public Types
template<typename T >
using	ValueCallbackType = std::function<void(const DataPointPath&, T&, const MetaData&)>

using	NotifyCallbackType = std::function<void(const DataPointPath&, const MetaData&)>

using	ErrorCallbackType = std::function<void(std::exception_ptr)>

using	SubscriptionId = size_t

Public Types inherited from rtctk::componentFramework::RepositoryIf
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
	RepositorySubscriberIf ()=default

virtual	~RepositorySubscriberIf ()=default

template<typename T = void, typename F , std::enable_if_t< std::is_convertible_v< F, NotifyCallbackType > or(not std::is_same_v< T, void > and std::is_convertible_v< F, ValueCallbackType< std::conditional_t< std::is_same_v< T, void >, std::byte, T > > >), bool > = true>
Subscription	Subscribe (const DataPointPath &path, const F &cb_value, const ErrorCallbackType &cb_error) const
	Subscribes to datapoint values change events by registering callbacks.

Subscription	Subscribe (const CallbackType &cb_created, const CallbackType &cb_deleted, const ErrorCallbackType &cb_error) const
	Subscribes to datapoint creation and deletion events by registering callbacks.

virtual RepositoryIf::Response	SendSubscribeRequest (const SubscribeRequest &request) const
	This is called to asynchronously send a subscription request for datapoints.

virtual RepositoryIf::Response	SendUnsubscribeRequest (const UnsubscribeRequest &request) const
	This is called to asynchronously send a request to unsubscribe from various notifications.

template<typename T , typename F , std::enable_if_t< not std::is_convertible_v< T, RepositorySubscriberIf::NotifyCallbackType >, bool > = true>
void	Subscribe (const DataPointPath &path, T &buffer, F handler) const
	A convenience template function that will register a callback to receive new datapoint values in a synchronous manner.

template<typename F >
void	Subscribe (const DataPointPath &path, F handler) const
	A convenience template function that will register a callback to receive datapoint value change notifications in a synchronous manner.

void	Unsubscribe (const DataPointPath &path) const
	A simple convenience function that will deregister all callbacks for receiving new datapoint values.

Public Member Functions inherited from rtctk::componentFramework::RepositoryIf
	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.

Friends
class	PyRepositorySubscriberIf

Additional Inherited Members
Static Public Member Functions inherited from rtctk::componentFramework::RepositoryIf
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 inherited from rtctk::componentFramework::RepositoryIf
using	RequestList = std::vector<std::any>

Protected Member Functions inherited from rtctk::componentFramework::RepositoryIf
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 I/O and additional subscription facilities for a repository.

Thread Safety: thread-safe

Member Typedef Documentation

◆ ErrorCallbackType

using rtctk::componentFramework::RepositorySubscriberIf::ErrorCallbackType = std::function<void(std::exception_ptr)>

◆ NotifyCallbackType

using rtctk::componentFramework::RepositorySubscriberIf::NotifyCallbackType = std::function<void(const DataPointPath&, const MetaData&)>

◆ SubscriptionId

using rtctk::componentFramework::RepositorySubscriberIf::SubscriptionId = size_t

◆ ValueCallbackType

template<typename T >

using rtctk::componentFramework::RepositorySubscriberIf::ValueCallbackType = std::function<void(const DataPointPath&, T&, const MetaData&)>

Constructor & Destructor Documentation

◆ RepositorySubscriberIf()

rtctk::componentFramework::RepositorySubscriberIf::RepositorySubscriberIf ( )

default

◆ ~RepositorySubscriberIf()

virtual rtctk::componentFramework::RepositorySubscriberIf::~RepositorySubscriberIf ( )

virtualdefault

Member Function Documentation

◆ SendSubscribeRequest()

RepositoryIf::Response rtctk::componentFramework::RepositorySubscriberIf::SendSubscribeRequest ( const SubscribeRequest & request ) const

virtual

This is called to asynchronously send a subscription request for datapoints.

One or more datapoints can be subscribed to by constructing a SubscribeRequest object and sending it to the repository service with this method. A typical usage is indicated in the following code sample:

void OnRemoved(const DataPointPath& path) {
  ...
}
void OnNewValue(const DataPointPath& path, int64_t& buffer) {
  ...
}
void OnValueChanged(const DataPointPath& path, int64_t& buffer) {
  ...
}
 
RepositorySubscriberIf& repo = ...;
int64_t buffer = ...;
SubscribeRequest request;
request.AddRemoveHandler("/test/datapoint"_dppath, OnRemoved);
request.AddNewValueHandler("/test/datapoint"_dppath, buffer, OnNewValue);
request.AddValueChangedHandler("/test/datapoint"_dppath, OnValueChanged);
auto response = repo.SendSubscribeRequest(request);
  ... can do some work here ...
response.Wait();

Note: One must not access the buffers added to a SubscribeRequest object once SendSubscribeRequest has been invoked. At least not without using some form of synchronisation, e.g. a mutex, since the buffers will be updated asynchronously in different threads to the one used by the caller.

Parameters

[in] request The subscription request to send to the repository.

Returns: A response object (a future) that is used to wait for completion of the request.

Thread Safety: thread-safe

Exception Safety: basic

Deprecated: Use SendRequest instead.

Reimplemented in rtctk::componentFramework::OldbAdapterLegacy.

◆ SendUnsubscribeRequest()

RepositoryIf::Response rtctk::componentFramework::RepositorySubscriberIf::SendUnsubscribeRequest ( const UnsubscribeRequest & request ) const

virtual

This is called to asynchronously send a request to unsubscribe from various notifications.

One can stop receiving notifications for one or more datapoints by constructing a UnsubscribeRequest object and sending it to the repository service with this method. A typical usage is indicated in the following code sample:

void OnRemoved(const DataPointPath& path) {
  ...
}
void OnNewValue(const DataPointPath& path, int64_t& buffer) {
  ...
}
 
RepositorySubscriberIf& repo = ...;
UnsubscribeRequest request;
request.AddRemoveHandler("/test/datapoint"_dppath);
request.AddNewValueHandler("/test/datapoint"_dppath);
auto response = repo.SendUnsubscribeRequest(request);
  ... can do some work here ...
response.Wait();

Parameters

[in] request The request to send to the repository.

Returns: A response object (a future) that is used to wait for completion of the request.

Thread Safety: thread-safe

Exception Safety: basic

Deprecated: Use SendRequest instead.

Reimplemented in rtctk::componentFramework::OldbAdapterLegacy.

◆ Subscribe() [1/4]

RepositorySubscriberIf::Subscription rtctk::componentFramework::RepositorySubscriberIf::Subscribe	(	const CallbackType &	cb_created,
		const CallbackType &	cb_deleted,
		const ErrorCallbackType &	cb_error ) const

Subscribes to datapoint creation and deletion events by registering callbacks.

This function can be used to register callback functions that will be called whenever a datapoint created or datapoint deleted notification is received.

Note: This method blocks until the registration has been completed for the datapoint.

Parameters

[in]	cb_created	A handler functional to invoke after a datapoint was created
[in]	cb_deleted	A handler functional to invoke after a datapoint was deleted
[in]	cb_error	A handler functional to invoke after a subscription error was detected.

Returns: A moveable subscription object that controls the life-time of the subscription

Thread Safety: thread-safe

Exception Safety: basic

◆ Subscribe() [2/4]

template<typename T , typename F , std::enable_if_t< std::is_convertible_v< F, RepositorySubscriberIf::NotifyCallbackType > or(not std::is_same_v< T, void > and std::is_convertible_v< F, RepositorySubscriberIf::ValueCallbackType< std::conditional_t< std::is_same_v< T, void >, std::byte, T > > >), bool > >

RepositorySubscriberIf::Subscription rtctk::componentFramework::RepositorySubscriberIf::Subscribe	(	const DataPointPath &	path,
		const F &	cb_value,
		const ErrorCallbackType &	cb_error ) const

Subscribes to datapoint values change events by registering callbacks.

This function can be used to register a callback function that will be called whenever a datapoint value change notification is received.

Note: This method blocks until the registration has been completed for the datapoint.

Template Parameters

T	The datapoint type
F	The type of the `handler` callback function. It can be any callable that has a function signature compatible with: void(const DataPointPath& path, T& buffer, const MetaData& metadata) rtctk::componentFramework::RepositoryIf::MetaData Class for passing/receiving metadata to/from the repository. Definition repositoryIf.hpp:195 or void(const DataPointPath& path, const MetaData& metadata)

Parameters

[in]	path	The path of the datapoint to subscribe to.
[in]	cb_value	A handler function, lambda or functional to invoke after a new datapoint value is received.
[in]	cb_error	A functional to invoke after a subscription error was detected.

Returns: A moveable subscription object that controls the life-time of the subscription

Thread Safety: thread-safe

Exception Safety: basic

◆ Subscribe() [3/4]

template<typename F >

void rtctk::componentFramework::RepositorySubscriberIf::Subscribe	(	const DataPointPath &	path,
		F	handler ) const

inline

A convenience template function that will register a callback to receive datapoint value change notifications in a synchronous manner.

This function can be used for simple cases to register a callback function that will be called when a new datapoint value change notification is received.

For a large number of datapoints it is better to use the SendSubscribeRequest method.

Note: This method blocks until the registration has been completed for the datapoint.

Template Parameters

F	The type of the `handler` callback function. It can be any callable that has a function signature compatible with: void(const DataPointPath& path)

Parameters

[in]	path	The path of the datapoint to subscribe to.
[in]	handler	A handler function, lambda or functional to invoke after a new datapoint value is received.

Thread Safety: thread-safe

Exception Safety: basic

Deprecated

◆ Subscribe() [4/4]

template<typename T , typename F , std::enable_if_t< not std::is_convertible_v< T, RepositorySubscriberIf::NotifyCallbackType >, bool > >

void rtctk::componentFramework::RepositorySubscriberIf::Subscribe	(	const DataPointPath &	path,
		T &	buffer,
		F	handler ) const

A convenience template function that will register a callback to receive new datapoint values in a synchronous manner.

This function can be used for simple cases to register a callback function that will be called when a new datapoint value is received. The buffer will be filled with the new value before invoking the callback. For a large number of datapoints it is better to use the SendSubscribeRequest method.

Note: This method blocks until the registration has been completed for the datapoint.

Template Parameters

T	The type of the output buffer, which must match the type of the datapoint.
F	The type of the `handler` callback function. It can be any callable that has a function signature compatible with: void(const DataPointPath& path, T& buffer)

Parameters

[in]	path	The path of the datapoint to subscribe to.
[out]	buffer	The buffer that will be filled with new data values.
[in]	handler	A handler function, lambda or functional to invoke after a new datapoint value is received.

Thread Safety: thread-safe

Exception Safety: basic

◆ Unsubscribe()

void rtctk::componentFramework::RepositorySubscriberIf::Unsubscribe ( const DataPointPath & path ) const

A simple convenience function that will deregister all callbacks for receiving new datapoint values.

This function can be used for simple cases to deregister all callback functions in a synchronous manner. For a large number of unsubscriptions it is better to use the SendUnsubscribeRequest method.

Note: This method blocks until the deregistration has been completed for the datapoint.

Parameters

[in] path The path of the datapoint to unsubscribe from.

Thread Safety: thread-safe

Exception Safety: basic

Deprecated

Friends And Related Symbol Documentation

◆ PyRepositorySubscriberIf

friend class PyRepositorySubscriberIf

friend

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

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

Classes

Public Types

Public Member Functions

Friends

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ ErrorCallbackType

◆ NotifyCallbackType

◆ SubscriptionId

◆ ValueCallbackType

Constructor & Destructor Documentation

◆ RepositorySubscriberIf()

◆ ~RepositorySubscriberIf()

Member Function Documentation

◆ SendSubscribeRequest()

◆ SendUnsubscribeRequest()

◆ Subscribe() [1/4]

◆ Subscribe() [2/4]

◆ Subscribe() [3/4]

◆ Subscribe() [4/4]

◆ Unsubscribe()

Friends And Related Symbol Documentation

◆ PyRepositorySubscriberIf