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>
28 typedef SSIZE_T ssize_t;
29 #endif
30 
31 #ifdef __cplusplus
32 extern "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 
43 typedef struct histogram histogram_t;
44 typedef struct hist_rollup_config hist_rollup_config_t;
51 typedef struct hist_bucket {
52  int8_t val;
53  int8_t exp;
55 
56 typedef struct hist_allocator {
57  void *(*malloc)(size_t);
58  void *(*calloc)(size_t, size_t);
59  void (*free)(void *);
61 
63 // Histogram buckets
64 
66 API_EXPORT(double) hist_bucket_to_double(hist_bucket_t hb);
68 API_EXPORT(double) hist_bucket_midpoint(hist_bucket_t in);
72 API_EXPORT(hist_bucket_t) double_to_hist_bucket(double d);
74 API_EXPORT(hist_bucket_t) int_scale_to_hist_bucket(int64_t value, int scale);
92 API_EXPORT(int) hist_bucket_to_string(hist_bucket_t hb, char *buf);
93 
95 // Creating and destroying histograms
96 
98 API_EXPORT(histogram_t *) hist_alloc(void);
100 API_EXPORT(histogram_t *) hist_alloc_nbins(int nbins);
102 
105 API_EXPORT(histogram_t *) hist_fast_alloc(void);
107 API_EXPORT(histogram_t *) hist_fast_alloc_nbins(int nbins);
109 API_EXPORT(histogram_t *) hist_clone(const histogram_t *other);
110 
112 API_EXPORT(histogram_t *) hist_alloc_with_allocator(const hist_allocator_t *alloc);
114 API_EXPORT(histogram_t *) hist_alloc_nbins_with_allocator(int nbins, const hist_allocator_t *alloc);
116 
119 API_EXPORT(histogram_t *) hist_fast_alloc_with_allocator(const hist_allocator_t *alloc);
121 API_EXPORT(histogram_t *) hist_fast_alloc_nbins_with_allocator(int nbins, const hist_allocator_t *alloc);
123 API_EXPORT(histogram_t *) hist_clone_with_allocator(const histogram_t *other, const hist_allocator_t *alloc);
124 
126 API_EXPORT(void) hist_free(histogram_t *hist);
127 
129 // Getting data in and out of histograms
130 
136 API_EXPORT(uint64_t) hist_insert(histogram_t *hist, double val, uint64_t count);
138 API_EXPORT(uint64_t) hist_remove(histogram_t *hist, double val, uint64_t count);
140 API_EXPORT(uint64_t) hist_remove_raw(histogram_t *hist, hist_bucket_t hb, uint64_t count);
145 API_EXPORT(uint64_t) hist_insert_raw(histogram_t *hist, hist_bucket_t hb, uint64_t count);
148 API_EXPORT(uint64_t) hist_insert_raw_end(histogram_t *hist, hist_bucket_t hb, uint64_t count);
150 API_EXPORT(int) hist_bucket_count(const histogram_t *hist);
152 API_EXPORT(int) hist_num_buckets(const histogram_t *hist);
154 API_EXPORT(uint64_t) hist_sample_count(const histogram_t *hist);
156 API_EXPORT(int) hist_bucket_idx(const histogram_t *hist, int idx, double *v, uint64_t *c);
158 API_EXPORT(int) hist_bucket_idx_bucket(const histogram_t *hist, int idx, hist_bucket_t *b, uint64_t *c);
160 API_EXPORT(int) hist_accumulate(histogram_t *tgt, const histogram_t * const *src, int cnt);
162 API_EXPORT(int) hist_subtract(histogram_t *tgt, const histogram_t * const *src, int cnt);
164 API_EXPORT(int) hist_subtract_as_int64(histogram_t *tgt, const histogram_t *src);
166 API_EXPORT(int) hist_add_as_int64(histogram_t *tgt, const histogram_t *src);
168 API_EXPORT(void) hist_clear(histogram_t *hist);
170 API_EXPORT(uint64_t) hist_insert_intscale(histogram_t *hist, int64_t val, int scale, uint64_t count);
171 
173 // Serialization
174 
176 API_EXPORT(ssize_t) hist_serialize(const histogram_t *h, void *buff, ssize_t len);
177 API_EXPORT(ssize_t) hist_deserialize(histogram_t *h, const void *buff, ssize_t len);
178 API_EXPORT(ssize_t) hist_serialize_estimate(const histogram_t *h);
180 API_EXPORT(ssize_t) hist_serialize_b64(const histogram_t *h, char *b64_serialized_histo_buff, ssize_t buff_len);
181 API_EXPORT(ssize_t) hist_deserialize_b64(histogram_t *h, const void *b64_string, ssize_t b64_string_len);
182 API_EXPORT(ssize_t) hist_serialize_b64_estimate(const histogram_t *h);
183 
184 API_EXPORT(void) hist_remove_zeroes(histogram_t *h);
192 API_EXPORT(histogram_t *) hist_compress_mbe(const histogram_t *h, int8_t mbe);
193 
195 // Analytics
196 
198 API_EXPORT(double) hist_approx_mean(const histogram_t *);
200 API_EXPORT(double) hist_approx_sum(const histogram_t *);
202 API_EXPORT(double) hist_approx_stddev(const histogram_t *);
206 API_EXPORT(double) hist_approx_moment(const histogram_t *hist, double k);
211 API_EXPORT(void) hist_clamp(histogram_t *hist, double lower, double upper);
215 API_EXPORT(uint64_t) hist_approx_count_below(const histogram_t *hist, double threshold);
219 API_EXPORT(uint64_t) hist_approx_count_above(const histogram_t *hist, double threshold);
223 API_EXPORT(uint64_t) hist_approx_count_nearby(const histogram_t *hist, double value);
228 API_EXPORT(int) hist_approx_quantile(const histogram_t *, const double *q_in, int nq, double *q_out);
233 API_EXPORT(int) hist_approx_inverse_quantile(const histogram_t *, const double *iq_in, int niq, double *iq_out);
234 
235 #ifdef __cplusplus
236 } /* FFI_SKIP */
237 #endif
238 
239 #endif
histogram_t * hist_fast_alloc(void)
Create a fast-histogram.
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)
histogram_t * hist_alloc_nbins(int nbins)
Create a new histogram with preallocated bins, uses default 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.
histogram_t * hist_alloc_nbins_with_allocator(int nbins, const hist_allocator_t *alloc)
Create a new histogram with preallocated bins, uses custom allocator.
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.
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.
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_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.
histogram_t * hist_fast_alloc_nbins(int nbins)
Create a fast-histogram with preallocated bins, uses default allocator.
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)
histogram_t * hist_fast_alloc_with_allocator(const hist_allocator_t *alloc)
Create a fast-histogram.
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.
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.
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_alloc(void)
Create a new histogram, uses default allocator.
int hist_num_buckets(const histogram_t *hist)
Same as hist_bucket_count.
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_with_allocator(const hist_allocator_t *alloc)
Create a new histogram, uses custom 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)
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_clone(const histogram_t *other)
Create an exact copy of other, uses default 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.
int hist_approx_inverse_quantile(const histogram_t *, const double *iq_in, int niq, double *iq_out)
histogram_t * hist_compress_mbe(const histogram_t *h, int8_t mbe)
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