include/lttng/map/map.h

   1 /*
   2  * Copyright (C) 2020 Francis Deslauriers <francis.deslauriers@efficios.com>
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-only
   5  *
   6  */
   7
   8 #ifndef LTTNG_MAP_H
   9 #define LTTNG_MAP_H
  10
  11 #include <stddef.h>
  12 #include <stdbool.h>
  13
  14 #include <lttng/domain.h>
  15 #include <lttng/handle.h>
  16
  17 #include <lttng/map/map-query.h>
  18
  19 struct lttng_map;
  20 struct lttng_map_list;
  21
  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;
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  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,
  37 };
  38
  39 enum lttng_map_bitness {
  40         LTTNG_MAP_BITNESS_32BITS = 32,
  41         LTTNG_MAP_BITNESS_64BITS = 64,
  42 };
  43
  44 enum lttng_map_boundary_policy {
  45         LTTNG_MAP_BOUNDARY_POLICY_OVERFLOW,
  46 };
  47
  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,
  53 };
  54
  55 /*
  56  *
  57  * Return LTTNG_MAP_STATUS_OK on success, LTTNG_MAP_STATUS_INVALID if invalid
  58  * parameters are passed.
  59  */
  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,
  67                 bool coalesce_hits,
  68                 struct lttng_map **map);
  69
  70 extern enum lttng_map_status lttng_map_get_name(
  71                 const struct lttng_map *map, const char **name);
  72
  73 extern enum lttng_map_status lttng_map_set_name(
  74                 struct lttng_map *map, const char *name);
  75
  76 /*
  77  * Get the number of dimensions.
  78  *
  79  */
  80 extern unsigned int lttng_map_get_dimension_count(
  81                 const struct lttng_map *map);
  82
  83 /*
  84  * Get the number of elements for the provided dimension.
  85  *
  86  * Return LTTNG_MAP_STATUS_OK on success, LTTNG_MAP_STATUS_INVALID if invalid
  87  * parameters are passed.
  88  *
  89  */
  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);
  93
  94 extern int lttng_map_get_is_enabled(const struct lttng_map *map);
  95
  96 extern enum lttng_map_bitness lttng_map_get_bitness(
  97                 const struct lttng_map *map);
  98
  99 extern enum lttng_domain_type lttng_map_get_domain(
 100                 const struct lttng_map *map);
 101
 102 extern enum lttng_buffer_type lttng_map_get_buffer_type(
 103                 const struct lttng_map *map);
 104
 105 extern enum lttng_map_boundary_policy lttng_map_get_boundary_policy(
 106                 const struct lttng_map *map);
 107
 108 extern bool lttng_map_get_coalesce_hits(
 109                 const struct lttng_map *map);
 110
 111 extern void lttng_map_destroy(struct lttng_map *map);
 112
 113 extern enum lttng_error_code lttng_add_map(struct lttng_handle *handle,
 114                 struct lttng_map *map);
 115
 116 extern enum lttng_error_code lttng_enable_map(struct lttng_handle *handle,
 117                 const char *map_name);
 118
 119 extern enum lttng_error_code lttng_disable_map(struct lttng_handle *handle,
 120                 const char *map_name);
 121
 122
 123 /*
 124  * Get a map from the list at a given index.
 125  *
 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.
 129  *
 130  * Returns a map, or NULL on error.
 131  */
 132 extern const struct lttng_map *lttng_map_list_get_at_index(
 133                 const struct lttng_map_list *map_list, unsigned int index);
 134
 135 /*
 136  * Get the number of map in a map list.
 137  */
 138
 139 extern enum lttng_map_status lttng_map_list_get_count(
 140                 const struct lttng_map_list *map_list, unsigned int *count);
 141
 142 /*
 143  * Destroy a map list.
 144  */
 145 extern void lttng_map_list_destroy(struct lttng_map_list *map_list);
 146
 147 extern enum lttng_error_code lttng_list_maps(struct lttng_handle *handle,
 148                 struct lttng_map_list **map_list);
 149
 150 /*
 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
 154  */
 155
 156 /*
 157  * Get the key of a key-value.
 158  *
 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.
 161  *
 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
 164  */
 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);
 167
 168 extern bool lttng_map_key_value_pair_get_has_overflowed(
 169                 const struct lttng_map_key_value_pair *key_value);
 170
 171 extern bool lttng_map_key_value_pair_get_has_underflowed(
 172                 const struct lttng_map_key_value_pair *key_value);
 173 /*
 174  * Get the value of a key-value.
 175  *
 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.
 178  *
 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.
 181  */
 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);
 184
 185 extern enum lttng_map_status lttng_map_content_get_count(
 186                 const struct lttng_map_content *map_content,
 187                 unsigned int *count);
 188
 189 extern const struct lttng_map_key_value_pair_list *lttng_map_content_get_at_index(
 190                 const struct lttng_map_content *map_content,
 191                 unsigned int index);
 192 /*
 193  * List all key-value pairs for the given session and map.
 194  *
 195  * On success, a newly-allocated key-value list is returned.
 196  *
 197  * The key-value list must be destroyed by the caller (see
 198  * lttng_map_key_value_pair_list_destroy()).
 199  *
 200  * Returns LTTNG_OK on success, else a suitable LTTng error code.
 201  */
 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);
 206
 207 extern enum lttng_buffer_type lttng_map_content_get_buffer_type(
 208                         const struct lttng_map_content *map_content);
 209
 210 extern void lttng_map_content_destroy(
 211                 struct lttng_map_content *map_content);
 212 /*
 213  * Get a key-value from the list at a given index.
 214  *
 215  * Note that the key value list maintains the ownership of the returned key
 216  * value.
 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.
 219  *
 220  * Returns a key-value, or NULL on error.
 221  */
 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,
 224                 unsigned int index);
 225
 226 /*
 227  * Get the number of key value pair in a key-value list.
 228  *
 229  * Return LTTNG_MAP_STATUS_OK on success,
 230  * LTTNG_MAP_STATUS_INVALID when invalid parameters are passed.
 231  */
 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);
 235
 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);
 238
 239 extern uint64_t lttng_map_key_value_pair_list_get_identifer(
 240                 const struct lttng_map_key_value_pair_list *kv_pair_list);
 241
 242 extern uint64_t lttng_map_key_value_pair_list_get_cpu(
 243                 const struct lttng_map_key_value_pair_list *kv_pair_list);
 244
 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);
 247
 248 /*
 249  * Destroy a map_key_value set.
 250  */
 251 extern void lttng_map_key_value_pair_list_destroy(
 252                 struct lttng_map_key_value_pair_list *kv_pair_list);
 253
 254 #ifdef __cplusplus
 255 }
 256 #endif
 257
 258 #endif /* LTTNG_MAP_H */