libcircllhist
circllhist.h
Go to the documentation of this file.
1
2/*
3 * Copyright (c) 2016-2021, Circonus, Inc.
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18
23#ifndef CIRCLLHIST_H
24#define CIRCLLHIST_H
25
26#if defined(WIN32)
27#include <basetsd.h>
28typedef SSIZE_T ssize_t;
29#endif
30
31#ifdef __cplusplus
32extern "C" { /* FFI_SKIP */
33#endif
34
35#define DEFAULT_HIST_SIZE 100
37#define HIST_BUCKET_MAX_STRING_SIZE 9
38#define API_EXPORT(type) extern type
39#include <stdlib.h>
40#include <sys/types.h>
41#include <stdint.h>
42
43typedef struct histogram histogram_t;
44typedef struct hist_rollup_config hist_rollup_config_t;
51typedef struct hist_bucket {
52 int8_t val;
53 int8_t exp;
55
56typedef struct hist_allocator {
57 void *(*malloc)(size_t);
58 void *(*calloc)(size_t, size_t);
59 void (*free)(void *);
61
63// Histogram buckets
64
66API_EXPORT(double) hist_bucket_to_double(hist_bucket_t hb);
68API_EXPORT(double) hist_bucket_midpoint(hist_bucket_t in);
74API_EXPORT(hist_bucket_t) int_scale_to_hist_bucket(int64_t value, int scale);
92API_EXPORT(int) hist_bucket_to_string(hist_bucket_t hb, char *buf);
93
95// Creating and destroying histograms
96
98API_EXPORT(histogram_t *) hist_alloc(void);
100API_EXPORT(histogram_t *) hist_alloc_nbins(int nbins);
102
105API_EXPORT(histogram_t *) hist_fast_alloc(void);
107API_EXPORT(histogram_t *) hist_fast_alloc_nbins(int nbins);
109API_EXPORT(histogram_t *) hist_clone(const histogram_t *other);
110
112API_EXPORT(histogram_t *) hist_alloc_with_allocator(const hist_allocator_t *alloc);
114API_EXPORT(histogram_t *) hist_alloc_nbins_with_allocator(int nbins, const hist_allocator_t *alloc);
116
119API_EXPORT(histogram_t *) hist_fast_alloc_with_allocator(const hist_allocator_t *alloc);
121API_EXPORT(histogram_t *) hist_fast_alloc_nbins_with_allocator(int nbins, const hist_allocator_t *alloc);
123API_EXPORT(histogram_t *) hist_clone_with_allocator(const histogram_t *other, const hist_allocator_t *alloc);
124
126API_EXPORT(void) hist_free(histogram_t *hist);
127
129// Getting data in and out of histograms
130
136API_EXPORT(uint64_t) hist_insert(histogram_t *hist, double val, uint64_t count);
138API_EXPORT(uint64_t) hist_remove(histogram_t *hist, double val, uint64_t count);
140API_EXPORT(uint64_t) hist_remove_raw(histogram_t *hist, hist_bucket_t hb, uint64_t count);
145API_EXPORT(uint64_t) hist_insert_raw(histogram_t *hist, hist_bucket_t hb, uint64_t count);
148API_EXPORT(uint64_t) hist_insert_raw_end(histogram_t *hist, hist_bucket_t hb, uint64_t count);
150API_EXPORT(int) hist_bucket_count(const histogram_t *hist);
152API_EXPORT(int) hist_num_buckets(const histogram_t *hist);
154API_EXPORT(uint64_t) hist_sample_count(const histogram_t *hist);
156API_EXPORT(int) hist_bucket_idx(const histogram_t *hist, int idx, double *v, uint64_t *c);
158API_EXPORT(int) hist_bucket_idx_bucket(const histogram_t *hist, int idx, hist_bucket_t *b, uint64_t *c);
160API_EXPORT(int) hist_accumulate(histogram_t *tgt, const histogram_t * const *src, int cnt);
162API_EXPORT(int) hist_subtract(histogram_t *tgt, const histogram_t * const *src, int cnt);
164API_EXPORT(int) hist_subtract_as_int64(histogram_t *tgt, const histogram_t *src);
166API_EXPORT(int) hist_add_as_int64(histogram_t *tgt, const histogram_t *src);
168API_EXPORT(void) hist_downsample(histogram_t *tgt, double factor);
170API_EXPORT(void) hist_clear(histogram_t *hist);
172API_EXPORT(uint64_t) hist_insert_intscale(histogram_t *hist, int64_t val, int scale, uint64_t count);
173
175// Serialization
176
178API_EXPORT(ssize_t) hist_serialize(const histogram_t *h, void *buff, ssize_t len);
179API_EXPORT(ssize_t) hist_deserialize(histogram_t *h, const void *buff, ssize_t len);
180API_EXPORT(ssize_t) hist_serialize_estimate(const histogram_t *h);
182API_EXPORT(ssize_t) hist_serialize_b64(const histogram_t *h, char *b64_serialized_histo_buff, ssize_t buff_len);
183API_EXPORT(ssize_t) hist_deserialize_b64(histogram_t *h, const void *b64_string, ssize_t b64_string_len);
184API_EXPORT(ssize_t) hist_serialize_b64_estimate(const histogram_t *h);
185
186API_EXPORT(void) hist_remove_zeroes(histogram_t *h);
194API_EXPORT(histogram_t *) hist_compress_mbe(const histogram_t *h, int8_t mbe);
195
197// Analytics
198
200API_EXPORT(double) hist_approx_mean(const histogram_t *);
202API_EXPORT(double) hist_approx_sum(const histogram_t *);
204API_EXPORT(double) hist_approx_stddev(const histogram_t *);
208API_EXPORT(double) hist_approx_moment(const histogram_t *hist, double k);
213API_EXPORT(void) hist_clamp(histogram_t *hist, double lower, double upper);
214
218API_EXPORT(uint64_t) hist_approx_count_below(const histogram_t *hist, double threshold);
219
223API_EXPORT(uint64_t) hist_approx_count_below_inclusive(const histogram_t *hist, double threshold);
224
228API_EXPORT(uint64_t) hist_approx_count_below_exclusive(const histogram_t *hist, double threshold);
229
233API_EXPORT(uint64_t) hist_approx_count_above(const histogram_t *hist, double threshold);
234
238API_EXPORT(uint64_t) hist_approx_count_above_inclusive(const histogram_t *hist, double threshold);
239
243API_EXPORT(uint64_t) hist_approx_count_above_exclusive(const histogram_t *hist, double threshold);
244
248API_EXPORT(uint64_t) hist_approx_count_nearby(const histogram_t *hist, double value);
254API_EXPORT(int) hist_approx_quantile(const histogram_t *, const double *q_in, int nq, double *q_out);
260API_EXPORT(int) hist_approx_quantile7(const histogram_t *, const double *q_in, int nq, double *q_out);
265API_EXPORT(int) hist_approx_inverse_quantile(const histogram_t *, const double *iq_in, int niq, double *iq_out);
266
267typedef struct {
268 uint64_t count;
269 double lower;
270 double upper;
272
273typedef enum {
274 HIST_APPROX_MID = 0,
275 HIST_APPROX_HARMONIC_MEAN,
276 HIST_APPROX_HIGH,
277 HIST_APPROX_LOW
278} histogram_approx_mode_t;
279
285API_EXPORT(histogram_t *) hist_create_approximation_from_adhoc(histogram_approx_mode_t mode, const histogram_adhoc_bin_t *bins, size_t nbins, double sum);
286
287#ifdef __cplusplus
288} /* FFI_SKIP */
289#endif
290
291#endif
uint64_t hist_remove_raw(histogram_t *hist, hist_bucket_t hb, uint64_t count)
Remove data from a histogram count times, returns the actual count removed protecting from underflow.
uint64_t hist_sample_count(const histogram_t *hist)
Get the total number of values stored in the histogram.
ssize_t hist_serialize(const histogram_t *h, void *buff, ssize_t len)
Serialize histogram to binary data.
int hist_bucket_idx_bucket(const histogram_t *hist, int idx, hist_bucket_t *b, uint64_t *c)
Get bucket+count for bucket at position idx. Valid positions are 0 .. hist_bucket_count()
uint64_t hist_approx_count_above(const histogram_t *hist, double threshold)
void hist_downsample(histogram_t *tgt, double factor)
Downsample a histogram to a certain factor.
histogram_t * hist_alloc_with_allocator(const hist_allocator_t *alloc)
Create a new histogram, uses custom allocator.
int hist_add_as_int64(histogram_t *tgt, const histogram_t *src)
Add bins in src from tgt treating src counts as signed, return -1 on overflow error.
uint64_t hist_approx_count_below_inclusive(const histogram_t *hist, double threshold)
double hist_approx_sum(const histogram_t *)
Approximate the sum of all values stored in the histogram.
double hist_approx_moment(const histogram_t *hist, double k)
double hist_approx_mean(const histogram_t *)
Approximate mean value of all values stored in the histogram.
histogram_t * hist_compress_mbe(const histogram_t *h, int8_t mbe)
uint64_t hist_remove(histogram_t *hist, double val, uint64_t count)
Remove data from a histogram count times, returns the actual count removed protecting from underflow.
int hist_subtract(histogram_t *tgt, const histogram_t *const *src, int cnt)
Subtract bins from each of cnt histograms in src from tgt, return -1 on underrun error.
double hist_bucket_to_double(hist_bucket_t hb)
Returns the edge of the histogram bucket closer to zero.
uint64_t hist_approx_count_above_inclusive(const histogram_t *hist, double threshold)
int hist_subtract_as_int64(histogram_t *tgt, const histogram_t *src)
Subtract bins in src from tgt treating the result count as signed, return -1 on overflow error.
uint64_t hist_insert_raw_end(histogram_t *hist, hist_bucket_t hb, uint64_t count)
double hist_bucket_to_double_bin_width(hist_bucket_t hb)
Get the width of the hist_bucket.
void hist_free(histogram_t *hist)
Free a (fast-) histogram, frees with allocator chosen during the alloc/clone.
void hist_clamp(histogram_t *hist, double lower, double upper)
uint64_t hist_approx_count_nearby(const histogram_t *hist, double value)
double hist_approx_stddev(const histogram_t *)
Approximate the standard deviation of all values stored in the histogram.
int hist_bucket_idx(const histogram_t *hist, int idx, double *v, uint64_t *c)
Get value+count for bucket at position idx. Valid positions are 0 .. hist_bucket_count()
histogram_t * hist_clone(const histogram_t *other)
Create an exact copy of other, uses default allocator.
int hist_num_buckets(const histogram_t *hist)
Same as hist_bucket_count.
int hist_approx_quantile7(const histogram_t *, const double *q_in, int nq, double *q_out)
histogram_t * hist_fast_alloc_nbins(int nbins)
Create a fast-histogram with preallocated bins, uses default allocator.
hist_bucket_t int_scale_to_hist_bucket(int64_t value, int scale)
Create the bucket that value * 10^(scale) belongs to.
uint64_t hist_insert_raw(histogram_t *hist, hist_bucket_t hb, uint64_t count)
histogram_t * hist_alloc_nbins(int nbins)
Create a new histogram with preallocated bins, uses default allocator.
uint64_t hist_approx_count_below(const histogram_t *hist, double threshold)
int hist_accumulate(histogram_t *tgt, const histogram_t *const *src, int cnt)
Accumulate bins from each of cnt histograms in src onto tgt.
int hist_bucket_to_string(hist_bucket_t hb, char *buf)
histogram_t * hist_alloc_nbins_with_allocator(int nbins, const hist_allocator_t *alloc)
Create a new histogram with preallocated bins, uses custom allocator.
histogram_t * hist_fast_alloc_with_allocator(const hist_allocator_t *alloc)
Create a fast-histogram.
ssize_t hist_serialize_b64(const histogram_t *h, char *b64_serialized_histo_buff, ssize_t buff_len)
Return histogram serialization as base64 encoded string.
int hist_approx_quantile(const histogram_t *, const double *q_in, int nq, double *q_out)
int hist_bucket_count(const histogram_t *hist)
Get the number of used buckets in a histogram.
histogram_t * hist_alloc(void)
Create a new histogram, uses default allocator.
histogram_t * hist_create_approximation_from_adhoc(histogram_approx_mode_t mode, const histogram_adhoc_bin_t *bins, size_t nbins, double sum)
uint64_t hist_approx_count_above_exclusive(const histogram_t *hist, double threshold)
histogram_t * hist_fast_alloc_nbins_with_allocator(int nbins, const hist_allocator_t *alloc)
Create a fast-histogram with preallocated bins, uses custom allocator.
uint64_t hist_insert(histogram_t *hist, double val, uint64_t count)
insert a value into a histogram count times
struct hist_bucket hist_bucket_t
void hist_clear(histogram_t *hist)
Clear data fast. Keeps buckets allocated.
double hist_bucket_midpoint(hist_bucket_t in)
Calculate mid-point of the bucket.
histogram_t * hist_clone_with_allocator(const histogram_t *other, const hist_allocator_t *alloc)
Create an exact copy of other, uses custom allocator.
int hist_approx_inverse_quantile(const histogram_t *, const double *iq_in, int niq, double *iq_out)
histogram_t * hist_fast_alloc(void)
Create a fast-histogram.
uint64_t hist_approx_count_below_exclusive(const histogram_t *hist, double threshold)
hist_bucket_t double_to_hist_bucket(double d)
Create the bucket that a value belongs to.
uint64_t hist_insert_intscale(histogram_t *hist, int64_t val, int scale, uint64_t count)
Insert a value into a histogram value = val * 10^(scale)
Definition: circllhist.h:56
Definition: circllhist.h:51
int8_t val
value * 10
Definition: circllhist.h:52
int8_t exp
exponent -128 .. 127
Definition: circllhist.h:53
Definition: circllhist.h:267