summaryrefslogtreecommitdiff
path: root/cesar/lib/restrack.h
blob: af530583b8550c8fab76e043000d6dd25a0ea423 (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
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
#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 "config/restrack.h"

/* Macro helpers. */
#if CONFIG_RESTRACK

# define _FL const char *function, int line
# define void_FL _FL
# define __FL , _FL
# define _fL __func__, __LINE__
# define __fL , _fL
# define _fl function, line
# define __fl , _fl
# define _fl_ function, line

#else /* !CONFIG_RESTRACK */

# define _FL
# define void_FL void
# define __FL
# define _fL
# define __fL
# define _fl
# define __fl
# define _fl_ NULL, 0

#endif /* !CONFIG_RESTRACK */

#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 */