Metric Definition Registry

Metric Definition Registry — Resolving metric and control names to metric/control definitions

Synopsis


#include <monitor/monitor.h>


#define     MON_REGISTRY_API
#define     MON_REGISTRY_MODULE             (desc)
#define     MON_SYMBOL_REGISTRY
            mon_registry_module;
int         mon_registry_register           (mon_module *module);
void        mon_registry_unregister         (mon_module *module);

enum        mon_metric_def_domain;
            mon_metric_def;
mon_metric_def* (*mon_metric_def_lookup)    (mon_metric_def_domain domain,
                                             const char *name,
                                             void *ptr);
            mon_param;
enum        mon_param_flags;
enum        mon_measurement_type;
mon_metric_def* mon_metric_def_new          (mon_metric_def_domain domain,
                                             const char *name,
                                             mon_type *type,
                                             mon_measurement_type measurement);
void        mon_metric_def_done             (mon_metric_def *def);
void        mon_metric_def_ref              (mon_metric_def *def);
int         mon_metric_def_add_param        (mon_metric_def *def,
                                             const char *name,
                                             mon_basic_type type,
                                             mon_param_flags flags);
int         mon_metric_def_encode           (mon_buffer *buf,
                                             const mon_metric_def *def);
int         mon_metric_def_decode           (mon_buffer *buf,
                                             mon_metric_def **def);
int         mon_metric_def_cmp              (const mon_metric_def *def1,
                                             const mon_metric_def *def2);

mon_metric_def* mon_metric_def_get          (const char *name);
mon_metric_def* mon_ctrl_def_get            (const char *name);

            mon_metric_cache;
int         mon_metric_cache_add            (mon_metric_cache *cache,
                                             mon_metric_def *def);
void        mon_metric_cache_remove         (mon_metric_cache *cache,
                                             mon_metric_def *def);
mon_metric_def* mon_metric_cache_get        (mon_metric_cache *cache,
                                             mon_metric_def_domain domain,
                                             const char *name);
void        mon_metric_cache_destroy        (mon_metric_cache *cache,
                                             int free_entries);

Description

Details

MON_REGISTRY_API

#define MON_REGISTRY_API	1

Defines the registry module API version implemented by the library.

MON_REGISTRY_MODULE()

#define     MON_REGISTRY_MODULE(desc)

Declares a registry module.

desc : the name of the registry module descriptor.

MON_SYMBOL_REGISTRY

#define MON_SYMBOL_REGISTRY	MON_MODSYM(mon_module_registry)

Defines the symbol name of the registry module descriptor table in a loadable module.

mon_registry_module

typedef struct {
	mon_module		header;
	mon_metric_def_lookup	lookup;
} mon_registry_module;

This is the descriptor structure for a module implementing a metric/control definition registry.

mon_module `header`;	the generic loadable module header.
mon_metric_def_lookup `lookup`;	the lookup function to register.

mon_registry_register ()

int         mon_registry_register           (mon_module *module);

Register a metric definition lookup function. Such functions will be called in the order of registration when a lookup for a metric definition is requested.

`module` :	a mon_registry_module to register.
Returns :	0 or error code.

mon_registry_unregister ()

void        mon_registry_unregister         (mon_module *module);

Unregister a metric definition lookup function.

module : a mon_registry_module to unregister.

enum mon_metric_def_domain

typedef enum {
	MON_DOM_METRIC = 1,
	MON_DOM_CTRL
} mon_metric_def_domain;

The name domain where the metric definition belongs.

`MON_DOM_METRIC`	the definition is for a metric.
`MON_DOM_CTRL`	the definition is for a control.

mon_metric_def

typedef struct {
	mon_metric_def_domain	domain;
	char			*name;
	mon_param		*params;
	unsigned int		paramcnt;
	mon_type		*type;
	mon_measurement_type	measurement;

	mon_metric_cache	*cache;
	int			refcnt;
} mon_metric_def;

The mon_metric_def struct holds a metric or control definition.

mon_metric_def_domain `domain`;	the definition domain: either `MON_DOM_METRIC` or `MON_DOM_CTRL`.
char *`name`;	the name of the defined object.
mon_param *`params`;	the list of formal parameters.
unsigned int `paramcnt`;	number of entries in `params`.
mon_type *`type`;	the data type.
mon_measurement_type `measurement`;	either `MON_CONTINUOUS` or `MON_EVENTLIKE`.
mon_metric_cache *`cache`;	the cache object this definition belongs to.
int `refcnt`;	the reference count of the definition objec.

mon_metric_def_lookup ()

mon_metric_def* (*mon_metric_def_lookup)    (mon_metric_def_domain domain,
                                             const char *name,
                                             void *ptr);

Prototype for a metric definition lookup function.

`domain` :	either `MON_DOM_METRIC` or `MON_DOM_CTRL`.
`name` :	the name to look up.
`ptr` :	opaque pointer.
Returns :	the definition object or `NULL` if `name` is not known.

mon_param

typedef struct {
	char			*name;
	mon_basic_type		type;
	mon_param_flags		flags;
} mon_param;

The mon_param struct defines a metric parameter.

char *`name`;	the name of the parameter.
mon_basic_type `type`;	the type of the parameter.
mon_param_flags `flags`;	combination of values of mon_param_flags.

enum mon_param_flags

typedef enum {
	/* The parameter is optional */
	MON_PARAM_OPTIONAL	= (1 << 0),
	/* The parameter may have multiple values */
	MON_PARAM_MULTIVAL	= (1 << 1)
} mon_param_flags;

