add c-major array layout c api.

kafka1991 · kafka1991 · commit 4057bbe1a707 · 2025-06-04T13:14:45.000+08:00
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -107,6 +107,10 @@ if (QUESTDB_TESTS_AND_EXAMPLES)
         line_sender_c_example_array_elem_strides
         examples/concat.c
         examples/line_sender_c_example_array_elem_strides.c)
+    compile_example(
+        line_sender_c_example_array_c_major
+        examples/concat.c
+        examples/line_sender_c_example_array_c_major.c)
     compile_example(
         line_sender_c_example_auth
         examples/concat.c
@@ -141,6 +145,9 @@ if (QUESTDB_TESTS_AND_EXAMPLES)
     compile_example(
         line_sender_cpp_example_auth
         examples/line_sender_cpp_example_auth.cpp)
+    compile_example(
+        line_sender_cpp_example_array_c_major
+        examples/line_sender_cpp_example_array_c_major.cpp)
     compile_example(
         line_sender_cpp_example_tls_ca
         examples/line_sender_cpp_example_tls_ca.cpp)
diff --git a/cpp_test/test_line_sender.cpp b/cpp_test/test_line_sender.cpp
@@ -199,15 +199,26 @@ TEST_CASE("line_sender c api basics")
         reinterpret_cast<uint8_t*>(arr_data.data()),
         sizeof(arr_data),
         &err));
+    line_sender_column_name arr_name3 = QDB_COLUMN_NAME_LITERAL("a3");
+    CHECK(
+        ::line_sender_buffer_column_f64_arr_c_major(
+            buffer,
+            arr_name3,
+            rank,
+            shape,
+            reinterpret_cast<uint8_t*>(arr_data.data()),
+            sizeof(arr_data),
+            &err));
     CHECK(::line_sender_buffer_at_nanos(buffer, 10000000, &err));
     CHECK(server.recv() == 0);
-    CHECK(::line_sender_buffer_size(buffer) == 266);
+    CHECK(::line_sender_buffer_size(buffer) == 382);
     CHECK(::line_sender_flush(sender, buffer, &err));
     ::line_sender_buffer_free(buffer);
     CHECK(server.recv() == 1);
     std::string expect{"test,t1=v1 f1=="};
     push_double_to_buffer(expect, 0.5).append(",a1==");
     push_double_arr_to_buffer(expect, arr_data, 3, shape).append(",a2==");
+    push_double_arr_to_buffer(expect, arr_data, 3, shape).append(",a3==");
     push_double_arr_to_buffer(expect, arr_data, 3, shape).append(" 10000000\n");
     CHECK(server.msgs(0) == expect);
 }
@@ -282,18 +293,24 @@ TEST_CASE("line_sender c++ api basics")
         .symbol("t1", "v1")
         .symbol("t2", "")
         .column("f1", 0.5)
-        .column<true>("a1", rank, shape, strides, arr_data)
-        .column<false>("a2", rank, shape, elem_strides, arr_data)
+        .column<questdb::ingress::array_strides_mode::bytes>(
+            "a1", rank, shape, strides, arr_data)
+        .column<questdb::ingress::array_strides_mode::elems>(
+            "a2", rank, shape, elem_strides, arr_data)
+        .column<questdb::ingress::array_strides_mode::c_major>(
+            "a3", rank, shape, {}, arr_data)
         .at(questdb::ingress::timestamp_nanos{10000000});
 
     CHECK(server.recv() == 0);
-    CHECK(buffer.size() == 270);
+    CHECK(buffer.size() == 386);
     sender.flush(buffer);
     CHECK(server.recv() == 1);
     std::string expect{"test,t1=v1,t2= f1=="};
     push_double_to_buffer(expect, 0.5).append(",a1==");
     push_double_arr_to_buffer(expect, arr_data, 3, shape.data())
         .append(",a2==");
+    push_double_arr_to_buffer(expect, arr_data, 3, shape.data())
+        .append(",a3==");
     push_double_arr_to_buffer(expect, arr_data, 3, shape.data())
         .append(" 10000000\n");
     CHECK(server.msgs(0) == expect);
