2 * Copyright (C) 2020 Francis Deslauriers <francis.deslauriers@efficios.com>
4 * SPDX-License-Identifier: LGPL-2.1-only
14 #include <lttng/domain.h>
15 #include <lttng/handle.h>
17 #include <lttng/map/map-query.h>
20 struct lttng_map_list
;
22 struct lttng_map_key_value_pair
;
23 /* A list of key value pair. */
24 struct lttng_map_key_value_pair_list
;
25 /* A list of key value pair list. */
26 struct lttng_map_content
;
32 enum lttng_map_status
{
33 LTTNG_MAP_STATUS_OK
= 0,
34 LTTNG_MAP_STATUS_ERROR
= -1,
35 LTTNG_MAP_STATUS_INVALID
= -2,
36 LTTNG_MAP_STATUS_UNSET
= -3,
39 enum lttng_map_bitness
{
40 LTTNG_MAP_BITNESS_32BITS
= 32,
41 LTTNG_MAP_BITNESS_64BITS
= 64,
44 enum lttng_map_boundary_policy
{
45 LTTNG_MAP_BOUNDARY_POLICY_OVERFLOW
,
48 enum lttng_map_key_value_pair_list_type
{
49 LTTNG_MAP_KEY_VALUE_PAIR_LIST_TYPE_KERNEL
,
50 LTTNG_MAP_KEY_VALUE_PAIR_LIST_TYPE_UST_PER_UID
,
51 LTTNG_MAP_KEY_VALUE_PAIR_LIST_TYPE_UST_PER_PID
,
52 LTTNG_MAP_KEY_VALUE_PAIR_LIST_TYPE_UST_PER_PID_AGGREGATED
,
57 * Return LTTNG_MAP_STATUS_OK on success, LTTNG_MAP_STATUS_INVALID if invalid
58 * parameters are passed.
60 extern enum lttng_map_status
lttng_map_create(const char *name
,
61 unsigned int dimension_count
,
62 uint64_t *dimension_sizes
,
63 enum lttng_domain_type domain
,
64 enum lttng_buffer_type buffer_type
,
65 enum lttng_map_bitness bitness
,
66 enum lttng_map_boundary_policy boundary_policy
,
68 struct lttng_map
**map
);
70 extern enum lttng_map_status
lttng_map_get_name(
71 const struct lttng_map
*map
, const char **name
);
73 extern enum lttng_map_status
lttng_map_set_name(
74 struct lttng_map
*map
, const char *name
);
77 * Get the number of dimensions.
80 extern unsigned int lttng_map_get_dimension_count(
81 const struct lttng_map
*map
);
84 * Get the number of elements for the provided dimension.
86 * Return LTTNG_MAP_STATUS_OK on success, LTTNG_MAP_STATUS_INVALID if invalid
87 * parameters are passed.
90 extern enum lttng_map_status
lttng_map_get_dimension_length(
91 const struct lttng_map
*map
, unsigned int dimension
,
92 uint64_t *dimension_length
);
94 extern int lttng_map_get_is_enabled(const struct lttng_map
*map
);
96 extern enum lttng_map_bitness
lttng_map_get_bitness(
97 const struct lttng_map
*map
);
99 extern enum lttng_domain_type
lttng_map_get_domain(
100 const struct lttng_map
*map
);
102 extern enum lttng_buffer_type
lttng_map_get_buffer_type(
103 const struct lttng_map
*map
);
105 extern enum lttng_map_boundary_policy
lttng_map_get_boundary_policy(
106 const struct lttng_map
*map
);
108 extern bool lttng_map_get_coalesce_hits(
109 const struct lttng_map
*map
);
111 extern void lttng_map_destroy(struct lttng_map
*map
);
113 extern enum lttng_error_code
lttng_add_map(struct lttng_handle
*handle
,
114 struct lttng_map
*map
);
116 extern enum lttng_error_code
lttng_enable_map(struct lttng_handle
*handle
,
117 const char *map_name
);
119 extern enum lttng_error_code
lttng_disable_map(struct lttng_handle
*handle
,
120 const char *map_name
);
124 * Get a map from the list at a given index.
126 * Note that the map list maintains the ownership of the returned map.
127 * It must not be destroyed by the user, nor should a reference to it be held
128 * beyond the lifetime of the map list.
130 * Returns a map, or NULL on error.
132 extern const struct lttng_map
*lttng_map_list_get_at_index(
133 const struct lttng_map_list
*map_list
, unsigned int index
);
136 * Get the number of map in a map list.
139 extern enum lttng_map_status
lttng_map_list_get_count(
140 const struct lttng_map_list
*map_list
, unsigned int *count
);
143 * Destroy a map list.
145 extern void lttng_map_list_destroy(struct lttng_map_list
*map_list
);
147 extern enum lttng_error_code
lttng_list_maps(struct lttng_handle
*handle
,
148 struct lttng_map_list
**map_list
);
151 * FIXME: frdeso proper explanation
152 * lttng_map_content 1 to N lttng_map_key_value_pair_list
153 * lttng_map_key_value_pair_list 1 to N lttng_map_key_value_pair
157 * Get the key of a key-value.
159 * The caller does not assume the ownership of the returned key.
160 * The key shall only be used for the duration of the key-value's lifetime.
162 * Returns LTTNG_MAP_STATUS_OK and a pointer to the key-value's key on success,
163 * LTTNG_MAP_STATUS_INVALID if an invalid parameter is passed, or
165 extern enum lttng_map_status
lttng_map_key_value_pair_get_key(
166 const struct lttng_map_key_value_pair
*kv_pair
, const char **key
);
168 extern bool lttng_map_key_value_pair_get_has_overflowed(
169 const struct lttng_map_key_value_pair
*key_value
);
171 extern bool lttng_map_key_value_pair_get_has_underflowed(
172 const struct lttng_map_key_value_pair
*key_value
);
174 * Get the value of a key-value.
176 * The caller does not assume the ownership of the returned value.
177 * The value shall only be used for the duration of the key-value's lifetime.
179 * Returns LTTNG_MAP_STATUS_OK and a pointer to the key-value's value on success,
180 * LTTNG_MAP_STATUS_INVALID if an invalid parameter is passed.
182 extern enum lttng_map_status
lttng_map_key_value_pair_get_value(
183 const struct lttng_map_key_value_pair
*kv_pair
, int64_t *value
);
185 extern enum lttng_map_status
lttng_map_content_get_count(
186 const struct lttng_map_content
*map_content
,
187 unsigned int *count
);
189 extern const struct lttng_map_key_value_pair_list
*lttng_map_content_get_at_index(
190 const struct lttng_map_content
*map_content
,
193 * List all key-value pairs for the given session and map.
195 * On success, a newly-allocated key-value list is returned.
197 * The key-value list must be destroyed by the caller (see
198 * lttng_map_key_value_pair_list_destroy()).
200 * Returns LTTNG_OK on success, else a suitable LTTng error code.
202 extern enum lttng_error_code
lttng_list_map_content(
203 struct lttng_handle
*handle
, const struct lttng_map
*map
,
204 const struct lttng_map_query
*map_query
,
205 struct lttng_map_content
**map_content
);
207 extern enum lttng_buffer_type
lttng_map_content_get_buffer_type(
208 const struct lttng_map_content
*map_content
);
210 extern void lttng_map_content_destroy(
211 struct lttng_map_content
*map_content
);
213 * Get a key-value from the list at a given index.
215 * Note that the key value list maintains the ownership of the returned key
217 * It must not be destroyed by the user, nor should a reference to it be held
218 * beyond the lifetime of the key value list.
220 * Returns a key-value, or NULL on error.
222 extern const struct lttng_map_key_value_pair
*lttng_map_key_value_pair_list_get_at_index(
223 const struct lttng_map_key_value_pair_list
*kv_pair_list
,
227 * Get the number of key value pair in a key-value list.
229 * Return LTTNG_MAP_STATUS_OK on success,
230 * LTTNG_MAP_STATUS_INVALID when invalid parameters are passed.
232 extern enum lttng_map_status
lttng_map_key_value_pair_list_get_count(
233 const struct lttng_map_key_value_pair_list
*kv_pair_list
,
234 unsigned int *count
);
236 extern enum lttng_map_key_value_pair_list_type
lttng_map_key_value_pair_list_get_type(
237 const struct lttng_map_key_value_pair_list
*kv_pair_list
);
239 extern uint64_t lttng_map_key_value_pair_list_get_identifer(
240 const struct lttng_map_key_value_pair_list
*kv_pair_list
);
242 extern uint64_t lttng_map_key_value_pair_list_get_cpu(
243 const struct lttng_map_key_value_pair_list
*kv_pair_list
);
245 extern bool lttng_map_key_value_pair_list_get_summed_all_cpu(
246 const struct lttng_map_key_value_pair_list
*kv_pair_list
);
249 * Destroy a map_key_value set.
251 extern void lttng_map_key_value_pair_list_destroy(
252 struct lttng_map_key_value_pair_list
*kv_pair_list
);
258 #endif /* LTTNG_MAP_H */