Common

Common services and utilities shared by other services. More...

Files
file	dataPointPath.cpp
	Implementation of DataPointPath.
file	exceptions.cpp
	Implementation of RTC Toolkit specific exception classes.
file	fitsIoFunctions.cpp
	Implementation of FITS I/O helper functions.
file	basicTypes.hpp
	Header file for basic type aliases.
file	dataPointPath.hpp
	Header file for DataPointPath.
file	dynamicThreadPool.hpp
	Header file for a dynamic resizing thread pool.
file	exceptions.hpp
	Provides macros and utilities for exception handling.
file	factoryRegistry.hpp
	Header file for FactoryRegistry and related helper classes.
file	factoryRegistry.ipp
	Implementation file for FactoryRegistry and related helper template classes.
file	fitsIoFunctions.hpp
	Declaration of FITS I/O helper functions.
file	influxTagMap.hpp
	Helper class for working with InfluxDB tags.
file	jsonPayload.hpp
	Defines the JSON payload type JsonPayload.
file	matrixBuffer.hpp
	Declaration of the MatrixBuffer template class used in APIs.
file	matrixSpan.hpp
	Declaration of the MatrixSpan template class used in APIs.
file	repositoryFactory.hpp
	Header file for RepositoryFactory.
file	repositoryFactory.ipp
	Implementation file for RepositoryFactory.
file	repositoryIf.hpp
	Header file for RepositoryIf and related base classes.
file	repositoryIf.ipp
	Implementation file for RepositoryIf template methods and related classes.
file	repositoryIfUtils.hpp
	Provides utilities to simplify use of RepositoryIf.
file	repositorySubscriberIf.hpp
	Header file for RepositorySubscriberIf and related base classes.
file	repositorySubscriberIf.ipp
	Implementation file for RepositorySubscriberIf template methods and related classes.
file	requestDispatcher.hpp
	Header file for the RequestDispatcher utility class.
file	serviceContainer.hpp
	A container that can hold any type of service.
file	serviceDiscovery.hpp
	Class that implements a very basic service discover mechanism.
file	serviceRegistryIf.hpp
	Class that implements the service registry interface.
file	stopToken.hpp
	A simple Stop Token.
file	timeParsing.hpp
	Utility functions for time.
file	timeString.hpp
	A timestring in ISO-8601 format.
file	typeTraits.hpp
	Provides useful mechanisms to test various type traits.
file	influxTagMap.cpp
	Implementation of InfluxTagMap.
file	repositoryIf.cpp
	Implementation of RepositoryIf.
file	repositoryIfUtils.cpp
	Implementation of RepositoryIf utilities.
file	repositorySubscriberIf.cpp
	Implementation of RepositorySubscriberIf.
file	serviceContainer.cpp
	Implementation of the ServiceContainer class.
file	serviceDiscovery.cpp
	Implementation of the ServiceDiscovery class.
file	serviceRegistryIf.cpp
	Implementation of the ServiceDiscovery class.
file	timeString.cpp
	An ISO-8601 time string implementation.
file	consulServiceRegistryAdapter.cpp
	Implementation of the Consul ServiceDiscovery class.
file	fileServiceRegistryAdapter.cpp
	Implementation of the ServiceDiscovery class.
file	consulServiceRegistryAdapter.hpp
	Header file for the ConsulServiceRegistryAdapter class.
file	fileServiceRegistryAdapter.hpp
	Class that implements a very basic service discover mechanism using a file.

Classes
class	rtctk::componentFramework::DataPointPath
	This class provides a wrapper for a data point path. More...
class	rtctk::componentFramework::NestedExceptionPrinter
	Adapter object intended to be used in contexts without direct access to the output-stream object. More...
class	rtctk::componentFramework::RtctkException
	The RtctkException class is the base class for all Rtctk exceptions. More...
class	rtctk::componentFramework::NotImplementedException
	The NotImplementedException is thrown whenever an attempt is made to use a feature or function that has not been implemented. More...
class	rtctk::componentFramework::UnsupportedTypeException
	The UnsupportedTypeException is thrown whenever an attempt is made to use an unsupported type in the RTC Toolkit API. More...
