134 lines
4.1 KiB
C
134 lines
4.1 KiB
C
/*
|
|
* Copyright(c) 2020 ZettaScale Technology and others
|
|
*
|
|
* This program and the accompanying materials are made available under the
|
|
* terms of the Eclipse Public License v. 2.0 which is available at
|
|
* http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
|
|
* v. 1.0 which is available at
|
|
* http://www.eclipse.org/org/documents/edl-v10.php.
|
|
*
|
|
* SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
|
|
*/
|
|
|
|
#ifndef DDS_STATISTICS_H
|
|
#define DDS_STATISTICS_H
|
|
|
|
/**
|
|
* @defgroup statistics (DDS Statistics)
|
|
* @ingroup dds
|
|
* @warning Unstable API
|
|
*
|
|
* A quick-and-dirty provisional interface
|
|
*/
|
|
|
|
#include "dds/dds.h"
|
|
#include "dds/ddsrt/attributes.h"
|
|
#include "dds/export.h"
|
|
|
|
#if defined (__cplusplus)
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* @brief Kind of statistical value
|
|
* @ingroup statistics
|
|
*/
|
|
enum dds_stat_kind {
|
|
DDS_STAT_KIND_UINT32, /**< value is a 32-bit unsigned integer */
|
|
DDS_STAT_KIND_UINT64, /**< value is a 64-bit unsigned integer */
|
|
DDS_STAT_KIND_LENGTHTIME /**< value is integral(length(t) dt) */
|
|
};
|
|
|
|
/**
|
|
* @brief KeyValue statistics entry
|
|
* @ingroup statistics
|
|
*/
|
|
struct dds_stat_keyvalue {
|
|
const char *name; /**< name, memory owned by library */
|
|
enum dds_stat_kind kind; /**< value type */
|
|
union {
|
|
uint32_t u32; /**< used if kind == DDS_STAT_KIND_UINT32 */
|
|
uint64_t u64; /**< used if kind == DDS_STAT_KIND_UINT64 */
|
|
uint64_t lengthtime; /**< used if kind == DDS_STAT_KIND_LENGTHTIME */
|
|
} u; /**< value */
|
|
};
|
|
|
|
/**
|
|
* @brief Statistics container
|
|
* @ingroup statistics
|
|
*/
|
|
struct dds_statistics {
|
|
dds_entity_t entity; /**< handle of entity to which this set of values applies */
|
|
uint64_t opaque; /**< internal data */
|
|
dds_time_t time; /**< time stamp of latest call to dds_refresh_statistics() */
|
|
size_t count; /**< number of key-value pairs */
|
|
struct dds_stat_keyvalue kv[]; /**< data */
|
|
};
|
|
|
|
/**
|
|
* @brief Allocate a new statistics object for entity
|
|
* @ingroup statistics
|
|
*
|
|
* This allocates and populates a newly allocated `struct dds_statistics` for the
|
|
* specified entity.
|
|
*
|
|
* @param[in] entity the handle of the entity
|
|
*
|
|
* @returns a newly allocated and populated statistics structure or NULL if entity is
|
|
* invalid or doesn't support any statistics.
|
|
*/
|
|
DDS_EXPORT struct dds_statistics *dds_create_statistics (dds_entity_t entity);
|
|
|
|
/**
|
|
* @brief Update a previously created statistics structure with current values
|
|
* @ingroup statistics
|
|
*
|
|
* Only the time stamp and the values (and "opaque") may change. The set of keys and the
|
|
* types of the values do not change.
|
|
*
|
|
* @param[in,out] stat statistics structure to update the values of
|
|
*
|
|
* @returns success or an error indication
|
|
*
|
|
* @retval DDS_RETCODE_OK
|
|
* the data was successfully updated
|
|
* @retval DDS_RETCODE_BAD_PARAMETER
|
|
* stats is a null pointer or the referenced entity no longer exists
|
|
* @retval DDS_RETCODE_PRECONDITION_NOT_MET
|
|
* library was deinitialized
|
|
*/
|
|
DDS_EXPORT dds_return_t dds_refresh_statistics (struct dds_statistics *stat);
|
|
|
|
/**
|
|
* @brief Free a previously created statistics object
|
|
* @ingroup statistics
|
|
*
|
|
* This frees the statistics object. Passing a null pointer is a no-op. The operation
|
|
* succeeds also if the referenced entity no longer exists.
|
|
*
|
|
* @param[in] stat statistics object to free
|
|
*/
|
|
DDS_EXPORT void dds_delete_statistics (struct dds_statistics *stat);
|
|
|
|
/**
|
|
* @brief Lookup a specific value by name
|
|
* @ingroup statistics
|
|
*
|
|
* This looks up the specified name in the list of keys in `stat` and returns the address
|
|
* of the key-value pair if present, a null pointer if not. If `stat` is a null pointer,
|
|
* it returns a null pointer.
|
|
*
|
|
* @param[in] stat statistics object to lookup a name in (or NULL)
|
|
* @param[in] name name to look for
|
|
*
|
|
* @returns The address of the key-value pair inside `stat`, or NULL if `stat` is NULL or
|
|
* `name` does not match a key in `stat.
|
|
*/
|
|
DDS_EXPORT const struct dds_stat_keyvalue *dds_lookup_statistic (const struct dds_statistics *stat, const char *name)
|
|
ddsrt_nonnull ((2));
|
|
|
|
#if defined (__cplusplus)
|
|
}
|
|
#endif
|
|
#endif
|