diff --git a/examples/line_sender_c_example_array_c_major.c b/examples/line_sender_c_example_array_c_major.c
@@ -0,0 +1,96 @@
+#include <questdb/ingress/line_sender.h>
+#include <stdio.h>
+#include <stdbool.h>
+#include <string.h>
+#include "concat.h"
+
+static bool example(const char* host, const char* port)
+{
+    line_sender_error* err = NULL;
+    line_sender* sender = NULL;
+    line_sender_buffer* buffer = NULL;
+    char* conf_str = concat("tcp::addr=", host, ":", port, ";protocol_version=2;");
+    if (!conf_str)
+    {
+        fprintf(stderr, "Could not concatenate configuration string.\n");
+        return false;
+    }
+
+    line_sender_utf8 conf_str_utf8 = {0, NULL};
+    if (!line_sender_utf8_init(
+            &conf_str_utf8, strlen(conf_str), conf_str, &err))
+        goto on_error;
+
+    sender = line_sender_from_conf(conf_str_utf8, &err);
+    if (!sender)
+        goto on_error;
+
+    free(conf_str);
+    conf_str = NULL;
+
+    buffer = line_sender_buffer_new_for_sender(sender);
+    line_sender_buffer_reserve(buffer, 64 * 1024);
+
+    line_sender_table_name table_name = QDB_TABLE_NAME_LITERAL("market_orders_c_major");
+    line_sender_column_name symbol_col = QDB_COLUMN_NAME_LITERAL("symbol");
+    line_sender_column_name book_col = QDB_COLUMN_NAME_LITERAL("order_book");
+
+    if (!line_sender_buffer_table(buffer, table_name, &err))
+        goto on_error;
+
+    line_sender_utf8 symbol_val = QDB_UTF8_LITERAL("BTC-USD");
+    if (!line_sender_buffer_symbol(buffer, symbol_col, symbol_val, &err))
+        goto on_error;
+
+    size_t array_rank = 3;
+    uintptr_t array_shape[] = {2, 3, 2};
+    double array_data[] = {
+        48123.5,
+        2.4,
+        48124.0,
+        1.8,
+        48124.5,
+        0.9,
+        48122.5,
+        3.1,
+        48122.0,
+        2.7,
+        48121.5,
+        4.3};
+
+    if (!line_sender_buffer_column_f64_arr_c_major(
+            buffer,
+            book_col,
+            array_rank,
+            array_shape,
+            (const uint8_t*)array_data,
+            sizeof(array_data),
+            &err))
+        goto on_error;
+
+    if (!line_sender_buffer_at_nanos(buffer, line_sender_now_nanos(), &err))
+        goto on_error;
+
+    if (!line_sender_flush(sender, buffer, &err))
+        goto on_error;
+
+    line_sender_close(sender);
+    return true;
+
+on_error:;
+    size_t err_len = 0;
+    const char* err_msg = line_sender_error_msg(err, &err_len);
+    fprintf(stderr, "Error: %.*s\n", (int)err_len, err_msg);
+    free(conf_str);
+    line_sender_error_free(err);
+    line_sender_buffer_free(buffer);
+    line_sender_close(sender);
+    return false;
+}
+
+int main(int argc, const char* argv[])
+{
+    const char* host = (argc >= 2) ? argv[1] : "localhost";
+    const char* port = (argc >= 3) ? argv[2] : "9009";
+    return !example(host, port);
+}
diff --git a/examples/line_sender_cpp_example_array_byte_strides.cpp b/examples/line_sender_cpp_example_array_byte_strides.cpp
@@ -36,7 +36,8 @@ static bool array_example(std::string_view host, std::string_view port)
         questdb::ingress::line_sender_buffer buffer = sender.new_buffer();
         buffer.table(table_name)
             .symbol(symbol_col, "BTC-USD"_utf8)