class	rtctk::componentFramework::UnsupportedUriException
	The UnsupportedUriException is thrown whenever an attempt is made to use an unsupported URI in the RTC Toolkit API. More...
class	rtctk::componentFramework::BufferTooSmall
	The BufferTooSmall is thrown when an API call fails because the provided buffer is not big enough to hold the data. More...
class	rtctk::componentFramework::InvalidArgumentException
	Thrown if an argument passed to a method was invalid. More...
class	rtctk::componentFramework::InitialisationException
	Thrown in cases where an initialisation routine has failed. More...
class	rtctk::componentFramework::InvalidStateChange
	This Exception is raised when the state change requested is invalid. More...
class	rtctk::componentFramework::InvalidSetting
	This Exception is raised when a invalid setting was used in the runtime repo. More...
class	rtctk::componentFramework::DdtSinkNotFound
	This Exception is raised when an invalid ddt sink is requested. More...
class	rtctk::componentFramework::DdtError
	This Exception is raised when the DDT Publisher returns an error that cannot be handled by the DDT Sink. More...
class	rtctk::componentFramework::IpcqError
	This Exception is raised when the ipc queue returns an error that cannot be handled by the Telemetry Source Thread. More...
class	rtctk::componentFramework::AdapterCreationException
	Thrown from service factory methods to indicate the adapter construction failed. More...
class	rtctk::componentFramework::InfluxTagMap
	Helper class for passing tags in Telegraf. More...
class	rtctk::componentFramework::MatrixBuffer< T, A >
	A buffer class representing 2D matrix data. More...
class	rtctk::componentFramework::MatrixSpan< T >
	A span referencing a 2D matrix buffer. More...
class	rtctk::componentFramework::RepositoryIf
	Abstract interface providing basic read and write facilities to a repository. More...
class	rtctk::componentFramework::RepositorySubscriberIf
	Abstract interface providing I/O and additional subscription facilities for a repository. More...
class	rtctk::componentFramework::RepositorySubscriberIf::Subscription
	RAII wrapper class used to manage the life-time of individual subscriptions. More...
class	rtctk::componentFramework::ServiceContainer
	Container class that holds services of any type. More...
class	rtctk::componentFramework::ServiceDiscovery
	Class that implements a very basic service discovery mechanism. More...
class	rtctk::componentFramework::ServiceRegistryIf
	Class that implements a service registry to be used by the service discovery. More...
class	rtctk::componentFramework::ConsulServiceRegistryAdapter
	Class that implements a very basic service discovery mechanism using Consul. More...
class	rtctk::componentFramework::FileServiceRegistryAdapter
	Class that implements a very basic service discovery mechanism using a file. More...

Functions
template<class E>
auto	rtctk::componentFramework::WrapWithNested (E &&exception) noexcept(std::is_nothrow_constructible_v< detail::UnspecifiedNested< typename std::decay_t< E > >, E && >)
	Constructs an unspecified exception that derives from both the provided object and std::nested_exception.
void	rtctk::componentFramework::PrintComposedExceptions (std::ostream &os, const std::vector< std::exception_ptr > &exceptions)
	Print composed exception messages in exceptions list to os.
void	rtctk::componentFramework::PrintNestedExceptions (std::ostream &os, const std::exception &exception)
	Print nested exception(s) in exception to os.
void	rtctk::componentFramework::PrintNestedExceptions (std::ostream &os, std::exception_ptr ptr)
	Print nested exception(s) in exception to os.
std::string	rtctk::componentFramework::GetCfitsioErrorMsg (int status)
	Helper function to convert a Cfitsio status code to a human readable message.
std::string	rtctk::componentFramework::CfitsioImageTypeToString (int bitpix)
	Returns a string representation of a Cfitsio image type code.
std::string	rtctk::componentFramework::CfitsioDataTypeToString (int datatype)
	Returns a string representation of a Cfitsio data type code.
const std::type_info &	rtctk::componentFramework::GetFitsImageType (const std::string &filename)
	Get the C++ type corresponding to a FITS image.
