src/daemon/utils_cache.h: Improve documentation for uc_iterator_get_next().
[collectd.git] / src / daemon / utils_cache.h
1 /**
2  * collectd - utils_cache.h
3  * Copyright (C) 2007       Florian octo Forster
4  * Copyright (C) 2016       Sebastian tokkee Harl
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a
7  * copy of this software and associated documentation files (the "Software"),
8  * to deal in the Software without restriction, including without limitation
9  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
10  * and/or sell copies of the Software, and to permit persons to whom the
11  * Software is furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included in
14  * all copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22  * DEALINGS IN THE SOFTWARE.
23  *
24  * Authors:
25  *   Florian octo Forster <octo at collectd.org>
26  *   Sebastian tokkee Harl <sh at tokkee.org>
27  **/
28
29 #ifndef UTILS_CACHE_H
30 #define UTILS_CACHE_H 1
31
32 #include "plugin.h"
33
34 #define STATE_OKAY     0
35 #define STATE_WARNING  1
36 #define STATE_ERROR    2
37 #define STATE_MISSING 15
38
39 int uc_init (void);
40 int uc_check_timeout (void);
41 int uc_update (const data_set_t *ds, const value_list_t *vl);
42 int uc_get_rate_by_name (const char *name, gauge_t **ret_values, size_t *ret_values_num);
43 gauge_t *uc_get_rate (const data_set_t *ds, const value_list_t *vl);
44
45 size_t uc_get_size (void);
46 int uc_get_names (char ***ret_names, cdtime_t **ret_times, size_t *ret_number);
47
48 int uc_get_state (const data_set_t *ds, const value_list_t *vl);
49 int uc_set_state (const data_set_t *ds, const value_list_t *vl, int state);
50 int uc_get_hits (const data_set_t *ds, const value_list_t *vl);
51 int uc_set_hits (const data_set_t *ds, const value_list_t *vl, int hits);
52 int uc_inc_hits (const data_set_t *ds, const value_list_t *vl, int step);
53
54 int uc_get_history (const data_set_t *ds, const value_list_t *vl,
55     gauge_t *ret_history, size_t num_steps, size_t num_ds);
56 int uc_get_history_by_name (const char *name,
57     gauge_t *ret_history, size_t num_steps, size_t num_ds);
58
59 /*
60  * Iterator interface
61  */
62 struct uc_iter_s;
63 typedef struct uc_iter_s uc_iter_t;
64
65 /*
66  * NAME
67  *   uc_get_iterator
68  *
69  * DESCRIPTION
70  *   Create an iterator for the cache. It will hold the cache lock until it's
71  *   destroyed.
72  *
73  * RETURN VALUE
74  *   An iterator object on success or NULL else.
75  */
76 uc_iter_t *uc_get_iterator (void);
77
78 /*
79  * NAME
80  *   uc_iterator_next
81  *
82  * DESCRIPTION
83  *   Advance the iterator to the next positiion and (optionally) returns the
84  *   name of the entry.
85  *
86  * PARAMETERS
87  *   `iter'     The iterator object to advance.
88  *   `ret_name' Optional pointer to a string where to store the name. If not
89  *              NULL, the returned value is a copy of the value and has to be
90  *              freed by the caller.
91  *
92  * RETURN VALUE
93  *   Zero upon success or non-zero if the iterator ie NULL or no further
94  *   values are available.
95  */
96 int uc_iterator_next (uc_iter_t *iter, char **ret_name);
97 void uc_iterator_destroy (uc_iter_t *iter);
98
99 /* Return the timestamp of the value at the current position. */
100 int uc_iterator_get_time (uc_iter_t *iter, cdtime_t *ret_time);
101 /* Return the (raw) value at the current position. */
102 int uc_iterator_get_values (uc_iter_t *iter, value_t **ret_values, size_t *ret_num);
103 /* Return the interval of the value at the current position. */
104 int uc_iterator_get_interval (uc_iter_t *iter, cdtime_t *ret_interval);
105
106 /*
107  * Meta data interface
108  */
109 int uc_meta_data_exists (const value_list_t *vl, const char *key);
110 int uc_meta_data_delete (const value_list_t *vl, const char *key);
111
112 int uc_meta_data_add_string (const value_list_t *vl,
113     const char *key,
114     const char *value);
115 int uc_meta_data_add_signed_int (const value_list_t *vl,
116     const char *key,
117     int64_t value);
118 int uc_meta_data_add_unsigned_int (const value_list_t *vl,
119     const char *key,
120     uint64_t value);
121 int uc_meta_data_add_double (const value_list_t *vl,
122     const char *key,
123     double value);
124 int uc_meta_data_add_boolean (const value_list_t *vl,
125     const char *key,
126     _Bool value);
127
128 int uc_meta_data_get_string (const value_list_t *vl,
129     const char *key,
130     char **value);
131 int uc_meta_data_get_signed_int (const value_list_t *vl,
132     const char *key,
133     int64_t *value);
134 int uc_meta_data_get_unsigned_int (const value_list_t *vl,
135     const char *key,
136     uint64_t *value);
137 int uc_meta_data_get_double (const value_list_t *vl,
138     const char *key,
139     double *value);
140 int uc_meta_data_get_boolean (const value_list_t *vl,
141     const char *key,
142     _Bool *value);
143
144 /* vim: set shiftwidth=2 softtabstop=2 tabstop=8 : */
145 #endif /* !UTILS_CACHE_H */