1 /*
2 ** Zabbix
3 ** Copyright (C) 2001-2021 Zabbix SIA
4 **
5 ** This program 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 2 of the License, or
8 ** (at your option) any later version.
9 **
10 ** This program 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 this program; if not, write to the Free Software
17 ** Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
18 **/
19 
20 #ifndef ZABBIX_VALUECACHE_H
21 #define ZABBIX_VALUECACHE_H
22 
23 #include "zbxtypes.h"
24 #include "zbxalgo.h"
25 #include "zbxhistory.h"
26 #include "memalloc.h"
27 
28 /*
29  * The Value Cache provides read caching of item historical data residing in history
30  * tables. No components must read history tables manually. Instead all history data
31  * must be read from the Value Cache.
32  *
33  * Usage notes:
34  *
35  * Initialization
36  *
37  *   The value cache must be initialized at the start of the program with zbx_vc_init()
38  *   function. To ensure proper removal of shared memory the value cache must be destroyed
39  *   upon a program exit with zbx_vc_destroy() function.
40  *
41  * Adding data
42  *
43  *   Whenever a new item value is added to system (history tables) the item value must be
44  *   also added added to Value Cache with zbx_dc_add_value() function to keep it up to date.
45  *
46  * Retrieving data
47  *
48  *   The history data is accessed with zbx_vc_get_values() and zbx_vc_get_value()
49  *   functions. Afterwards the retrieved history data must be freed by the caller by using
50  *   either zbx_history_record_vector_destroy() function (free the zbx_vc_get_values()
51  *   call output) or zbx_history_record_clear() function (free the zbx_vc_get_value() call output).
52  *
53  * Locking
54  *
55  *   The cache ensures synchronization between processes by using automatic locks whenever
56  *   a cache function (zbx_vc_*) is called and by providing manual cache locking functionality
57  *   with zbx_vc_lock()/zbx_vc_unlock() functions.
58  *
59  */
60 
61 #define ZBX_VC_MODE_NORMAL	0
62 #define ZBX_VC_MODE_LOWMEM	1
63 
64 /* indicates that all values from database are cached */
65 #define ZBX_ITEM_STATUS_CACHED_ALL	1
66 
67 /* the cache statistics */
68 typedef struct
69 {
70 	/* Value cache misses are new values cached during request and hits are calculated by  */
71 	/* subtracting misses from the total number of values returned (0 if the number of     */
72 	/* returned values is less than misses.                                                */
73 	/* When performing count based requests the number of cached values might be greater   */
74 	/* than number of returned values. This can skew the hits/misses ratio towards misses. */
75 	zbx_uint64_t	hits;
76 	zbx_uint64_t	misses;
77 
78 	zbx_uint64_t	total_size;
79 	zbx_uint64_t	free_size;
80 
81 	/* value cache operating mode - see ZBX_VC_MODE_* defines */
82 	int		mode;
83 }
84 zbx_vc_stats_t;
85 
86 /* item diagnostic statistics */
87 typedef struct
88 {
89 	zbx_uint64_t	itemid;
90 	int		values_num;
91 	int		hourly_num;
92 }
93 zbx_vc_item_stats_t;
94 
95 int	zbx_vc_init(char **error);
96 
97 void	zbx_vc_destroy(void);
98 
99 void	zbx_vc_reset(void);
100 
101 void	zbx_vc_enable(void);
102 
103 void	zbx_vc_disable(void);
104 
105 int	zbx_vc_get_values(zbx_uint64_t itemid, int value_type, zbx_vector_history_record_t *values, int seconds,
106 		int count, const zbx_timespec_t *ts);
107 
108 int	zbx_vc_get_value(zbx_uint64_t itemid, int value_type, const zbx_timespec_t *ts, zbx_history_record_t *value);
109 
110 int	zbx_vc_add_values(zbx_vector_ptr_t *history);
111 
112 int	zbx_vc_get_statistics(zbx_vc_stats_t *stats);
113 
114 void	zbx_vc_housekeeping_value_cache(void);
115 
116 void	zbx_vc_get_diag_stats(zbx_uint64_t *items_num, zbx_uint64_t *values_num, int *mode);
117 void	zbx_vc_get_mem_stats(zbx_mem_stats_t *mem);
118 void	zbx_vc_get_item_stats(zbx_vector_ptr_t *stats);
119 void	zbx_vc_flush_stats(void);
120 
121 #endif	/* ZABBIX_VALUECACHE_H */
122