-            .column<true>(book_col, 3, shape, strides, arr_data)
+            .column<questdb::ingress::array_strides_mode::bytes>(
+                book_col, 3, shape, strides, arr_data)
             .at(questdb::ingress::timestamp_nanos::now());
         sender.flush(buffer);
         return true;
diff --git a/examples/line_sender_cpp_example_array_c_major.cpp b/examples/line_sender_cpp_example_array_c_major.cpp
@@ -0,0 +1,62 @@
+#include <questdb/ingress/line_sender.hpp>
+#include <iostream>
+#include <vector>
+
+using namespace std::literals::string_view_literals;
+using namespace questdb::ingress::literals;
+
+static bool array_example(std::string_view host, std::string_view port)
+{
+    try
+    {
+        auto sender = questdb::ingress::line_sender::from_conf(
+            "tcp::addr=" + std::string{host} + ":" + std::string{port} +
+            ";protocol_version=2;");
+
+        const auto table_name = "cpp_market_orders_c_major"_tn;
+        const auto symbol_col = "symbol"_cn;
+        const auto book_col = "order_book"_cn;
+        size_t rank = 3;
+        std::vector<uintptr_t> shape{2, 3, 2};
+        std::array<double, 12> arr_data = {
+            48123.5,
+            2.4,
+            48124.0,
+            1.8,
+            48124.5,
+            0.9,
+            48122.5,
+            3.1,
+            48122.0,
+            2.7,
+            48121.5,
+            4.3};
+
+        questdb::ingress::line_sender_buffer buffer = sender.new_buffer();
+        buffer.table(table_name)
+            .symbol(symbol_col, "BTC-USD"_utf8)
+            .column<questdb::ingress::array_strides_mode::c_major>(
+                book_col, 3, shape, {}, arr_data)
+            .at(questdb::ingress::timestamp_nanos::now());
+        sender.flush(buffer);
+        return true;
+    }
+    catch (const questdb::ingress::line_sender_error& err)
+    {
+        std::cerr << "[ERROR] " << err.what() << std::endl;
+        return false;
+    }
+}
+
+int main(int argc, const char* argv[])
+{
+    auto host = "localhost"sv;
+    if (argc >= 2)
+        host = std::string_view{argv[1]};
+
+    auto port = "9009"sv;
+    if (argc >= 3)
+        port = std::string_view{argv[2]};
+
+    return !array_example(host, port);
+}
diff --git a/examples/line_sender_cpp_example_array_elem_strides.cpp b/examples/line_sender_cpp_example_array_elem_strides.cpp
@@ -36,7 +36,8 @@ static bool array_example(std::string_view host, std::string_view port)
         questdb::ingress::line_sender_buffer buffer = sender.new_buffer();
         buffer.table(table_name)
             .symbol(symbol_col, "BTC-USD"_utf8)
-            .column<false>(book_col, 3, shape, strides, arr_data)
+            .column<questdb::ingress::array_strides_mode::elems>(
+                book_col, 3, shape, strides, arr_data)
             .at(questdb::ingress::timestamp_nanos::now());
         sender.flush(buffer);
         return true;
diff --git a/include/questdb/ingress/line_sender.h b/include/questdb/ingress/line_sender.h
@@ -491,6 +491,30 @@ bool line_sender_buffer_column_str(
     line_sender_utf8 value,
     line_sender_error** err_out);
 