std::vector< uint64_t >	rtctk::componentFramework::GetFitsImageShape (const std::string &filename)
	Get the shape of a FITS image.
std::size_t	rtctk::componentFramework::GetFitsImageSize (const std::string &filename)
	Get the number of pixels in a FITS image.
template<typename T>
void	rtctk::componentFramework::WriteDataToFits (const std::string &filename, const T &buffer)
	Writes a matrix, vector, or span to a FITS image file.
template<typename T>
void	rtctk::componentFramework::ReadDataFromFits (const std::string &filename, T &buffer)
	Reads data from a FITS file into a buffer (matrix, vector, or span).
template<typename T>
void	rtctk::componentFramework::WriteMatrixToFits (const std::string &filename, const T &matrix, bool boolean_items=false)
	Writes data representing a matrix as an image to a FITS file.
template<typename T>
void	rtctk::componentFramework::ReadMatrixFromFits (const std::string &filename, T &matrix)
	Reads a FITS file image into a buffer object representing a matrix.
template<typename T>
void	rtctk::componentFramework::WriteVectorToFits (const std::string &filename, const T &vector, bool boolean_items=false)
	Writes data as a 1D image to a FITS file.
template<typename T>
void	rtctk::componentFramework::ReadVectorFromFits (const std::string &filename, T &vector)
	Reads a FITS file containing a 1D image into a buffer object representing a vector.
template<typename T>
bool	rtctk::componentFramework::GetOptionalParam (RepositoryIf &repo, const DataPointPath &path, T &value)
	Get optional datapoint.
std::optional< numapp::NumaPolicies >	rtctk::componentFramework::GetNumaPolicies (RepositoryIf &repo, const DataPointPath &path)
	Constructs a NumaPolicies object from the configuration datapoints found under the given datapoint path.

Variables
template<typename T>
constexpr bool	rtctk::componentFramework::IS_VECTOR_TYPE = IsVectorType<T>::value
	Is true if the type is a std::vector<U> of some type U.
template<typename T>
constexpr bool	rtctk::componentFramework::IS_MATRIX_BUFFER_TYPE = IsMatrixBufferType<T>::value
	Is true if the type is a MatrixBuffer<U> of some type U.
template<typename T>
constexpr bool	rtctk::componentFramework::IS_SPAN_TYPE = IsSpanType<T>::value
	Is true if the type is a gsl::span<U> of some type U.
template<typename T>
constexpr bool	rtctk::componentFramework::IS_MATRIX_SPAN_TYPE = IsMatrixSpanType<T>::value
	Is true if the type is a MatrixSpan<U> of some type U.
template<typename T>
constexpr bool	rtctk::componentFramework::IS_STD_ARRAY_TYPE = IsStdArrayType<T>::value
	Is true if the type is a std::array<U> of some type U.
template<typename T>
constexpr bool	rtctk::componentFramework::IS_STATIC_SPAN_TYPE = IsStaticSpanType<T>::value
	Is true if the type is a gsl::span type with fixed size.
template<typename T>
constexpr bool	rtctk::componentFramework::IS_DYNAMIC_SPAN_TYPE = IsDynamicSpanType<T>::value
	Is true if the type is a gsl::span type with dynamic size.
template<typename T>
constexpr bool	rtctk::componentFramework::IS_SUPPORTED_URI_SCHEME_DEFINED = IsSupportedUriSchemeDefined<T>::value
	Is true if the class contains the member SUPPORTED_URI_SCHEME.
template<typename T>
constexpr bool	rtctk::componentFramework::IS_ADAPTER_ID_TYPE_DEFINED = IsAdapterIdTypeDefined<T>::value
	Is true if the class contains the type declaration for AdapterIdType.

Detailed Description

Common services and utilities shared by other services.

Copyright

SPDX 2020-2026 European Southern Observatory (ESO)
SPDX LGPL-3.0-only

Function Documentation

CfitsioDataTypeToString()

std::string rtctk::componentFramework::CfitsioDataTypeToString

(

int

datatype

)

Returns a string representation of a Cfitsio data type code.

