This is an automated email from the ASF dual-hosted git repository.
ColinLeeo pushed a commit to branch docs/dev
in repository https://gitbox.apache.org/repos/asf/tsfile.git
The following commit(s) were added to refs/heads/docs/dev by this push:
new 99aaa34c9 docs: restore RestorableTsFileIOWriter interface docs (#896)
99aaa34c9 is described below
commit 99aaa34c9b428f775270f986561db4e89920d620
Author: leto-bbq <[email protected]>
AuthorDate: Wed Aug 5 16:07:22 2026 +0800
docs: restore RestorableTsFileIOWriter interface docs (#896)
* docs: restore RestorableTsFileIOWriter interface docs
* docs: remove V2.3.1 marker
* docs: remove remaining V2.3.1 markers
---
.../InterfaceDefinition/InterfaceDefinition-CPP.md | 39 ++++++++++++++++++++++
.../InterfaceDefinition/InterfaceDefinition-CPP.md | 39 ++++++++++++++++++++++
.../InterfaceDefinition/InterfaceDefinition-CPP.md | 39 ++++++++++++++++++++++
.../InterfaceDefinition/InterfaceDefinition-CPP.md | 39 ++++++++++++++++++++++
4 files changed, 156 insertions(+)
diff --git
a/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
b/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
index 496e48aca..ab12740a0 100644
---
a/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
+++
b/src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
@@ -269,6 +269,45 @@ public:
};
```
+### RestorableTsFileIOWriter
+
+```cpp
+namespace storage {
+/**
+ * RestorableTsFileIOWriter is used to open a TsFile and perform optional
recovery operations on it.
+ * Inherits from TsFileIOWriter and supports continuous writing after file
recovery.
+ *
+ * (1) If the TsFile was closed normally: has_crashed()=false,
can_write()=false
+ *
+ * (2) If the TsFile is incomplete / the program crashed: has_crashed()=true,
+ * can_write()=true. The writer will truncate the corrupted data and allow
further writing.
+ *
+ * Implemented based on standard C++11, uses RAII and smart pointers to avoid
memory leaks.
+ */
+class RestorableTsFileIOWriter : public TsFileIOWriter {
+ public:
+ RestorableTsFileIOWriter();
+
+ /**
+ * Opens a TsFile for recovery / appending data.
+ * Uses O_RDWR|O_CREAT mode without O_TRUNC, so the original file content
is preserved.
+ *
+ * @param file_path Path of the TsFile
+ * @param truncate_corrupted If true, truncate the corrupted data;
+ * If false, do not truncate (the incomplete file remains unchanged)
+ * @return E_OK on success, error code on failure
+ */
+ int open(const std::string& file_path, bool truncate_corrupted = true);
+
+ /**
+ * Closes the file
+ */
+ void close();
+};
+
+} // namespace storage
+```
+
### Configuring encoding and compression
Encoding and compression are chosen **per data type**: each type has a default
diff --git
a/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
b/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
index 496e48aca..ab12740a0 100644
---
a/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
+++
b/src/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
@@ -269,6 +269,45 @@ public:
};
```
+### RestorableTsFileIOWriter
+
+```cpp
+namespace storage {
+/**
+ * RestorableTsFileIOWriter is used to open a TsFile and perform optional
recovery operations on it.
+ * Inherits from TsFileIOWriter and supports continuous writing after file
recovery.
+ *
+ * (1) If the TsFile was closed normally: has_crashed()=false,
can_write()=false
+ *
+ * (2) If the TsFile is incomplete / the program crashed: has_crashed()=true,
+ * can_write()=true. The writer will truncate the corrupted data and allow
further writing.
+ *
+ * Implemented based on standard C++11, uses RAII and smart pointers to avoid
memory leaks.
+ */
+class RestorableTsFileIOWriter : public TsFileIOWriter {
+ public:
+ RestorableTsFileIOWriter();
+
+ /**
+ * Opens a TsFile for recovery / appending data.
+ * Uses O_RDWR|O_CREAT mode without O_TRUNC, so the original file content
is preserved.
+ *
+ * @param file_path Path of the TsFile
+ * @param truncate_corrupted If true, truncate the corrupted data;
+ * If false, do not truncate (the incomplete file remains unchanged)
+ * @return E_OK on success, error code on failure
+ */
+ int open(const std::string& file_path, bool truncate_corrupted = true);
+
+ /**
+ * Closes the file
+ */
+ void close();
+};
+
+} // namespace storage
+```
+
### Configuring encoding and compression
Encoding and compression are chosen **per data type**: each type has a default
diff --git
a/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
b/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
index 50de78b47..16198c056 100644
---
a/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
+++
b/src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
@@ -269,6 +269,45 @@ public:
};
```
+### RestorableTsFileIOWriter
+
+```cpp
+namespace storage {
+/**
+ * RestorableTsFileIOWriter 用于打开 TsFile 并对其进行可选的恢复操作
+ * 继承自 TsFileIOWriter，支持在文件恢复后继续写入
+ *
+ * (1) 若 TsFile 正常关闭：has_crashed()=false，can_write()=false
+ *
+ * (2) 若 TsFile 不完整/程序崩溃：has_crashed()=true，
+ * can_write()=true，写入器会截断损坏数据并允许继续写入
+ *
+ * 基于标准 C++11 实现，通过 RAII 和智能指针避免内存泄漏
+ */
+class RestorableTsFileIOWriter : public TsFileIOWriter {
+ public:
+ RestorableTsFileIOWriter();
+
+ /**
+ * 打开 TsFile 用于恢复/追加写入
+ * 使用 O_RDWR|O_CREAT 模式，不使用 O_TRUNC，因此会保留文件原有内容
+ *
+ * @param file_path TsFile 文件路径
+ * @param truncate_corrupted 若为 true，则截断损坏的数据；
+ * 若为 false，则不截断（不完整文件保持原样）
+ * @return 成功返回 E_OK，失败返回错误码
+ */
+ int open(const std::string& file_path, bool truncate_corrupted = true);
+
+ /**
+ * 关闭文件
+ */
+ void close();
+};
+
+} // namespace storage
+```
+
### 配置编码与压缩
编码与压缩 **按数据类型** 选取：每种类型都有默认值（见上表）。你可以修改这些默认值，
diff --git
a/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
b/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
index 50de78b47..16198c056 100644
---
a/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
+++
b/src/zh/UserGuide/latest/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md
@@ -269,6 +269,45 @@ public:
};
```
+### RestorableTsFileIOWriter
+
+```cpp
+namespace storage {
+/**
+ * RestorableTsFileIOWriter 用于打开 TsFile 并对其进行可选的恢复操作
+ * 继承自 TsFileIOWriter，支持在文件恢复后继续写入
+ *
+ * (1) 若 TsFile 正常关闭：has_crashed()=false，can_write()=false
+ *
+ * (2) 若 TsFile 不完整/程序崩溃：has_crashed()=true，
+ * can_write()=true，写入器会截断损坏数据并允许继续写入
+ *
+ * 基于标准 C++11 实现，通过 RAII 和智能指针避免内存泄漏
+ */
+class RestorableTsFileIOWriter : public TsFileIOWriter {
+ public:
+ RestorableTsFileIOWriter();
+
+ /**
+ * 打开 TsFile 用于恢复/追加写入
+ * 使用 O_RDWR|O_CREAT 模式，不使用 O_TRUNC，因此会保留文件原有内容
+ *
+ * @param file_path TsFile 文件路径
+ * @param truncate_corrupted 若为 true，则截断损坏的数据；
+ * 若为 false，则不截断（不完整文件保持原样）
+ * @return 成功返回 E_OK，失败返回错误码
+ */
+ int open(const std::string& file_path, bool truncate_corrupted = true);
+
+ /**
+ * 关闭文件
+ */
+ void close();
+};
+
+} // namespace storage
+```
+
### 配置编码与压缩
编码与压缩 **按数据类型** 选取：每种类型都有默认值（见上表）。你可以修改这些默认值，
