clickhouse_c/
sys.rs

1//! Raw FFI bindings for clickhouse-c.
2//!
3//! Structures and functions mirror public C headers. `build.rs` reads integer
4//! constants from bundled headers and generates corresponding Rust constants.
5
6#![allow(non_camel_case_types)]
7#![allow(non_snake_case)]
8#![allow(non_upper_case_globals)]
9#![allow(dead_code)]
10
11use core::ffi::{c_char, c_int, c_void};
12
13/* C enum types */
14
15pub type chc_kind = c_int;
16pub type chc_col_kind = c_int;
17pub type chc_interval_unit = c_int;
18pub type chc_compression = c_int;
19pub type chc_packet_kind = c_int;
20
21include!(concat!(env!("OUT_DIR"), "/sys_constants.rs"));
22
23/* Errors */
24
25#[repr(C)]
26pub struct chc_err {
27    pub msg: [c_char; CHC_ERR_MSG_LEN],
28}
29
30impl chc_err {
31    pub const fn zeroed() -> Self {
32        Self {
33            msg: [0; CHC_ERR_MSG_LEN],
34        }
35    }
36}
37
38/* Allocator */
39
40#[repr(C)]
41#[derive(Clone, Copy)]
42pub struct chc_alloc {
43    pub ud: *mut c_void,
44    pub alloc: Option<unsafe extern "C" fn(ud: *mut c_void, bytes: usize) -> *mut c_void>,
45    pub realloc: Option<
46        unsafe extern "C" fn(
47            ud: *mut c_void,
48            p: *mut c_void,
49            old_bytes: usize,
50            new_bytes: usize,
51        ) -> *mut c_void,
52    >,
53    pub free: Option<unsafe extern "C" fn(ud: *mut c_void, p: *mut c_void, bytes: usize)>,
54}
55
56unsafe extern "C" {
57    pub fn chc_alloc_stdlib() -> chc_alloc;
58}
59
60/* Local C helpers from src/wrapper.c */
61
62unsafe extern "C" {
63    // Use same monotonic clock as POSIX backend deadlines
64    pub fn chc_rs_monotonic_us() -> i64;
65}
66
67/* I/O */
68
69// Public callback table from clickhouse.h
70#[repr(C)]
71pub struct chc_io {
72    pub ud: *mut c_void,
73    pub read: Option<
74        unsafe extern "C" fn(
75            ud: *mut c_void,
76            buf: *mut c_void,
77            len: usize,
78            out_n: *mut usize,
79            err: *mut chc_err,
80        ) -> c_int,
81    >,
82    pub write: Option<
83        unsafe extern "C" fn(
84            ud: *mut c_void,
85            buf: *const c_void,
86            len: usize,
87            err: *mut chc_err,
88        ) -> c_int,
89    >,
90    pub check_cancel: Option<unsafe extern "C" fn(ud: *mut c_void) -> c_int>,
91}
92
93// Implementation-private buffered reader allocated through C helpers
94#[repr(C)]
95pub struct chc_in {
96    _opaque: [u8; 0],
97}
98
99unsafe extern "C" {
100    // Supports callback-backed and submitted-input modes
101    pub fn chc_in_init(
102        input: *mut chc_in,
103        io: *mut chc_io,
104        al: *const chc_alloc,
105        cap: usize,
106        err: *mut chc_err,
107    ) -> c_int;
108    pub fn chc_in_init_ioless(input: *mut chc_in, al: *const chc_alloc) -> c_int;
109    pub fn chc_in_submit(
110        input: *mut chc_in,
111        buf: *const c_void,
112        len: usize,
113        err: *mut chc_err,
114    ) -> c_int;
115    /// Returns number of unconsumed buffered bytes.
116    pub fn chc_in_available(input: *const chc_in) -> usize;
117    /// Removes consumed bytes and compacts buffer.
118    pub fn chc_in_reset(input: *mut chc_in);
119    pub fn chc_in_free(input: *mut chc_in);
120}
121
122// Public POSIX file descriptor backend state from clickhouse-posix-io.h
123#[repr(C)]
124pub struct chc_posix_io {
125    pub fd: c_int,
126    pub check_cancel: Option<unsafe extern "C" fn(ud: *mut c_void) -> bool>,
127    pub cancel_ud: *mut c_void,
128    // Absolute monotonic deadline in microseconds, zero disables timeout
129    pub deadline_us: i64,
130}
131
132unsafe extern "C" {
133    pub fn chc_posix_io_init(
134        state: *mut chc_posix_io,
135        out_io: *mut chc_io,
136        fd: c_int,
137        check_cancel: Option<unsafe extern "C" fn(ud: *mut c_void) -> bool>,
138        cancel_ud: *mut c_void,
139    );
140    pub fn chc_posix_io_set_deadline(state: *mut chc_posix_io, deadline_us: i64);
141}
142
143/* Type syntax tree */
144
145#[repr(C)]
146pub struct chc_type {
147    _opaque: [u8; 0],
148}
149
150unsafe extern "C" {
151    pub fn chc_type_parse(
152        name: *const c_char,
153        name_len: usize,
154        al: *const chc_alloc,
155        out: *mut *mut chc_type,
156        err: *mut chc_err,
157    ) -> c_int;
158    pub fn chc_type_destroy(t: *mut chc_type, al: *const chc_alloc);
159
160    pub fn chc_type_kind(t: *const chc_type) -> chc_kind;
161    pub fn chc_type_n_children(t: *const chc_type) -> usize;
162    pub fn chc_type_child(t: *const chc_type, i: usize) -> *const chc_type;
163
164    pub fn chc_type_fixed_size(t: *const chc_type) -> c_int;
165    pub fn chc_type_elem_size(t: *const chc_type) -> usize;
166    pub fn chc_type_decimal_precision(t: *const chc_type) -> c_int;
167    pub fn chc_type_decimal_scale(t: *const chc_type) -> c_int;
168    pub fn chc_type_datetime64_scale(t: *const chc_type) -> c_int;
169    pub fn chc_type_interval_unit(t: *const chc_type) -> chc_interval_unit;
170    pub fn chc_type_qbit_dimension(t: *const chc_type) -> usize;
171    pub fn chc_type_qbit_element_size(t: *const chc_type) -> usize;
172    pub fn chc_type_timezone(t: *const chc_type, out_len: *mut usize) -> *const c_char;
173    pub fn chc_type_name(t: *const chc_type, out_len: *mut usize) -> *const c_char;
174
175    pub fn chc_type_enum_count(t: *const chc_type) -> usize;
176    pub fn chc_type_enum_at(
177        t: *const chc_type,
178        i: usize,
179        name: *mut *const c_char,
180        name_len: *mut usize,
181        value: *mut i64,
182    );
183
184    pub fn chc_type_tuple_field_name(
185        t: *const chc_type,
186        i: usize,
187        out_len: *mut usize,
188    ) -> *const c_char;
189    pub fn chc_type_agg_function(t: *const chc_type, out_len: *mut usize) -> *const c_char;
190
191    pub fn chc_type_format(t: *const chc_type, buf: *mut c_char, buf_len: usize) -> usize;
192}
193
194/* Columns */
195
196// Public column layout from clickhouse.h, checked by tests/layout.rs
197#[repr(C)]
198#[derive(Clone, Copy)]
199pub struct chc_column_fixed {
200    pub data: *mut c_void,
201    pub elem_size: usize,
202}
203#[repr(C)]
204#[derive(Clone, Copy)]
205pub struct chc_column_str {
206    pub data: *mut u8,
207    pub offsets: *mut u64,
208    pub bytes: usize,
209}
210#[repr(C)]
211#[derive(Clone, Copy)]
212pub struct chc_column_nullable {
213    pub null_map: *mut u8,
214    pub inner: *mut chc_column,
215}
216#[repr(C)]
217#[derive(Clone, Copy)]
218pub struct chc_column_array {
219    pub offsets: *mut u64,
220    pub values: *mut chc_column,
221}
222#[repr(C)]
223#[derive(Clone, Copy)]
224pub struct chc_column_tuple {
225    pub children: *mut *mut chc_column,
226    pub arity: usize,
227}
228#[repr(C)]
229#[derive(Clone, Copy)]
230pub struct chc_column_lc {
231    pub key_size: c_int,
232    pub keys: *mut c_void,
233    pub dict: *mut chc_column,
234    pub dict_n: usize,
235}
236
237// `layout` selects active member of anonymous C union
238#[repr(C)]
239pub union chc_column_payload {
240    pub fixed: chc_column_fixed,
241    pub str_: chc_column_str,
242    pub nullable: chc_column_nullable,
243    pub array: chc_column_array,
244    pub tuple: chc_column_tuple,
245    pub lc: chc_column_lc,
246}
247
248#[repr(C)]
249pub struct chc_column {
250    pub layout: chc_col_kind,
251    pub n_rows: usize,
252    pub payload: chc_column_payload,
253}
254
255unsafe extern "C" {
256    // Builders borrow input data and child nodes without allocating
257    pub fn chc_build_fixed(data: *const c_void, elem_size: usize, n_rows: usize) -> chc_column;
258    pub fn chc_build_string(offsets: *const u64, data: *const u8, n_rows: usize) -> chc_column;
259    pub fn chc_build_nullable(null_map: *const u8, inner: *mut chc_column) -> chc_column;
260    pub fn chc_build_array(
261        offsets: *const u64,
262        n_rows: usize,
263        values: *mut chc_column,
264    ) -> chc_column;
265    pub fn chc_build_tuple(children: *mut *mut chc_column, arity: usize) -> chc_column;
266    pub fn chc_build_lc(
267        key_size: c_int,
268        keys: *const c_void,
269        n_rows: usize,
270        dict: *mut chc_column,
271    ) -> chc_column;
272}
273
274unsafe extern "C" {
275    pub fn chc_column_layout(c: *const chc_column) -> chc_col_kind;
276    pub fn chc_column_n_rows(c: *const chc_column) -> usize;
277    pub fn chc_column_fixed_data(c: *const chc_column, elem_size: *mut usize) -> *const c_void;
278    pub fn chc_column_string_data(c: *const chc_column) -> *const u8;
279    pub fn chc_column_string_offsets(c: *const chc_column) -> *const u64;
280    pub fn chc_column_null_map(c: *const chc_column) -> *const u8;
281    pub fn chc_column_nullable_inner(c: *const chc_column) -> *const chc_column;
282    pub fn chc_column_array_offsets(c: *const chc_column) -> *const u64;
283    pub fn chc_column_array_values(c: *const chc_column) -> *const chc_column;
284    pub fn chc_column_tuple_arity(c: *const chc_column) -> usize;
285    pub fn chc_column_tuple_child(c: *const chc_column, i: usize) -> *const chc_column;
286    pub fn chc_column_lc_key_size(c: *const chc_column) -> c_int;
287    pub fn chc_column_lc_keys(c: *const chc_column) -> *const c_void;
288    pub fn chc_column_lc_dict(c: *const chc_column) -> *const chc_column;
289    pub fn chc_column_validate(c: *const chc_column, err: *mut chc_err) -> c_int;
290}
291
292/* Block reader */
293
294#[repr(C)]
295pub struct chc_block {
296    _opaque: [u8; 0],
297}
298
299#[repr(C)]
300#[derive(Clone, Copy)]
301pub struct chc_block_opts {
302    pub has_block_info: bool,
303    pub has_custom_serialization: bool,
304    pub read_buffer_bytes: usize,
305}
306
307impl chc_block_opts {
308    pub const fn zeroed() -> Self {
309        Self {
310            has_block_info: false,
311            has_custom_serialization: false,
312            read_buffer_bytes: 0,
313        }
314    }
315}
316
317unsafe extern "C" {
318    // C helpers allocate implementation-private buffered reader
319    pub fn chc_rs_in_new(
320        io: *mut chc_io,
321        al: *const chc_alloc,
322        cap: usize,
323        out: *mut *mut chc_in,
324        err: *mut chc_err,
325    ) -> c_int;
326    pub fn chc_rs_in_new_ioless(
327        al: *const chc_alloc,
328        out: *mut *mut chc_in,
329        err: *mut chc_err,
330    ) -> c_int;
331    pub fn chc_rs_in_destroy(input: *mut chc_in, al: *const chc_alloc);
332
333    pub fn chc_block_read(
334        input: *mut chc_in,
335        al: *const chc_alloc,
336        opts: *const chc_block_opts,
337        out: *mut *mut chc_block,
338        err: *mut chc_err,
339    ) -> c_int;
340    pub fn chc_block_destroy(b: *mut chc_block, al: *const chc_alloc);
341
342    pub fn chc_block_n_rows(b: *const chc_block) -> usize;
343    pub fn chc_block_n_columns(b: *const chc_block) -> usize;
344    pub fn chc_block_column_name(
345        b: *const chc_block,
346        i: usize,
347        out_len: *mut usize,
348    ) -> *const c_char;
349    pub fn chc_block_column_type(b: *const chc_block, i: usize) -> *const chc_type;
350    pub fn chc_block_column(b: *const chc_block, i: usize) -> *const chc_column;
351
352    pub fn chc_block_is_overflows(b: *const chc_block) -> bool;
353    pub fn chc_block_bucket_num(b: *const chc_block) -> i32;
354}
355
356/* Block builder */
357
358// Block column borrows name, type, and column tree until write completes
359#[repr(C)]
360#[derive(Clone, Copy)]
361pub struct chc_block_col {
362    pub name: *const c_char,
363    pub name_len: usize,
364    pub type_: *const chc_type,
365    pub col: *const chc_column,
366}
367
368impl chc_block_col {
369    pub const fn zeroed() -> Self {
370        Self {
371            name: core::ptr::null(),
372            name_len: 0,
373            type_: core::ptr::null(),
374            col: core::ptr::null(),
375        }
376    }
377}
378
379// Builder references caller-provided column storage
380#[repr(C)]
381#[derive(Clone, Copy)]
382pub struct chc_block_builder {
383    pub cols: *mut chc_block_col,
384    pub n_cols: usize,
385    pub n_rows: usize,
386}
387
388impl chc_block_builder {
389    pub const fn zeroed() -> Self {
390        Self {
391            cols: core::ptr::null_mut(),
392            n_cols: 0,
393            n_rows: 0,
394        }
395    }
396}
397
398unsafe extern "C" {
399    pub fn chc_block_builder_init(bb: *mut chc_block_builder, cols: *mut chc_block_col);
400    pub fn chc_block_builder_append(
401        bb: *mut chc_block_builder,
402        name: *const c_char,
403        name_len: usize,
404        t: *const chc_type,
405        col: *const chc_column,
406    );
407
408    pub fn chc_block_write_cols(
409        io: *mut chc_io,
410        cols: *const chc_block_col,
411        n_cols: usize,
412        n_rows: usize,
413        opts: *const chc_block_opts,
414        err: *mut chc_err,
415    ) -> c_int;
416
417    pub fn chc_block_write(
418        io: *mut chc_io,
419        bb: *const chc_block_builder,
420        opts: *const chc_block_opts,
421        err: *mut chc_err,
422    ) -> c_int;
423}
424
425/* Compression */
426
427#[repr(C)]
428pub struct chc_codec {
429    pub ud: *mut c_void,
430    pub lz4_compress: Option<
431        unsafe extern "C" fn(
432            ud: *mut c_void,
433            src: *const c_void,
434            src_len: usize,
435            dst: *mut c_void,
436            dst_cap: usize,
437            dst_n: *mut usize,
438            err: *mut chc_err,
439        ) -> c_int,
440    >,
441    pub lz4_decompress: Option<
442        unsafe extern "C" fn(
443            ud: *mut c_void,
444            src: *const c_void,
445            src_len: usize,
446            dst: *mut c_void,
447            original_size: usize,
448            err: *mut chc_err,
449        ) -> c_int,
450    >,
451    pub zstd_compress: Option<
452        unsafe extern "C" fn(
453            ud: *mut c_void,
454            src: *const c_void,
455            src_len: usize,
456            dst: *mut c_void,
457            dst_cap: usize,
458            dst_n: *mut usize,
459            err: *mut chc_err,
460        ) -> c_int,
461    >,
462    pub zstd_decompress: Option<
463        unsafe extern "C" fn(
464            ud: *mut c_void,
465            src: *const c_void,
466            src_len: usize,
467            dst: *mut c_void,
468            original_size: usize,
469            err: *mut chc_err,
470        ) -> c_int,
471    >,
472    pub lz4_bound: Option<unsafe extern "C" fn(src_len: usize) -> usize>,
473    pub zstd_bound: Option<unsafe extern "C" fn(src_len: usize) -> usize>,
474}
475
476unsafe extern "C" {
477    pub fn chc_cityhash128(data: *const c_void, len: usize, out_lo: *mut u64, out_hi: *mut u64);
478}
479
480#[cfg(feature = "lz4")]
481unsafe extern "C" {
482    pub fn chc_lz4_codec_init(out: *mut chc_codec);
483}
484
485#[cfg(feature = "zstd")]
486unsafe extern "C" {
487    pub fn chc_zstd_codec_init(out: *mut chc_codec);
488}
489
490/* Native protocol client */
491
492#[repr(C)]
493pub struct chc_client_opts {
494    pub client_name: *const c_char,
495    pub client_version_major: u64,
496    pub client_version_minor: u64,
497    pub client_version_patch: u64,
498    pub database: *const c_char,
499    pub user: *const c_char,
500    pub password: *const c_char,
501    pub compression: chc_compression,
502    pub codec: *const chc_codec,
503    pub read_buffer_bytes: usize,
504}
505
506impl chc_client_opts {
507    pub const fn zeroed() -> Self {
508        Self {
509            client_name: core::ptr::null(),
510            client_version_major: 0,
511            client_version_minor: 0,
512            client_version_patch: 0,
513            database: core::ptr::null(),
514            user: core::ptr::null(),
515            password: core::ptr::null(),
516            compression: CHC_COMP_NONE,
517            codec: core::ptr::null(),
518            read_buffer_bytes: 0,
519        }
520    }
521}
522
523#[repr(C)]
524pub struct chc_server_info {
525    pub name: [c_char; 64],
526    pub timezone: [c_char; 64],
527    pub display_name: [c_char; 128],
528    pub version_major: u64,
529    pub version_minor: u64,
530    pub version_patch: u64,
531    pub revision: u64,
532}
533
534#[repr(C)]
535pub struct chc_client {
536    _opaque: [u8; 0],
537}
538
539#[repr(C)]
540pub struct chc_exception {
541    pub code: i32,
542    pub name: *mut c_char,
543    pub name_len: usize,
544    pub display_text: *mut c_char,
545    pub display_text_len: usize,
546    pub stack_trace: *mut c_char,
547    pub stack_trace_len: usize,
548}
549
550#[repr(C)]
551#[derive(Clone, Copy)]
552pub struct chc_packet_progress {
553    pub rows: u64,
554    pub bytes: u64,
555    pub total_rows: u64,
556    pub total_bytes: u64,
557    pub written_rows: u64,
558    pub written_bytes: u64,
559    pub elapsed_ns: u64,
560}
561
562#[repr(C)]
563#[derive(Clone, Copy)]
564pub struct chc_packet_profile {
565    pub rows: u64,
566    pub blocks: u64,
567    pub bytes: u64,
568    pub rows_before_limit: u64,
569    pub applied_limit: u8,
570    pub calculated_rows_before_limit: u8,
571}
572
573// `kind` selects active member of C payload union
574#[repr(C)]
575pub union chc_packet_payload {
576    pub block: *mut chc_block,
577    pub exception: *mut chc_exception,
578    pub progress: chc_packet_progress,
579    pub profile: chc_packet_profile,
580}
581
582#[repr(C)]
583pub struct chc_packet {
584    pub kind: chc_packet_kind,
585    pub payload: chc_packet_payload,
586}
587
588impl chc_packet {
589    pub const fn zeroed() -> Self {
590        Self {
591            kind: 0,
592            payload: chc_packet_payload {
593                block: core::ptr::null_mut(),
594            },
595        }
596    }
597}
598
599#[repr(C)]
600pub struct chc_query_setting {
601    pub name: *const c_char,
602    pub value: *const c_char,
603    pub important: bool,
604    pub custom: bool,
605}
606
607#[repr(C)]
608pub struct chc_query_param {
609    pub name: *const c_char,
610    pub value: *const c_char,
611}
612
613#[repr(C)]
614pub struct chc_query_opts {
615    pub query_id: *const c_char,
616    pub query_id_len: usize,
617    pub settings: *const chc_query_setting,
618    pub n_settings: usize,
619    pub params: *const chc_query_param,
620    pub n_params: usize,
621}
622
623unsafe extern "C" {
624    // Handshake rejection transfers exception ownership through `exc`
625    pub fn chc_client_init(
626        out: *mut *mut chc_client,
627        opts: *const chc_client_opts,
628        al: *const chc_alloc,
629        io: *mut chc_io,
630        exc: *mut *mut chc_exception,
631        err: *mut chc_err,
632    ) -> c_int;
633    pub fn chc_client_close(c: *mut chc_client);
634    pub fn chc_client_server_info(c: *const chc_client) -> *const chc_server_info;
635    pub fn chc_client_send_query(
636        c: *mut chc_client,
637        sql: *const c_char,
638        sql_len: usize,
639        query_id: *const c_char,
640        query_id_len: usize,
641        err: *mut chc_err,
642    ) -> c_int;
643    pub fn chc_client_send_query_ex(
644        c: *mut chc_client,
645        sql: *const c_char,
646        sql_len: usize,
647        opts: *const chc_query_opts,
648        err: *mut chc_err,
649    ) -> c_int;
650    pub fn chc_client_recv_packet(
651        c: *mut chc_client,
652        out: *mut chc_packet,
653        err: *mut chc_err,
654    ) -> c_int;
655    pub fn chc_packet_clear(c: *mut chc_client, p: *mut chc_packet);
656    pub fn chc_client_send_data(
657        c: *mut chc_client,
658        bb: *const chc_block_builder,
659        err: *mut chc_err,
660    ) -> c_int;
661    pub fn chc_client_send_cancel(c: *mut chc_client, err: *mut chc_err) -> c_int;
662    pub fn chc_client_send_ping(c: *mut chc_client, err: *mut chc_err) -> c_int;
663    pub fn chc_exception_free(e: *mut chc_exception, al: *const chc_alloc);
664}
665
666/* I/O-independent client */
667
668#[repr(C)]
669pub struct chc_async_client {
670    _opaque: [u8; 0],
671}
672
673unsafe extern "C" {
674    pub fn chc_async_client_init(
675        out: *mut *mut chc_async_client,
676        opts: *const chc_client_opts,
677        al: *const chc_alloc,
678        err: *mut chc_err,
679    ) -> c_int;
680    pub fn chc_async_client_free(c: *mut chc_async_client);
681
682    pub fn chc_async_submit(
683        c: *mut chc_async_client,
684        buf: *const c_void,
685        len: usize,
686        err: *mut chc_err,
687    ) -> c_int;
688    pub fn chc_async_pending_out(c: *mut chc_async_client, buf: *mut *const u8, len: *mut usize);
689    pub fn chc_async_consume_out(c: *mut chc_async_client, n: usize);
690
691    // Handshake rejection transfers exception ownership through `exc`
692    pub fn chc_async_handshake(
693        c: *mut chc_async_client,
694        exc: *mut *mut chc_exception,
695        err: *mut chc_err,
696    ) -> c_int;
697    pub fn chc_async_send_query(
698        c: *mut chc_async_client,
699        sql: *const c_char,
700        sql_len: usize,
701        query_id: *const c_char,
702        query_id_len: usize,
703        err: *mut chc_err,
704    ) -> c_int;
705    pub fn chc_async_send_data(
706        c: *mut chc_async_client,
707        bb: *const chc_block_builder,
708        err: *mut chc_err,
709    ) -> c_int;
710    pub fn chc_async_send_data_end(c: *mut chc_async_client, err: *mut chc_err) -> c_int;
711    pub fn chc_async_recv_packet(
712        c: *mut chc_async_client,
713        out: *mut chc_packet,
714        err: *mut chc_err,
715    ) -> c_int;
716    pub fn chc_async_server_info(c: *const chc_async_client) -> *const chc_server_info;
717    pub fn chc_async_packet_clear(c: *mut chc_async_client, p: *mut chc_packet);
718}
clickhouse_c/sys.rs

clickhouse_c/
sys.rs
