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 
27 /*
28  * The Value Cache provides read caching of item historical data residing in history
29  * tables. No components must read history tables manually. Instead all history data
30  * must be read from the Value Cache.
31  *
32  * Usage notes:
33  *
34  * Initialization
35  *
36  *   The value cache must be initialized at the start of the program with zbx_vc_init()
37  *   function. To ensure proper removal of shared memory the value cache must be destroyed
38  *   upon a program exit with zbx_vc_destroy() function.
39  *
40  * Adding data
41  *
42  *   Whenever a new item value is added to system (history tables) the item value must be
43  *   also added added to Value Cache with zbx_dc_add_value() function to keep it up to date.
44  *
45  * Retrieving data
46  *
47  *   The history data is accessed with zbx_vc_get_values() and zbx_vc_get_value()
48  *   functions. Afterwards the retrieved history data must be freed by the caller by using
49  *   either zbx_history_record_vector_destroy() function (free the zbx_vc_get_values()
50  *   call output) or zbx_history_record_clear() function (free the zbx_vc_get_value() call output).
51  *
52  * Locking
53  *
54  *   The cache ensures synchronization between processes by using automatic locks whenever
55  *   a cache function (zbx_vc_*) is called and by providing manual cache locking functionality
56  *   with zbx_vc_lock()/zbx_vc_unlock() functions.
57  *
58  */
59 
60 #define ZBX_VC_MODE_NORMAL	0
61 #define ZBX_VC_MODE_LOWMEM	1
62 
63 /* indicates that all values from database are cached */
64 #define ZBX_ITEM_STATUS_CACHED_ALL	1
65 
66 /* the cache statistics */
67 typedef struct
68 {
69 	/* Value cache misses are new values cached during request and hits are calculated by  */
70 	/* subtracting misses from the total number of values returned (0 if the number of     */
71 	/* returned values is less than misses.                                                */
72 	/* When performing count based requests the number of cached values might be greater   */
73 	/* than number of returned values. This can skew the hits/misses ratio towards misses. */
74 	zbx_uint64_t	hits;
75 	zbx_uint64_t	misses;
76 
77 	zbx_uint64_t	total_size;
78 	zbx_uint64_t	free_size;
79 
80 	/* value cache operating mode - see ZBX_VC_MODE_* defines */
81 	int		mode;
82 }
83 zbx_vc_stats_t;
84 
85 int	zbx_vc_init(char **error);
86 
87 void	zbx_vc_destroy(void);
88 
89 void	zbx_vc_reset(void);
90 
91 void	zbx_vc_lock(void);
92 
93 void	zbx_vc_unlock(void);
94 
95 void	zbx_vc_enable(void);
96 
97 void	zbx_vc_disable(void);
98 
99 int	zbx_vc_get_values(zbx_uint64_t itemid, int value_type, zbx_vector_history_record_t *values, int seconds,
100 		int count, const zbx_timespec_t *ts);
101 
102 int	zbx_vc_get_value(zbx_uint64_t itemid, int value_type, const zbx_timespec_t *ts, zbx_history_record_t *value);
103 
104 int	zbx_vc_add_values(zbx_vector_ptr_t *history);
105 
106 int	zbx_vc_get_statistics(zbx_vc_stats_t *stats);
107 
108 void	zbx_vc_housekeeping_value_cache(void);
109 
110 #endif	/* ZABBIX_VALUECACHE_H */
111