summaryrefslogtreecommitdiff
path: root/cesar/lib/restrack.h
blob: 44b74e9bc28bcf37ae69eb93699040e1a33d7d59 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
#ifndef restrack_h
#define restrack_h
/* Cesar project {{{
 *
 * Copyright (C) 2007 Spidcom
 *
 * <<<Licence>>>
 *
 * }}} */
/**
 * \file    lib/restrack.h
 * \brief   Resources tracker.
 * \ingroup lib
 *
 * The resources tracker is a debugging tool to trace resources allocations
 * and releases.
 *
 * It provides services to track resources references with two flavors.
 *
 * The first one and simpler one (lite) will record all the places where
 * allocations and releases are done during the whole resource life time.
 * This flavor can not determine current resource owner because it can not
 * associate the source line recorded with the owner.
 *
 * The second flavor (full) will request an extra argument for each allocation
 * and release.  This argument is an owner of the resources.  This flavor can
 * track much more errors as it can detect wrong releases and will bark if a
 * resources is freed while it still own other resources.
 *
 * At any time, the user can check for unbalanced resources allocations or
 * releases.
 *
 * Use CONFIG_RESTRACK to enable Resources tracker.
 *
 * Use CONFIG_RESTRACK_KEEP to keep records of destructed resources (not safe,
 * but may be useful for debug in some cases).
 */
#include "lib/blame.h"

#include "config/restrack.h"

#if CONFIG_RESTRACK

BEGIN_DECLS

/**
 * Create a resource reference counter.
 * \param  owner  owner of the resource, ignored for the lite flavor
 * \param  resource  resource referenced
 * \param  function  function name (__func__)
 * \param  line  source line
 * \param  initial  reference counter initial value
 */
void
restrack_create (void *owner, void *resource, const char *function, int line,
                 int initial);

/**
 * Update a resource reference counter.
 * \param  owner  owner of the resource, ignored for the lite flavor
 * \param  resource  resource referenced
 * \param  function  function name (__func__)
 * \param  line  source line
 * \param  change  reference counter change
 */
void
restrack_update (void *owner, void *resource, const char *function, int line,
                 int change);

/**
 * Destroy a resource reference counter.
 * \param  owner  owner of the resource, ignored for the lite flavor
 * \param  resource  resource referenced
 * \param  function  function name (__func__)
 * \param  line  source line
 * \param  change  reference counter change
 *
 * Will check if the counter reaches zero.
 */
void
restrack_destroy (void *owner, void *resource, const char *function, int line,
                  int change);

/**
 * Check that the current state of resources allocations is balanced.
 * \return  true if no unbalanced resource.
 *
 * Will output statistics for any unbalanced resources.
 */
bool
restrack_check (void);

/**
 * Free all memory used by the Resources Tracker.
 *
 * Useful for memory leaks analysis.  Called automatically on exit.
 */
void
restrack_uninit (void);

END_DECLS

#else /* !CONFIG_RESTRACK */

# define restrack_create(...) ((void) 0)
# define restrack_update(...) ((void) 0)
# define restrack_destroy(...) ((void) 0)
# define restrack_check() true
# define restrack_uninit() ((void) 0)

#endif /* !CONFIG_RESTRACK */

#endif /* restrack_h */