TsFile C++ 文档

简介

本目录包含 TsFile 的 C++ 实现版本。目前，C++ 版本支持 TsFile 的查询与写入功能，包括基于时间过滤的查询。

源代码位于 ./src 目录。 C/C++ 示例代码位于 ./examples 目录。 TsFile_cpp 的性能基准测试位于 ./bench_mark 目录。

此外，在 ./src/cwrapper 目录中提供了 C 函数封装接口，Python 工具依赖该封装。

如何贡献

我们使用 clang-format 来确保 C++ 代码遵循 ./clang-format 文件中定义的一致规范（类似于 Google 风格）。

欢迎提交任何 Bug 报告。 你可以创建一个以 [CPP] 开头的 Issue 来描述问题，例如： https://github.com/apache/tsfile/issues/94

构建

环境要求

sudo apt-get update
sudo apt-get install -y cmake make g++ clang-format libuuid-dev

构建 tsfile：

bash build.sh

如果你安装了 Maven 工具，也可以运行：

mvn package -P with-cpp clean verify

构建完成后，可在 ./build 目录下找到生成的共享库文件。

在向 GitHub 提交代码之前，请确保 mvn 编译通过。

Windows 下 MinGW 编译问题

如果你在 Windows 下使用 MinGW 编译时遇到错误，可以尝试使用以下我们验证通过的版本：

  • GCC 14.2.0（POSIX 线程） + LLVM/Clang/LLD/LLDB 18.1.8 + MinGW-w64 12.0.0 UCRT - release 1
  • GCC 12.2.0 + LLVM/Clang/LLD/LLDB 16.0.0 + MinGW-w64 10.0.0（UCRT）- release 5
  • GCC 12.2.0 + LLVM/Clang/LLD/LLDB 16.0.0 + MinGW-w64 10.0.0（MSVCRT）- release 5
  • GCC 11.2.0 + MinGW-w64 10.0.0（MSVCRT）- release 1

配置交叉编译工具链

修改工具链文件 cmake/ToolChain.cmake，定义以下变量：

  • CMAKE_C_COMPILER：指定 C 编译器路径。
  • CMAKE_CXX_COMPILER：指定 C++ 编译器路径。
  • CMAKE_FIND_ROOT_PATH：设置交叉编译环境的根路径（例如交叉编译工具链目录）。

在 cpp/ 目录下执行以下命令创建构建目录并开始编译：

mkdir build && cd build
cmake .. -DToolChain=ON
make

并行写入

TsFile C++ 支持基于线程池的列级并行编码，适用于表模型写入路径（write_table）。启用后，时间列和所有值列使用预计算的 page 边界并行写入，同时保证各列 page 对齐封盘。

编译选项

并行写入通过 ENABLE_THREADS CMake 选项控制（默认开启）：

cmake .. -DENABLE_THREADS=ON   # 开启（默认）
cmake .. -DENABLE_THREADS=OFF  # 关闭——编译期剥离所有线程代码

运行时配置

#include "common/global.h"

// 运行时开启或关闭并行写入（单核机器自动禁用）
storage::set_parallel_write_enabled(true);

// 设置工作线程数（必须在创建 TsFileWriter 之前调用）
storage::set_write_thread_count(4);

默认情况下，当机器 CPU 核数大于 1 时自动启用并行写入，线程数设为硬件核数（上限 64）。

使用 TsFile

你可以在 ./examples/cpp_examples 目录下的 demo_read.cpp 和 demo_write.cpp 中查看读写数据的示例。

在 ./examples/c_examples 目录下，还提供了使用 C 风格 API 在 C 环境中读写数据的示例。

在 ./examples 目录下执行：

bash build.sh

即可在 ./examples/build 目录下生成可执行文件。