1 /* Copyright © 2012 Brandon L Black <blblack@gmail.com>
2 *
3 * This file is part of gdnsd.
4 *
5 * gdnsd is free software: you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation, either version 3 of the License, or
8 * (at your option) any later version.
9 *
10 * gdnsd is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License
16 * along with gdnsd. If not, see <http://www.gnu.org/licenses/>.
17 *
18 */
19
20 #ifndef GDNSD_STATS_H
21 #define GDNSD_STATS_H
22
23 #include <gdnsd/compiler.h>
24 #include <gdnsd/dmn.h>
25
26 #include <inttypes.h>
27
28 /*
29 * This header defines two data types named stats_t and stats_uint_t,
30 * and several accessor functions for them.
31 *
32 * stats_t is used to implement an uint-like peice of data which is
33 * shared (without barriers or locking) between multiple threads
34 * and/or CPUs with the following very important caveats:
35 *
36 * 1) One thread is the "owner", and is the only thread performing
37 * write operations to the value within stats_t.
38 * 2) Non-owner threads only read the data, using stats_get().
39 * 3) The usage of the stats_t must be such that there are no data
40 * dependencies on it for correctness. In other words: pay attention
41 * to the word "stats" in the type name; this is intended for storing
42 * and retrieving statistical data which have no bearing on correct
43 * program execution.
44 * 4) Further, it's important to realize that the writes will only
45 * be seen by the non-owner threads "when the CPU feels like it". On
46 * modern mainstream systems with reasonable cache coherency, this
47 * generally happens "pretty soon", soon enough that it doesn't matter
48 * for stats accounting. There is no actual gaurantee on when the
49 * update becomes visible in the general case, and it might *never*
50 * become visible on some exotic architectures that gdnsd doesn't
51 * care to support at this time.
52 *
53 * stats_uint_t is simply an regular unsigned type of some width that
54 * matches the internal width of stats_t. You can store the result
55 * of stats_get() in such a type to cache it thread-locally for a while
56 * in cases where that makes sense.
57 *
58 * The width of the types currently matches uintptr_t (the width of a
59 * pointer), because most mainstream architectures are atomic for
60 * this size of aligned memory access (not atomic in the SMP sense,
61 * atomic in the "you won't read a half-updated value" sense).
62 */
63
64 typedef uintptr_t stats_uint_t;
65 typedef struct { stats_uint_t _x; } stats_t;
66
67 // stats_own_set() -> set the stats value from the owner thread only
68 F_NONNULL F_UNUSED
stats_own_set(stats_t * s,const stats_uint_t v)69 static void stats_own_set(stats_t* s, const stats_uint_t v) { s->_x = v; }
70
71 // stats_own_inc() -> increment stats value from the owner thread only
72 F_NONNULL F_UNUSED
stats_own_inc(stats_t * s)73 static void stats_own_inc(stats_t* s) { s->_x++; }
74
75 // stats_own_get() -> read the value from the owner thread
76 F_NONNULL F_UNUSED
stats_own_get(const stats_t * s)77 static stats_uint_t stats_own_get(const stats_t* s) { return s->_x; }
78
79 // stats_get() -> read the value from any other thread
80 F_NONNULL F_UNUSED
stats_get(const stats_t * s)81 static stats_uint_t stats_get(const stats_t* s)
82 { return *(const volatile stats_uint_t*)&s->_x; }
83
84 #endif // GDNSD_STATS_H
85