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_METRICthe definition is for a metric.
MON_DOM_CTRLthe 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_OPTIONALthe parameter is optional.
MON_PARAM_MULTIVALthe 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_CONTINUOUSThe metric is continuous, it can be measured whenever the consumer wants.
MON_EVENTLIKEThe 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.