TimescaleDB的Cross-Module Function机制

函数映射的三层结构

SQL 层: compress_chunk(sql) → 'ts_compress_chunk'(C函数名) ↓ src/cross_module_fn.c: ts_compress_chunk() → 代理/跳板函数 (Apache License) ↓ ts_cm_functions->compress_chunk(fcinfo) ↓ tsl/src/init.c: .compress_chunk = tsl_compress_chunk ← 真正的函数指针赋值 (TSL License) ↓ tsl/src/compression/api.c: tsl_compress_chunk() ← 真正的实现

第一步：SQL 声明 → C 函数名

sql/maintenance_utils.sql:40:

CREATE FUNCTION compress_chunk(...) RETURNS REGCLASS AS '@MODULE_PATHNAME@', 'ts_compress_chunk' LANGUAGE C;

第二步：跨模块代理包装器

src/cross_module_fn.c:18-23 的CROSSMODULE_WRAPPER宏：

#define CROSSMODULE_WRAPPER(func) \ TS_FUNCTION_INFO_V1(ts_##func); \ Datum ts_##func(PG_FUNCTION_ARGS) \ { \ PG_RETURN_DATUM(ts_cm_functions->func(fcinfo)); \ } CROSSMODULE_WRAPPER(compress_chunk); // 展开为 ts_compress_chunk()

展开后：

// 自动生成 ts_compress_chunk 函数！ Datum ts_compress_chunk(PG_FUNCTION_ARGS) { // 通过函数指针调用真正的实现 PG_RETURN_DATUM(ts_cm_functions->compress_chunk(fcinfo)); }

ts_compress_chunk不是手动写的，是 CROSSMODULE_WRAPPER 宏自动生成的！

第三步：函数指针赋值

CrossModuleFunctions结构体在 cross_module_fn.h:131 有一个字段：

typedef struct CrossModuleFunctions { // ... PGFunction compress_chunk; // 函数指针 PGFunction decompress_chunk; // ... } CrossModuleFunctions;

在 tsl/src/init.c:176 初始化时赋值：

static CrossModuleFunctions tsl_cm_functions = { // ... .compress_chunk = tsl_compress_chunk, // 指向真正的实现！ .decompress_chunk = tsl_decompress_chunk, // ... };

ts_module_init()执行时：

ts_cm_functions = &tsl_cm_functions; // 全局函数表指向 TSL 实现

为什么这样设计？双 License 架构

┌──────────────────────────────────────────────────────────┐ │ TimescaleDB 双 License 架构 │ ├──────────────────────────────────────────────────────────┤ │ │ │ src/ 目录 (Apache 2.0 License - 完全开源) │ │ ├── cross_module_fn.c ← CROSSMODULE_WRAPPER 宏 │ │ │ 生成 ts_compress_chunk() 代理函数 │ │ │ 默认函数表 → error_no_default_fn_pg_community │ │ │ (如果只装开源版，调用会报错: "not supported │ │ │ under the current license") │ │ │ │ │ └── cross_module_fn.h ← CrossModuleFunctions 结构体 │ │ │ │ tsl/ 目录 (Timescale License - 商业功能) │ │ ├── init.c ← 赋值函数表 │ │ │ .compress_chunk = tsl_compress_chunk │ │ └── compression/api.c ← 真正的实现 │ │ tsl_compress_chunk() {...} │ │ │ └──────────────────────────────────────────────────────────┘

• Community 版（只用src/）：函数表保留默认值error_no_default_fn_pg_community，压缩功能不可用
• 完整版（加载tsl/）：_PG_init()调用ts_module_init()，将ts_cm_functions指向tsl_cm_functions，所有函数指针替换为真实实现

总结

ts_compress_chunk是真实存在的 C 函数，但它不是手写的 — 它由CROSSMODULE_WRAPPER(compress_chunk)宏自动生成。它就是一张跳板，通过##宏拼接生成：

// 宏： CROSSMODULE_WRAPPER(compress_chunk) // 生成函数名： ts_##compress_chunk → ts_compress_chunk // 函数体： 调用 ts_cm_functions->compress_chunk(fcinfo) // 即 tsl_compress_chunk(fcinfo)

所有以ts_开头、tsl_实现的功能（压缩、解压缩、连续聚合、压缩策略等），都走这套CROSSMODULE_WRAPPER→ts_cm_functions函数表 → TSL 实现的路径。