Parameters

[in]

datatype

The Cfitsio data type code that may be used with fits_read_pix or fits_write_pix.

Returns

Cfitsio data type as a string or "Unknown type" if the type code is not recognised.

CfitsioImageTypeToString()

std::string rtctk::componentFramework::CfitsioImageTypeToString

(

int

bitpix

)

Returns a string representation of a Cfitsio image type code.

Parameters

[in]

bitpix

The Cfitsio image type code that may be used with fits_create_img or returned by fits_get_img_equivtype.

Returns

Cfitsio image type as a string or "Unknown type" if the type code is not recognised.

GetCfitsioErrorMsg()

std::string rtctk::componentFramework::GetCfitsioErrorMsg

(

int

status

)

Helper function to convert a Cfitsio status code to a human readable message.

Parameters

[in]

status

The status code set by a Cfitsio routine.

Returns

An error message corresponding to the Cfitsio status code.

GetFitsImageShape()

std::vector< uint64_t > rtctk::componentFramework::GetFitsImageShape

(

const std::string &

filename

)

Get the shape of a FITS image.

This method will return a vector of integers indicating the number of pixels in each dimension. For 1D data the vector will contain only one number. For 2D data the vector will contain the number of rows and columns in the image.

Parameters

[in]

filename

The name of the FITS file to query.

Returns

The shape of the image as a vector of unsigned integers.

Exceptions

RtctkException

If the FITS file could not be read or has the wrong format.

GetFitsImageSize()

std::size_t rtctk::componentFramework::GetFitsImageSize

(

const std::string &

filename

)

Get the number of pixels in a FITS image.

This method will return the total number pixels in the image stored in the primary HDU of a FITS file.

Parameters

[in]

filename

The name of the FITS file to query.

Returns

The total number of pixels in the image.

Exceptions

RtctkException

If the FITS file could not be read or has the wrong format.

GetFitsImageType()

const std::type_info & rtctk::componentFramework::GetFitsImageType

(

const std::string &

filename

)

Get the C++ type corresponding to a FITS image.

This method will identify the FITS format of the image in the primary HDU and return the type info object corresponding to the C++ type that should be used with one of the methods: ReadVectorFromFits, WriteVectorToFits, ReadMatrixFromFits or WriteMatrixToFits.

Parameters

[in]

filename

The name of the FITS file to query.

Returns

The corresponding C++ type of the image in the FITS file.

Exceptions

RtctkException

If the FITS file could not be read or has the wrong format.

GetNumaPolicies()

std::optional< numapp::NumaPolicies > rtctk::componentFramework::GetNumaPolicies	(	RepositoryIf &	repo,
		const DataPointPath &	path )

Constructs a NumaPolicies object from the configuration datapoints found under the given datapoint path.

Parameters

repo	Repository to read from.
path	The base path under which configuration datapoints for NUMA policies will be searched. The following sub-paths will be searched: cpu_affinity scheduler_policy scheduler_priority memory_policy_mode memory_policy_nodes

Returns

The loaded NUMA policies or std::nullopt if no policies were provided.

Valid values for the scheduler_policy datapoint are:

• Fifo
• Rr
• Other
• Batch

If either Fifo or Rr are used then the scheduler_priority must be used to set the threads priority. Valid values for scheduler_priority is different depending on scheduler_policy:

• Fifo and Rr: 1-99
• Other and Batch: -20 - 19 with 0 being the default. This is also known as the "nice" value.

Valid values for the memory_policy_mode datapoint are:

• Default
• Bind
• Interleave
• Preferred

Note

Setting only scheduler_priority without scheduler_policy has no effect. scheduler_policy must always be used if scheduler_priority is set in the configuration.

The datapoints for memory_policy_mode and memory_policy_nodes must be provided together.

GetOptionalParam()

template<typename T>

bool rtctk::componentFramework::GetOptionalParam	(	RepositoryIf &	repo,
		const DataPointPath &	path,
		T &	value )

Get optional datapoint.

Template Parameters

T	Data point type.

Parameters

	repo	Repository to read from.
	path	Data point to read.
