1sg_comp_init(3) sg_comp_init(3)
2
6 sg_comp_init, sg_comp_destroy, sg_comp_get_tls, sg_global_lock,
7 sg_global_unlock - managing system statistics delivery
8
10 #include "tools.h"
11 void *get_global_static (unsigned int id);
14 sg_error sg_global_lock (void);
16 sg_error sg_global_unlock (void);
18
20 sg_comp_init() is called by sg_init() to run the initialisation for the
21 globals component and each registered libstatgrab component. This reg‐
22 istration is done statically by appending a component initialisation
23 information structure (instance-of sg_comp_info) to the comp_info list
24 in src/libstatgrab/globals.c. The instance of sg_comp_info is usually
25 defined by using one of EASY_COMP_SETUP() or EXTENDED_COMP_SETUP(), re‐
26 spectively.
27 sg_comp_destroy() is called by sg_shutdown() to destroy all global re‐
29 sources, eg. translation tables for device names or compiled regular
30 expressions to match path names etc. Statistics resources are managed
31 somewhere else and are freed (conceptually and usually) before
32 sg_comp_destroy() is invoked.
33 sg_comp_get_tls() is the internal function to access the thread local
35 storage (formerly static globals) of the component. Usually it's easier
36 to rely on the encapsulating macro GLOBAL_GET_TLS().
37
39 Delivering system statistics is the job of libstatgrab, managing the
40 delivery is the job of the globals component. To fulfil this job, the
41 components to manage must be prepared:
42 1. declare component's global and TLS data structure (probably only on
44 paper, not in code)
45 2. define global initialisation, thread destruction and process de‐
47 struction functions (if required by 1.)
48 3. define component information structure using *_COMP_SETUP()
50 4. define component accessors using one or more of
52 EASY_COMP_ACCESS()
54 EASY_COMP_DIFF()
55 MULTI_COMP_ACCESS()
56 MULTI_COMP_DIFF()
57 When having done these steps, a new component delivering new statistics
59 is born and needs to be "announced". Assuming the component is named
60 cpu, append the line { &sg_cpu_init, 0 } to above named comp_info list.
61 Component initialisation information in detail:
63 typedef sg_error (*comp_global_init_function)(unsigned id);
65 typedef void (*comp_global_destroy_function)(void);
66 typedef void (*comp_global_cleanup_function)(void *);
67 struct sg_comp_status {
69 sg_error init_error;
70 };
71 struct sg_comp_init {
73 comp_global_init_function init_fn;
74 comp_global_destroy_function destroy_fn;
75 comp_global_cleanup_function cleanup_fn;
76 size_t static_buf_size;
77 #if defined(ENABLE_THREADS) && defined(HAVE_PTHREAD)
78 const char **required_locks;
79 #endif
80 struct sg_comp_status *status;
81 };
82 Components which do not need something special can rely on
85 EASY_COMP_SETUP():
86 Initialising memory component
88 EASY_COMP_SETUP(mem,1,NULL);
90 When own initialisation is needed, doing it is a bit more complex:
93 Initialising network component
95 #define SG_NETWORK_IO_NOW_IDX 0
97 #define SG_NETWORK_IO_DIFF_IDX 1
98 #define SG_NETWORK_IFACE_IDX 2
99 #define SG_NETWORK_MAX_IDX 3
100 EXTENDED_COMP_SETUP(network,SG_NETWORK_MAX_IDX,NULL);
102 #ifdef LINUX
104 static regex_t network_io_rx;
105 #define RX_MATCH_COUNT (8+1)
106 #endif
107 sg_error
109 sg_network_init_comp(unsigned id) {
110 GLOBAL_SET_ID(network,id);
111 #ifdef LINUX
113 if( regcomp( &network_io_rx, ..., REG_EXTENDED)!=0) {
114 return sg_set_error(SG_ERROR_PARSE, NULL);
115 }
116 #endif
117 return SG_ERROR_NONE;
119 }
120 void
122 sg_network_destroy_comp(void) {
123 #ifdef LINUX
124 regfree(&network_io_rx);
125 #endif
126 }
127 EASY_COMP_CLEANUP_FN(network,SG_NETWORK_MAX_IDX)
129 MACROS TO WORK WITH THE COMPONENT MANAGER
132 To simplify working with the component management functions, some pre‐
133 processor macros are available. They are shown here as if they were
134 functions to ease understanding.
135 void DEFAULT_INIT_COMP (identifier comp, ...);
137 void EASY_COMP_SETUP (identifier comp, size_t nvect, ...);
139 void EXTENDED_COMP_SETUP (identifier comp, size_t nvect, ...);
141 void GLOBAL_SET_ID (identifier comp, unsigned int id);
143 struct sg_##comp##_glob *GLOBAL_GET_TLS (identifier comp);
145 void EASY_COMP_INIT_FN (identifier comp);
147 void EASY_COMP_DESTROY_FN (identifier comp);
149 void EASY_COMP_CLEANUP_FN (identifier comp, size_t nvect);
151 void EASY_COMP_ACCESS (identifier fn, identifier comp, identifier stat,
153 size_t idx);
154 void MULTI_COMP_ACCESS (identifier fn, identifier comp, identifier
156 stat, size_t idx);
157 void EASY_COMP_DIFF (identifier fn, identifier getfn, identifier comp,
159 identifier stat, size_t diffidx, size_t nowidx);
160 void MULTI_COMP_DIFF (identifier fn, identifier getfn, identifier comp,
162 identifier stat, size_t diffidx, size_t nowidx);
163 EASY_COMP_SETUP() cares about anything to be automatically done for in‐
165 stantiating a component information structure for the specified compo‐
166 nent comp. The created TLS storage structure will hold nvect pointer
167 elements and that's it. All initialisation, destruction and cleanup-
168 routines are created as needed using EASY_COMP_INIT_FN(), EASY_COMP_DE‐
169 STROY_FN() and EASY_COMP_CLEANUP_FN(). After the amount of required
170 vector pointers to be stored the list of required mutexes must be spec‐
171 ified, finished with a NULL pointer.
172 EXTENDED_COMP_SETUP() cares about anything to be automatically done for
174 instantiating an component information structure for the specified com‐
175 ponent comp but the required defintion of the initialisation, destruc‐
176 tion and cleanup routines. The created TLS storage structure will hold
177 nvect pointer elements and that's it. After the amount of required vec‐
178 tor pointers to be stored, the list of required mutexes must be speci‐
179 fied, finished with a NULL pointer. All standard routines can be cre‐
180 ated semi-automatically using EASY_COMP_INIT_FN(), EASY_COMP_DE‐
181 STROY_FN() and EASY_COMP_CLEANUP_FN().
182 DEFAULT_INIT_COMP() just declares the prototypes for the initialisa‐
184 tion, destruction and cleanup routines, defines the initialisation sta‐
185 tus buffer, lock-names list and finally fills the component initialisa‐
186 tion structure. Use this when your TLS storage contains not only vec‐
187 tor pointers.
188 GLOBAL_GET_TLS() returns the pointer to the component's thread local
190 storage.
191 GLOBAL_SET_ID() stores the component identifier, required eg. to access
193 its TLS.
194 EASY_COMP_INIT_FN() defines a default component initialisation routine.
196 It stores the component identifier and returns with SG_ERROR_NONE.
197 EASY_COMP_DESTROY_FN() defines a default component destructor, called
199 at the end of the entire process (or when the last sg_shutdown() is
200 called). The default destructor does nothing and usually an individual
201 initialisation routine requires an individual destructor, too.
202 EASY_COMP_CLEANUP_FN() defines a default TLS cleanup routine, always
204 called when a thread ends to free vectors held in thread local storage.
205 EASY_COMP_ACCESS() defines accessors to a specific statistic containing
207 one element provided by the component: the functions fn() and the
208 fn##_r(). The following function must exists:
209 sg_error fn##_int (sg_vector *name##_vect); It accesses the vector idx
210 from TLS of component comp and returns sg_##name##_stats. It manages
211 all standard things like memory and error management, return value etc.
212 EASY_COMP_DIFF() returns the difference between the two statistic col‐
214 lection runs. The variant dealing with statgrab owned statistics return
215 the difference between the content currently in the vector specified by
216 nowidx and the resulting vector of getfn(). The result is stored in the
217 vector diffidx. If there is no current result, simply the result of
218 getfn() is returned.
219 MULTI_COMP_ACCESS() defines accessors to a specific statistic contain‐
221 ing 0..n elements provided by the component: the functions fn() and the
222 fn##_r(). The following function must exists:
223 sg_error fn##_int (sg_vector **name##_vect); It accesses the vector idx
224 from TLS of component comp and returns sg_##name##_stats. It manages
225 all standard things like memory and error anagement, return values, en‐
226 tries update, etc.
227 MULTI_COMP_DIFF() does the same as EASY_COMP_DIFF() but for vectors
229 with more than one element.
230
232 libstatgrab(3) sg_intro(3) sg_set_error(3) sg_comp_init(3) sg_vec‐
233 tor_create(3)
234
236 ⟨http://www.i-scream.org/libstatgrab/⟩
237i-scream 2013-06-07 sg_comp_init(3)