NAME
sg_comp_init, sg_comp_destroy, sg_comp_get_tls, sg_global_lock, sg_global_unlock - managing system statistics delivery
SYNOPSIS
FC#include "tools.h"F[0]
FCvoid *get_global_staticF[0] FC(unsigned int id);F[0]
FCsg_error sg_global_lockF[0] FC(void);F[0]
FCsg_error sg_global_unlockF[0] FC(void);F[0]
DESCRIPTION
FCsg_comp_initF[0]() is called by FCsg_initF[0]() to run the initialisation for the globals component and each registered libstatgrab component. This registration is done statically by appending a component initialisation information structure (instance-of FCsg_comp_infoF[0]) to the FCcomp_infoF[0] list in FCsrc/libstatgrab/globals.cF[0]. The instance of FCsg_comp_infoF[0] is usually defined by using one of FCEASY_COMP_SETUPF[0]() or FCEXTENDED_COMP_SETUPF[0](), respectively.
FCsg_comp_destroyF[0]() is called by FCsg_shutdownF[0]() to destroy all global resources, eg. translation tables for device names or compiled regular expressions to match path names etc. Statistics resources are managed somewhere else and are freed (conceptually and usually) before FCsg_comp_destroyF[0]() is invoked.
FCsg_comp_get_tlsF[0]() is the internal function to access the thread local storage (formerly static globals) of the component. Usually it's easier to rely on the encapsulating macro FCGLOBAL_GET_TLSF[0]().
NOTES
Delivering system statistics is the job of libstatgrab, managing the delivery is the job of the globals component. To fulfil this job, the components to manage must be prepared:
- 1.
-
declare component's global and TLS data structure (probably only on paper, not in code)
- 2.
-
define global initialisation, thread destruction and process destruction functions (if required by 1.)
- 3.
-
define component information structure using FC*_COMP_SETUPF[0]()
- 4.
-
define component accessors using one or more of
FCEASY_COMP_ACCESSF[0]()
FCEASY_COMP_DIFFF[0]()
FCMULTI_COMP_ACCESSF[0]()
FCMULTI_COMP_DIFFF[0]()
When having done these steps, a new component delivering new statistics is born and needs to be "announced". Assuming the component is named cpu, append the line FC{ &sg_cpu_init, 0 }F[0] to above named FCcomp_infoF[0] list.
Component initialisation information in detail:
FC
typedef sg_error (*comp_global_init_function)(unsigned id);
typedef void (*comp_global_destroy_function)(void);
typedef void (*comp_global_cleanup_function)(void *);
struct sg_comp_status {
sg_error init_error;
};
struct sg_comp_init {
comp_global_init_function init_fn;
comp_global_destroy_function destroy_fn;
comp_global_cleanup_function cleanup_fn;
size_t static_buf_size;
#if defined(ENABLE_THREADS) && defined(HAVE_PTHREAD)
const char **required_locks;
#endif
struct sg_comp_status *status;
};
F[0]
Components which do not need something special can rely on FCEASY_COMP_SETUPF[0]():
Initialising memory component
FC
EASY_COMP_SETUP(mem,1,NULL);
F[0]
When own initialisation is needed, doing it is a bit more complex:
Initialising network component
FC
#define SG_NETWORK_IO_NOW_IDX 0
#define SG_NETWORK_IO_DIFF_IDX 1
#define SG_NETWORK_IFACE_IDX 2
#define SG_NETWORK_MAX_IDX 3
EXTENDED_COMP_SETUP(network,SG_NETWORK_MAX_IDX,NULL);
#ifdef LINUX
static regex_t network_io_rx;
#define RX_MATCH_COUNT (8+1)
#endif
sg_error
sg_network_init_comp(unsigned id) {
GLOBAL_SET_ID(network,id);
#ifdef LINUX
if( regcomp( &network_io_rx, ..., REG_EXTENDED)!=0) {
return sg_set_error(SG_ERROR_PARSE, NULL);
}
#endif
return SG_ERROR_NONE;
}
void
sg_network_destroy_comp(void) {
#ifdef LINUX
regfree(&network_io_rx);
#endif
}
EASY_COMP_CLEANUP_FN(network,SG_NETWORK_MAX_IDX)
F[0]
MACROS TO WORK WITH THE COMPONENT MANAGER
To simplify working with the component management functions, some preprocessor macros are available. They are shown here as if they were functions to ease understanding.
FCvoid DEFAULT_INIT_COMPF[0] FC(identifier comp, ...);F[0]
FCvoid EASY_COMP_SETUPF[0] FC(identifier comp, size_t nvect, ...);F[0]
FCvoid EXTENDED_COMP_SETUPF[0] FC(identifier comp, size_t nvect, ...);F[0]
FCvoid GLOBAL_SET_IDF[0] FC(identifier comp, unsigned int id);F[0]
FCstruct sg_##comp##_glob *GLOBAL_GET_TLSF[0] FC(identifier comp);F[0]
FCvoid EASY_COMP_INIT_FNF[0] FC(identifier comp);F[0]
FCvoid EASY_COMP_DESTROY_FNF[0] FC(identifier comp);F[0]
FCvoid EASY_COMP_CLEANUP_FNF[0] FC(identifier comp, size_t nvect);F[0]
FCvoid EASY_COMP_ACCESSF[0] FC(identifier fn, identifier comp, identifier stat, size_t idx);F[0]
FCvoid MULTI_COMP_ACCESSF[0] FC(identifier fn, identifier comp, identifier stat, size_t idx);F[0]
FCvoid EASY_COMP_DIFFF[0] FC(identifier fn, identifier getfn, identifier comp, identifier stat, size_t diffidx, size_t nowidx);F[0]
FCvoid MULTI_COMP_DIFFF[0] FC(identifier fn, identifier getfn, identifier comp, identifier stat, size_t diffidx, size_t nowidx);F[0]
FCEASY_COMP_SETUPF[0]() cares about anything to be automatically done for instantiating a component information structure for the specified component FCcompF[0]. The created TLS storage structure will hold FCnvectF[0] pointer elements and that's it. All initialisation, destruction and cleanup-routines are created as needed using FCEASY_COMP_INIT_FNF[0](), FCEASY_COMP_DESTROY_FNF[0]() and FCEASY_COMP_CLEANUP_FNF[0](). After the amount of required vector pointers to be stored the list of required mutexes must be specified, finished with a NULL pointer.
FCEXTENDED_COMP_SETUPF[0]() cares about anything to be automatically done for instantiating an component information structure for the specified component FCcompF[0] but the required definition of the initialisation, destruction and cleanup routines. The created TLS storage structure will hold FCnvectF[0] pointer elements and that's it. After the amount of required vector pointers to be stored, the list of required mutexes must be specified, finished with a NULL pointer. All standard routines can be created semi-automatically using FCEASY_COMP_INIT_FNF[0](), FCEASY_COMP_DESTROY_FNF[0]() and FCEASY_COMP_CLEANUP_FNF[0]().
FCDEFAULT_INIT_COMPF[0]() just declares the prototypes for the initialisation, destruction and cleanup routines, defines the initialisation status buffer, lock-names list and finally fills the component initialisation structure. Use this when your TLS storage contains not only vector pointers.
FCGLOBAL_GET_TLSF[0]() returns the pointer to the component's thread local storage.
FCGLOBAL_SET_IDF[0]() stores the component identifier, required eg. to access its TLS.
FCEASY_COMP_INIT_FNF[0]() defines a default component initialisation routine. It stores the component identifier and returns with SG_ERROR_NONE.
FCEASY_COMP_DESTROY_FNF[0]() defines a default component destructor, called at the end of the entire process (or when the last FCsg_shutdownF[0]() is called). The default destructor does nothing and usually an individual initialisation routine requires an individual destructor, too.
FCEASY_COMP_CLEANUP_FNF[0]() defines a default TLS cleanup routine, always called when a thread ends to free vectors held in thread local storage.
FCEASY_COMP_ACCESSF[0]() defines accessors to a specific statistic containing one element provided by the component: the functions FCfnF[0]() and the FCfn##_rF[0](). The following function must exists: FCsg_error fn##_intF[0] FC(sg_vector *name##_vect);F[0] It accesses the vector idx from TLS of component FCcompF[0] and returns sg_##name##_stats. It manages all standard things like memory and error management, return value etc.
FCEASY_COMP_DIFFF[0]() returns the difference between the two statistic collection runs. The variant dealing with statgrab owned statistics return the difference between the content currently in the vector specified by FCnowidxF[0] and the resulting vector of FCgetfnF[0](). The result is stored in the vector FCdiffidxF[0]. If there is no current result, simply the result of FCgetfnF[0]() is returned.
FCMULTI_COMP_ACCESSF[0]() defines accessors to a specific statistic containing 0..n elements provided by the component: the functions FCfnF[0]() and the FCfn##_rF[0](). The following function must exists: FCsg_error fn##_intF[0] FC(sg_vector **name##_vect);F[0] It accesses the vector idx from TLS of component FCcompF[0] and returns sg_##name##_stats. It manages all standard things like memory and error anagement, return values, FCentriesF[0] update, etc.
FCMULTI_COMP_DIFFF[0]() does the same as FCEASY_COMP_DIFFF[0]() but for vectors with more than one element.
SEE ALSO
libstatgrab(3) sg_intro(3) sg_set_error(3) sg_comp_init(3) sg_vector_create(3)
WEBSITE
⟨https://libstatgrab.org/⟩