[out]	value	Destination variable for read datapoint. Will not be modified if datapoint does not exist.

Return values

true	if the datapoint exists and value has been set.
false	otherwise.

PrintComposedExceptions()

void rtctk::componentFramework::PrintComposedExceptions	(	std::ostream &	os,
		const std::vector< std::exception_ptr > &	exceptions )

Print composed exception messages in exceptions list to os.

The error messages for each exception are indented and prefixed as follows:

Composed exceptions:
 -  1. First outer exception message.
    2. First nested exception message
       with multiple lines.
 -  1. Second exception message.
 -  1. Third exception message.
    2. Inner nested exception of third exception.

Parameters

os	Output stream to print to.
exceptions	List of composed exceptions to print.

PrintNestedExceptions() [1/2]

void rtctk::componentFramework::PrintNestedExceptions	(	std::ostream &	os,
		const std::exception &	exception )

Print nested exception(s) in exception to os.

The error messages for each exception are indented and prefixed as follows:

Nested exceptions:
1. Outer exception message.
2. Middle nested exception message
   with multiple lines.
3. Inner nested exception message.

Parameters

os	Output stream to print to.
exception	Exception (possibly nested) to print.

PrintNestedExceptions() [2/2]

void rtctk::componentFramework::PrintNestedExceptions	(	std::ostream &	os,
		std::exception_ptr	ptr )

Print nested exception(s) in exception to os.

If ptr does not hold an exception this function has no effect.

Parameters

os	Output stream to print to.
ptr	Exception (possibly nested) to print.

ReadDataFromFits()

template<typename T>

void rtctk::componentFramework::ReadDataFromFits	(	const std::string &	filename,
		T &	buffer )

Reads data from a FITS file into a buffer (matrix, vector, or span).

The function opens a FITS image using CFITSIO, validates that the image pixel type matches the buffer element type, checks dimensionality (1D for vectors/spans, 2D for matrices), and resizes the buffer when applicable. Data is then read into the buffer. Boolean types are converted from integer representation.

Template Parameters

T	Buffer type (MatrixBuffer, MatrixSpan, Vector, or Span).

Parameters

[in]	filename	Name of the FITS file to read.
[out]	buffer	Destination buffer to store the image data.

Exceptions

RtctkException	If the file cannot be opened, metadata is invalid, or read fails.
BufferTooSmall	If a span buffer is smaller than the FITS data size.

ReadMatrixFromFits()

template<typename T>

void rtctk::componentFramework::ReadMatrixFromFits	(	const std::string &	filename,
		T &	matrix )

Reads a FITS file image into a buffer object representing a matrix.

Template Parameters

T	The type of the matrix object. Must be MatrixBuffer or MatrixSpan.

Parameters

[in]	filename	Name of the FITS file to read from.
[out]	matrix	The matrix data object that will be updated with the loaded data.

ReadVectorFromFits()

template<typename T>

void rtctk::componentFramework::ReadVectorFromFits	(	const std::string &	filename,
		T &	vector )

Reads a FITS file containing a 1D image into a buffer object representing a vector.

Template Parameters

T	The type of the vector object. Must be std::vector or gsl::span.

Parameters

[in]	filename	Name of the FITS file to read from.
[out]	vector	The vector data object that will be updated with the loaded data.

WrapWithNested()

template<class E>

auto rtctk::componentFramework::WrapWithNested ( E && exception )

noexcept

Constructs an unspecified exception that derives from both the provided object and std::nested_exception.

Warning

Although it is akin to a non-throwing version of std::throw_with_nested, if WrapWithNested is invoked without a current exception it shall not be used with std::rethrow_if_nested as it terminates the application if there's no nested exception.

If there is a current exception (std::current_exception() == true) the nested exception will be stored with the returned exception type.

Template Parameters

E	exception type used to deduce the exception type to construct using std::decay<E>.

Parameters

exception

Exception used to copy or move-construct the unspecified exception.

Exceptions

Exceptions

thrown by exception copy/move constructor.

WriteDataToFits()

template<typename T>

void rtctk::componentFramework::WriteDataToFits	(	const std::string &	filename,
		const T &	buffer )