+/**
+ * Records a multidimensional array of 64-bit floating-point values in C-major
+ * order.
+ *
+ * @param[in] buffer Line buffer object.
+ * @param[in] name Column name.
+ * @param[in] rank Number of dimensions of the array.
+ * @param[in] shape Array of dimension sizes (length = `rank`).
+ *                   Each element must be a positive integer.
+ * @param[in] data_buffer First array element data.
+ * @param[in] data_buffer_len Bytes length of the array data.
+ * @param[out] err_out Set to an error object on failure (if non-NULL).
+ * @return true on success, false on error.
+ */
+LINESENDER_API
+bool line_sender_buffer_column_f64_arr_c_major(
+    line_sender_buffer* buffer,
+    line_sender_column_name name,
+    size_t rank,
+    const uintptr_t* shape,
+    const uint8_t* data_buffer,
+    size_t data_buffer_len,
+    line_sender_error** err_out);
+
 /**
  * Record a multidimensional array of double for the given column.
  *
diff --git a/include/questdb/ingress/line_sender.hpp b/include/questdb/ingress/line_sender.hpp
@@ -109,6 +109,18 @@ enum class protocol_version
     v2 = 2,
 };
 
+enum class array_strides_mode
+{
+    /** Strides are inferred from C-style row-major memory layout. */
+    c_major,
+
+    /** Strides are provided in bytes */
+    bytes,
+
+    /** Strides are provided in elements */
+    elems,
+};
+
 /* Possible sources of the root certificates used to validate the server's TLS
  * certificate. */
 enum class ca
@@ -641,11 +653,9 @@ class line_sender_buffer
     }
 
     /**
-     * Record a multidimensional double-precision array for the given column.
+     * Records a multidimensional array of double-precision values.
      *
-     * @tparam B    Strides mode selector:
-     *              - `true` for byte-level strides
-     *              - `false` for element-level strides
+     * @tparam Layout    Memory layout specification (array_strides_mode)
      * @tparam T    Element type (current only `double` is supported).
      * @tparam N    Number of elements in the flat data array
      *
@@ -654,7 +664,7 @@ class line_sender_buffer
      * @param data    Array first element data. Size must match product of
      * dimensions.
      */
-    template <bool B, typename T, size_t N>
+    template <array_strides_mode Layout, typename T, size_t N>
     line_sender_buffer& column(
         column_name_view name,
         const size_t rank,
@@ -666,16 +676,46 @@ class line_sender_buffer
             std::is_same_v<T, double>,
             "Only double types are supported for arrays");
         may_init();
-        line_sender_error::wrapped_call(
-            B ? ::line_sender_buffer_column_f64_arr_byte_strides
-              : ::line_sender_buffer_column_f64_arr_elem_strides,
-            _impl,
-            name._impl,
-            rank,
-            shape.data(),
-            strides.data(),
-            reinterpret_cast<const uint8_t*>(data.data()),
-            sizeof(double) * N);
+        switch (Layout)
+        {
+        case array_strides_mode::c_major:
+            if (!strides.empty())
+            {
+                throw line_sender_error{
+                    line_sender_error_code::config_error,
+                    "C_Major layout requires empty strides vector"};
+            }
+            line_sender_error::wrapped_call(
+                ::line_sender_buffer_column_f64_arr_c_major,
+                _impl,
+                name._impl,
+                rank,
+                shape.data(),
+                reinterpret_cast<const uint8_t*>(data.data()),
+                sizeof(double) * N);
+            break;
+        case array_strides_mode::bytes:
+            line_sender_error::wrapped_call(
+                ::line_sender_buffer_column_f64_arr_byte_strides,
+                _impl,
+                name._impl,
+                rank,
+                shape.data(),
+                strides.data(),
+                reinterpret_cast<const uint8_t*>(data.data()),
+                sizeof(double) * N);
+            break;
+        case array_strides_mode::elems:
+            line_sender_error::wrapped_call(
+                ::line_sender_buffer_column_f64_arr_elem_strides,
+                _impl,
+                name._impl,
+                rank,
+                shape.data(),
+                strides.data(),
+                reinterpret_cast<const uint8_t*>(data.data()),
+                sizeof(double) * N);
+        }
         return *this;
     }
 
diff --git a/questdb-rs-ffi/src/lib.rs b/questdb-rs-ffi/src/lib.rs
diff --git a/questdb-rs-ffi/src/ndarr.rs b/questdb-rs-ffi/src/ndarr.rs
diff --git a/system_test/questdb_line_sender.py b/system_test/questdb_line_sender.py
diff --git a/system_test/test.py b/system_test/test.py
