Browse code

core: counters arrays and counters descriptions

- each counter must have a description / help string.
- allow null handles in counter_register().
- counters arrays can be used to conveniently describe and
register several counters in the same time.
E.g.:
counter_def_t my_counters_defs[] = {
{&h1, "counter1", 0, 0, 0, "test counter1"},
{&h2, "counter2", 0, 0, 0, "test counter2"},
{0, "counter3", 0, get_cbk, 0, "counter with callback"},
{0, 0, 0, 0, 0, 0}
};

counter_register_array("my_counters", my_counters_defs);

Andrei Pelinescu-Onciul authored on 09/08/2010 14:51:36
Showing 2 changed files
... ...
@@ -56,6 +56,7 @@ struct counter_record {
56 56
 	void* cbk_param;
57 57
 	counter_cbk_f cbk;
58 58
 	struct counter_record* grp_next; /* next in group */
59
+	str doc;
59 60
 };
60 61
 
61 62
 
... ...
@@ -279,12 +280,13 @@ static struct grp_record* grp_hash_get_create(str* group)
279 279
 static struct counter_record* cnt_hash_add(
280 280
 							str* group, str* name,
281 281
 							int flags, counter_cbk_f cbk,
282
-							void* param)
282
+							void* param, const char* doc)
283 283
 {
284 284
 	struct str_hash_entry* e;
285 285
 	struct counter_record* cnt_rec;
286 286
 	struct grp_record* grp_rec;
287 287
 	struct counter_record** p;
288
+	int doc_len;
288 289
 	
289 290
 	e = 0;
290 291
 	if (cnts_no >= MAX_COUNTER_ID)
... ...
@@ -294,9 +296,11 @@ static struct counter_record* cnt_hash_add(
294 294
 	if (grp_rec == 0)
295 295
 		/* non existing group an no new one could be created */
296 296
 		goto error;
297
+	doc_len = doc?strlen(doc):0;
297 298
 	/* cnt_rec copied at &e->u.data[0] */
298 299
 	e = pkg_malloc(sizeof(struct str_hash_entry) - sizeof(e->u.data) +
299
-					sizeof(*cnt_rec) + name->len + 1 + group->len + 1);
300
+					sizeof(*cnt_rec) + name->len + 1 + group->len + 1 +
301
+					doc_len + 1);
300 302
 	if (e == 0)
301 303
 		goto error;
302 304
 	cnt_rec = (struct counter_record*)&e->u.data[0];
... ...
@@ -304,6 +308,8 @@ static struct counter_record* cnt_hash_add(
304 304
 	cnt_rec->group.len = group->len;
305 305
 	cnt_rec->name.s = cnt_rec->group.s + group->len + 1;
306 306
 	cnt_rec->name.len = name->len;
307
+	cnt_rec->doc.s = cnt_rec->name.s + name->len +1;
308
+	cnt_rec->doc.len = doc_len;
307 309
 	cnt_rec->h.id = cnts_no++;
308 310
 	cnt_rec->flags = flags;
309 311
 	cnt_rec->cbk_param = param;
... ...
@@ -311,6 +317,10 @@ static struct counter_record* cnt_hash_add(
311 311
 	cnt_rec->grp_next = 0;
312 312
 	memcpy(cnt_rec->group.s, group->s, group->len + 1);
313 313
 	memcpy(cnt_rec->name.s, name->s, name->len + 1);
314
+	if (doc)
315
+		memcpy(cnt_rec->doc.s, doc, doc_len + 1);
316
+	else
317
+		cnt_rec->doc.s[0] = 0;
314 318
 	e->key = cnt_rec->name;
315 319
 	e->flags = 0;
316 320
 	/* add it a pointer to it in the records array */
... ...
@@ -389,14 +399,14 @@ static struct counter_record* cnt_hash_get_create(
389 389
 								str* group, str* name,
390 390
 								int flags,
391 391
 								counter_cbk_f cbk,
392
-								void* param)
392
+								void* param, const char* doc)
393 393
 {
394 394
 	struct counter_record* ret;
395 395
 
396 396
 	ret = cnt_hash_lookup(group, name);
397 397
 	if (ret)
398 398
 		return ret;
399
-	return cnt_hash_add(group, name, flags, cbk, param);
399
+	return cnt_hash_add(group, name, flags, cbk, param, doc);
400 400
 }
401 401
 
402 402
 
... ...
@@ -405,21 +415,23 @@ static struct counter_record* cnt_hash_get_create(
405 405
  * Can be called only before forking (e.g. from mod_init() or
406 406
  * init_child(PROC_INIT)).
407 407
  * @param handle - result parameter, it will be filled with the counter
408
- *                  handle on success.
408
+ *                  handle on success (can be null if not needed).
409 409
  * @param group - group name
410 410
  * @param name  - counter name (group.name must be unique).
411 411
  * @param flags  - counter flags: one of CNT_F_*.
412 412
  * @param cbk   - read callback function (if set it will be called each time
413 413
  *                  someone will call counter_get()).
414 414
  * @param cbk_param - callback param.
415
+ * @param doc       - description/documentation string.
415 416
  * @param reg_flags - register flags: 1 - don't fail if counter already
416 417
  *                    registered (act like counter_lookup(handle, group, name).
417 418
  * @return 0 on succes, < 0 on error (-1 not init or malloc error, -2 already
418 419
  *         registered (and register_flags & 1 == 0).
419 420
  */
420
-int counter_register(	counter_handle_t* handle, char* group, char* name,
421
-						int flags,
421
+int counter_register(	counter_handle_t* handle, const char* group,
422
+						const char* name, int flags,
422 423
 						counter_cbk_f cbk, void* cbk_param,
424
+						const char* doc,
423 425
 						int reg_flags)
424 426
 {
425 427
 	str grp;
... ...
@@ -431,31 +443,31 @@ int counter_register(	counter_handle_t* handle, char* group, char* name,
431 431
 		BUG("late attempt to register counter: %s.%s\n", group, name);
432 432
 		goto error;
433 433
 	}
434
-	n.s = name;
434
+	n.s = (char*)name;
435 435
 	n.len = strlen(name);
436 436
 	if (unlikely(group == 0 || *group == 0)) {
437 437
 		BUG("attempt to register counter %s without a group\n", name);
438 438
 		goto error;
439 439
 	}
440
-	grp.s = group;
440
+	grp.s = (char*)group;
441 441
 	grp.len = strlen(group);
442 442
 	cnt_rec = cnt_hash_lookup(&grp, &n);
443 443
 	if (cnt_rec) {
444 444
 		if (reg_flags & 1)
445 445
 			goto found;
446 446
 		else {
447
-			handle->id = 0;
447
+			if (handle) handle->id = 0;
448 448
 			return -2;
449 449
 		}
450 450
 	} else
451
-		cnt_rec = cnt_hash_get_create(&grp, &n, flags, cbk, cbk_param);
451
+		cnt_rec = cnt_hash_get_create(&grp, &n, flags, cbk, cbk_param, doc);
452 452
 	if (unlikely(cnt_rec == 0))
453 453
 		goto error;
454 454
 found:
455
-	*handle = cnt_rec->h;
455
+	if (handle) *handle = cnt_rec->h;
456 456
 	return 0;
457 457
 error:
458
-	handle->id = 0;
458
+	if (handle) handle->id = 0;
459 459
 	return -1;
460 460
 }
461 461
 
... ...
@@ -492,20 +504,41 @@ int counter_lookup_str(counter_handle_t* handle, str* group, str* name)
492 492
   * @param name - counter name.
493 493
  * @return 0 on success, < 0 on error
494 494
  */
495
-int counter_lookup(counter_handle_t* handle, char* group, char* name)
495
+int counter_lookup(counter_handle_t* handle,
496
+					const char* group, const char* name)
496 497
 {
497 498
 	str grp;
498 499
 	str n;
499 500
 
500
-	n.s = name;
501
+	n.s = (char*)name;
501 502
 	n.len = strlen(name);
502
-	grp.s = group;
503
+	grp.s = (char*)group;
503 504
 	grp.len = group?strlen(group):0;
504 505
 	return counter_lookup_str(handle, &grp, &n);
505 506
 }
506 507
 
507 508
 
508 509
 
510
+/** register all the counters declared in a null-terminated array.
511
+  * @param group - counters group.
512
+  * @param defs  - null terminated array containing counters definitions.
513
+  * @return 0 on success, < 0 on error ( - (counter_number+1))
514
+  */
515
+int counter_register_array(const char* group, counter_def_t* defs)
516
+{
517
+	int r;
518
+	
519
+	for (r=0; defs[r].name; r++)
520
+		if (counter_register(	defs[r].handle,
521
+								group, defs[r].name, defs[r].flags,
522
+								defs[r].get_cbk, defs[r].get_cbk_param,
523
+								defs[r].descr, 0) <0)
524
+			return -(r+1); /* return - (idx of bad counter + 1) */
525
+	return 0;
526
+}
527
+
528
+
529
+
509 530
 /** get the value of the counter, bypassing callbacks.
510 531
  * @param handle - counter handle obtained using counter_lookup() or
511 532
  *                 counter_register().
... ...
@@ -628,6 +661,29 @@ error:
628 628
 
629 629
 
630 630
 
631
+/** return the description (doc) string for a given counter.
632
+ * @param handle - counter handle obtained using counter_lookup() or
633
+ *                 counter_register().
634
+ * @return asciiz pointer on success, 0 on error.
635
+ */
636
+char* counter_get_doc(counter_handle_t handle)
637
+{
638
+	if (unlikely(_cnts_vals == 0)) {
639
+		/* not init yet */
640
+		BUG("counters not fully initialized yet\n");
641
+		goto error;
642
+	}
643
+	if (unlikely(handle.id >= cnts_no)) {
644
+		BUG("invalid counter id %d (max %d)\n", handle.id, cnts_no - 1);
645
+		goto error;
646
+	}
647
+	return cnt_id2record[handle.id]->doc.s;
648
+error:
649
+	return 0;
650
+}
651
+
652
+
653
+
631 654
 /** iterate on all the counter group names.
632 655
  * @param cbk - pointer to a callback function that will be called for each
633 656
  *              group name.
... ...
@@ -651,7 +707,7 @@ void counter_iterate_grp_names(void (*cbk)(void* p, str* grp_name), void* p)
651 651
  * @param p   - parameter that will be passed to the callback function
652 652
  *              (along the variable name).
653 653
  */
654
-void counter_iterate_grp_var_names(	char* group,
654
+void counter_iterate_grp_var_names(	const char* group,
655 655
 									void (*cbk)(void* p, str* var_name),
656 656
 									void* p)
657 657
 {
... ...
@@ -659,7 +715,7 @@ void counter_iterate_grp_var_names(	char* group,
659 659
 	struct grp_record* g;
660 660
 	str grp;
661 661
 	
662
-	grp.s = group;
662
+	grp.s = (char*)group;
663 663
 	grp.len = strlen(group);
664 664
 	g = grp_hash_lookup(&grp);
665 665
 	if (g)
... ...
@@ -676,7 +732,7 @@ void counter_iterate_grp_var_names(	char* group,
676 676
  * @param p   - parameter that will be passed to the callback function
677 677
  *              (along the group name, variable name and variable handle).
678 678
  */
679
-void counter_iterate_grp_vars(char* group,
679
+void counter_iterate_grp_vars(const char* group,
680 680
 							  void (*cbk)(void* p, str* g, str* n,
681 681
 								  			counter_handle_t h),
682 682
 							  void *p)
... ...
@@ -685,7 +741,7 @@ void counter_iterate_grp_vars(char* group,
685 685
 	struct grp_record* g;
686 686
 	str grp;
687 687
 	
688
-	grp.s = group;
688
+	grp.s = (char*)group;
689 689
 	grp.len = strlen(group);
690 690
 	g = grp_hash_lookup(&grp);
691 691
 	if (g)
... ...
@@ -22,7 +22,7 @@
22 22
  *  Example usage:
23 23
  *  1. register (must be before forking, e.g. from mod_init()):
24 24
  *    counter_handle_t h;
25
- *    counter_register(&h, "my_counters", "foo", 0, 0, 0, 0);
25
+ *    counter_register(&h, "my_counters", "foo", 0, 0, 0, "test counter", 0);
26 26
  *  2. increment/add:
27 27
  *    counter_inc(h);
28 28
  *    counter_add(h, 100);
... ...
@@ -62,6 +62,26 @@ typedef struct counter_handle_s counter_handle_t;
62 62
 typedef struct counter_val_s counter_array_t;
63 63
 typedef counter_val_t (*counter_cbk_f)(counter_handle_t h, void* param);
64 64
 
65
+
66
+
67
+/* counter definition structure, used in zero term. arrays for more
68
+ *  convenient registration of several counters at once
69
+ *  (see counter_register_array(group, counter_array)).
70
+ */
71
+struct counter_def_s {
72
+	counter_handle_t* handle; /** if non 0, will be filled with the counter
73
+							     handle */
74
+	const char* name;         /**< counter name (inside the group) */
75
+	int flags;                /**< counter flags */
76
+	counter_cbk_f get_cbk;    /**< callback function for reading */
77
+	void* get_cbk_param;      /**< callback parameter */
78
+	const char* descr;        /**< description/documentation string */
79
+};
80
+
81
+typedef struct counter_def_s counter_def_t;
82
+
83
+
84
+
65 85
 extern counter_array_t* _cnts_vals;
66 86
 extern int _cnts_row_len; /* number of elements per row */
67 87
 
... ...
@@ -71,10 +91,15 @@ int init_counters();
71 71
 void destroy_counters();
72 72
 int counters_prefork_init(int max_process_no);
73 73
 
74
-int counter_register(	counter_handle_t* handle, char* group, char* name,
75
-						int flags, counter_cbk_f cbk, void* cbk_param,
74
+
75
+int counter_register_array(const char* group, counter_def_t* defs);
76
+int counter_register(	counter_handle_t* handle, const char* group,
77
+						const char* name, int flags,
78
+						counter_cbk_f cbk, void* cbk_param,
79
+						const char* doc,
76 80
 						int reg_flags);
77
-int counter_lookup(counter_handle_t* handle, char* group, char* name);
81
+int counter_lookup(counter_handle_t* handle,
82
+						const char* group, const char* name);
78 83
 int counter_lookup_str(counter_handle_t* handle, str* group, str* name);
79 84
 
80 85
 void counter_reset(counter_handle_t handle);
... ...
@@ -82,6 +107,7 @@ counter_val_t counter_get_val(counter_handle_t handle);
82 82
 counter_val_t counter_get_raw_val(counter_handle_t handle);
83 83
 char* counter_get_name(counter_handle_t handle);
84 84
 char* counter_get_group(counter_handle_t handle);
85
+char* counter_get_doc(counter_handle_t handle);
85 86
 
86 87
 /** gets the per process value of counter h for process p_no. */
87 88
 #define counter_pprocess_val(p_no, h) \
... ...
@@ -111,10 +137,10 @@ inline static void counter_add(counter_handle_t handle, int v)
111 111
 
112 112
 
113 113
 void counter_iterate_grp_names(void (*cbk)(void* p, str* grp_name), void* p);
114
-void counter_iterate_grp_var_names(	char* group,
114
+void counter_iterate_grp_var_names(	const char* group,
115 115
 									void (*cbk)(void* p, str* var_name),
116 116
 									void* p);
117
-void counter_iterate_grp_vars(char* group,
117
+void counter_iterate_grp_vars(const char* group,
118 118
 							  void (*cbk)(void* p, str* g, str* n,
119 119
 								  			counter_handle_t h),
120 120
 							  void *p);