Writes a matrix, vector, or span to a FITS image file.

Supports both 2D and 1D buffers. The FITS pixel type is derived from the buffer element type. Boolean buffers are converted to 8-bit integers and marked with the BOOLITEM keyword.

Template Parameters

T	Buffer type (MatrixBuffer, MatrixSpan, vector, or span).

Parameters

[in]	filename	Output FITS file path (overwritten if it exists).
[in]	buffer	Data to write as a FITS image.

Exceptions

RtctkException

on CFITSIO or filesystem errors.

WriteMatrixToFits()

template<typename T>

void rtctk::componentFramework::WriteMatrixToFits	(	const std::string &	filename,
		const T &	matrix,
		bool	boolean_items = false )

Writes data representing a matrix as an image to a FITS file.

Template Parameters

T	The type of the matrix object. Must be MatrixBuffer or MatrixSpan.

Parameters

[in]	filename	Name of the FITS file to create. It will be overwritten if it exists.
[in]	matrix	The matrix data to write.
[in]	boolean_items	Flag indicating if the BOOLITEM keyword should be written.

WriteVectorToFits()

template<typename T>

void rtctk::componentFramework::WriteVectorToFits	(	const std::string &	filename,
		const T &	vector,
		bool	boolean_items = false )

Writes data as a 1D image to a FITS file.

Template Parameters

T	The type of the vector object. Must be std::vector or gsl::span.

Parameters

[in]	filename	Name of the FITS file to create. It will be overwritten if it exists.
[in]	vector	The vector data to write.
[in]	boolean_items	Flag indicating if the BOOLITEM keyword should be written.

Variable Documentation

IS_ADAPTER_ID_TYPE_DEFINED

template<typename T>

bool rtctk::componentFramework::IS_ADAPTER_ID_TYPE_DEFINED = IsAdapterIdTypeDefined<T>::value

inlineconstexpr

Is true if the class contains the type declaration for AdapterIdType.

IS_DYNAMIC_SPAN_TYPE

template<typename T>

bool rtctk::componentFramework::IS_DYNAMIC_SPAN_TYPE = IsDynamicSpanType<T>::value

inlineconstexpr

Is true if the type is a gsl::span type with dynamic size.

IS_MATRIX_BUFFER_TYPE

template<typename T>

bool rtctk::componentFramework::IS_MATRIX_BUFFER_TYPE = IsMatrixBufferType<T>::value

inlineconstexpr

Is true if the type is a MatrixBuffer<U> of some type U.

IS_MATRIX_SPAN_TYPE

template<typename T>

bool rtctk::componentFramework::IS_MATRIX_SPAN_TYPE = IsMatrixSpanType<T>::value

inlineconstexpr

Is true if the type is a MatrixSpan<U> of some type U.

IS_SPAN_TYPE

template<typename T>

bool rtctk::componentFramework::IS_SPAN_TYPE = IsSpanType<T>::value

inlineconstexpr

Is true if the type is a gsl::span<U> of some type U.

IS_STATIC_SPAN_TYPE

template<typename T>

bool rtctk::componentFramework::IS_STATIC_SPAN_TYPE = IsStaticSpanType<T>::value

inlineconstexpr

Is true if the type is a gsl::span type with fixed size.

IS_STD_ARRAY_TYPE

template<typename T>

bool rtctk::componentFramework::IS_STD_ARRAY_TYPE = IsStdArrayType<T>::value

inlineconstexpr

Is true if the type is a std::array<U> of some type U.

IS_SUPPORTED_URI_SCHEME_DEFINED

template<typename T>

bool rtctk::componentFramework::IS_SUPPORTED_URI_SCHEME_DEFINED = IsSupportedUriSchemeDefined<T>::value

inlineconstexpr

Is true if the class contains the member SUPPORTED_URI_SCHEME.

IS_VECTOR_TYPE

template<typename T>

bool rtctk::componentFramework::IS_VECTOR_TYPE = IsVectorType<T>::value

inlineconstexpr

Is true if the type is a std::vector<U> of some type U.