约定

Arrow C++ API 遵循一些简单的指南。与许多规则一样，也可能存在例外。

语言版本

从 10.0 版本开始，Arrow C++ 与 C++17 兼容。

命名空间

所有 Arrow API（宏除外）都在 arrow 命名空间内，并在其嵌套命名空间中。

安全指针

Arrow 对象通常使用安全指针传递和存储 - 大多数情况下是 std::shared_ptr，但有时也是 std::unique_ptr。

不可变性

许多 Arrow 对象是不可变的：一旦构造，它们的逻辑属性就无法再改变。这使得它们可以在多线程场景中使用，而无需繁琐且容易出错的同步。

当然，也有一些明显的例外，例如 I/O 对象或可变数据缓冲区。

错误报告

大多数 API 通过返回 arrow::Status 实例来指示成功或错误结果。Arrow 不会抛出它自己的异常，但第三方异常可能会传播，尤其是 std::bad_alloc（但 Arrow 不使用标准分配器来分配大型数据）。

当 API 可以返回错误代码或成功值时，它通常通过返回模板类 arrow::Result 来实现。但是，某些 API（通常已弃用）返回 arrow::Status，并将结果值作为输出指针参数传递。

以下是如何检查操作结果的示例

const int64_t buffer_size = 4096;

auto maybe_buffer = arrow::AllocateBuffer(buffer_size, &buffer);
if (!maybe_buffer.ok()) {
   // ... handle error
} else {
   std::shared_ptr<arrow::Buffer> buffer = *maybe_buffer;
   // ... use allocated buffer
}

如果调用函数本身返回 arrow::Result 或 arrow::Status 并且想要传播任何不成功的结果，则可以使用两个方便的宏

• ARROW_RETURN_NOT_OK 接收一个 arrow::Status 参数，如果不成功则返回它。

• ARROW_ASSIGN_OR_RAISE 接收一个 arrow::Result 参数，如果成功则将其结果分配给lvalue，或者在错误时返回相应的 arrow::Status。

例如

arrow::Status DoSomething() {
   const int64_t buffer_size = 4096;
   std::shared_ptr<arrow::Buffer> buffer;
   ARROW_ASSIGN_OR_RAISE(buffer, arrow::AllocateBuffer(buffer_size));
   // ... allocation successful, do something with buffer below

   // return success at the end
   return Status::OK();
}

另请参见

错误报告的 API 参考