Flags for a metric/control parameter.

`MON_PARAM_OPTIONAL`	the parameter is optional.
`MON_PARAM_MULTIVAL`	the parameter may have multiple values.

enum mon_measurement_type

typedef enum {
	MON_CONTINUOUS,
	MON_EVENTLIKE
} mon_measurement_type;

The list of possible metric measurement types.

`MON_CONTINUOUS`	The metric is continuous, it can be measured whenever the consumer wants.
`MON_EVENTLIKE`	The metric is event-like. It cannot measured directly.

mon_metric_def_new ()

mon_metric_def* mon_metric_def_new          (mon_metric_def_domain domain,
                                             const char *name,
                                             mon_type *type,
                                             mon_measurement_type measurement);

Allocates a new mon_metric_def structure.

`domain` :	a mon_metric_def_domain.
`name` :	the metric/control name.
`type` :	the data type.
`measurement` :	a mon_measurement_type.
Returns :	a mon_metric_def or `NULL` if there was an error.

mon_metric_def_done ()

void        mon_metric_def_done             (mon_metric_def *def);

Drops a reference to a mon_metric_def. When the last reference is gone the memory allocated to the mon_metric_def is freed.

def : a mon_metric_def.

mon_metric_def_ref ()

void        mon_metric_def_ref              (mon_metric_def *def);

Increase the reference count of a mon_metric_def.

def : a mon_metric_def.

mon_metric_def_add_param ()

int         mon_metric_def_add_param        (mon_metric_def *def,
                                             const char *name,
                                             mon_basic_type type,
                                             mon_param_flags flags);

Adds a new parameter to a mon_metric_def.

`def` :	a mon_metric_def.
`name` :	the name of the parameter.
`type` :	the type of the parameter.
`flags` :	flags for this parameter.
Returns :	0 if successful or an error code.

mon_metric_def_encode ()

int         mon_metric_def_encode           (mon_buffer *buf,
                                             const mon_metric_def *def);

Encodes a metric definition.

`buf` :	the destination buffer.
`def` :	a mon_metric_def.
Returns :	0 if successful or an error code.

mon_metric_def_decode ()

int         mon_metric_def_decode           (mon_buffer *buf,
                                             mon_metric_def **def);

Decodes a metric definition that was encoded by mon_metric_def_encode().

`buf` :	the source buffer.
`def` :	pointer to store the decoded mon_metric_def if successful.
Returns :	0 if successful or an error code.

mon_metric_def_cmp ()

int         mon_metric_def_cmp              (const mon_metric_def *def1,
                                             const mon_metric_def *def2);

Compares two metric definitions using a lexicographical ordering.

`def1` :	a mon_metric_def.
`def2` :	a mon_metric_def.
Returns :	< 0, 0 or > 0 if `def1` is less than, equal, or greater than `def2` according to the lexicographical order.

mon_metric_def_get ()

mon_metric_def* mon_metric_def_get          (const char *name);

Get the definition of the named metric. The result of the first successful registered lookup function will be returned.

`name` :	the name of the metric.
Returns :	a mon_metric_def or `NULL` if the metric name was invalid.

mon_ctrl_def_get ()

mon_metric_def* mon_ctrl_def_get            (const char *name);

Get the definition of the named control. The result of the first successful registered lookup function will be returned.

`name` :	the name of the control.
Returns :	a mon_metric_def or `NULL` if the control name was invalid.

mon_metric_cache

typedef struct {
	GHashTable		*defs[2];
	unsigned int		num_defs[2];

	GList			*lookups;
} mon_metric_cache;

Defines a cache for mon_metric_def objects.

GHashTable *`defs`[2];	hash tables for looking up metric and control definitions.
unsigned int `num_defs`[2];	number of entries in the `defs` hash tables.
GList *`lookups`;	list of lookup functions to try if the definition is not in the cache.

mon_metric_cache_add ()

int         mon_metric_cache_add            (mon_metric_cache *cache,
                                             mon_metric_def *def);

Adds a mon_metric_def to a cache. The reference count of def is not modified.

`cache` :	a mon_metric_cache.
`def` :	a mon_metric_def.
Returns :	0 if successful or an error code.

mon_metric_cache_remove ()

void        mon_metric_cache_remove         (mon_metric_cache *cache,
                                             mon_metric_def *def);

Removes a mon_metric_def from a cache. The reference count of def is not modified.

`cache` :	a mon_metric_cache.
`def` :	a mon_metric_def.

mon_metric_cache_get ()

mon_metric_def* mon_metric_cache_get        (mon_metric_cache *cache,
                                             mon_metric_def_domain domain,
                                             const char *name);

Retrieves a mon_metric_def from a mon_metric_cache.

`cache` :	a mon_metric_cache.
`domain` :	either `MON_DOM_METRIC` or `MON_DOM_CTRL`.
`name` :	the name of the object.
Returns :	a mon_metric_def or `NULL` if `name` is not known.

mon_metric_cache_destroy ()

void        mon_metric_cache_destroy        (mon_metric_cache *cache,
                                             int free_entries);

Destroys a mon_metric_cache. Only the cache is destroyed, the metric definitions belonging to the cache are not deallocated.

`cache` :	a mon_metric_cache.
`free_entries` :	if TRUE, `mon_metric_def_done()` will be called on all entries in the cache.