Conventions

The Arrow C++ API follows a few simple guidelines. As with many rules, there may be exceptions.

Language version

Arrow is C++11-compatible. A few backports are used for newer functionality, for example the std::string_view class.

Namespacing

All the Arrow API (except macros) is namespaced inside a arrow namespace, and nested namespaces thereof.

Safe pointers

Arrow objects are usually passed and stored using safe pointers – most of the time std::shared_ptr but sometimes also std::unique_ptr.

Immutability

Many Arrow objects are immutable: once constructed, their logical properties cannot change anymore. This makes it possible to use them in multi-threaded scenarios without requiring tedious and error-prone synchronization.

There are obvious exceptions to this, such as IO objects or mutable data buffers.

Error reporting

Most APIs indicate a successful or erroneous outcome by returning a arrow::Status instance. Arrow doesn’t throw exceptions of its own, but third-party exceptions might propagate through, especially std::bad_alloc (but Arrow doesn’t use the standard allocators for large data).

As a consequence, the result value of a function is generally passed as an out-pointer parameter, rather than as a function return value.

(however, functions which always determiniscally succeed may eschew this convention and return their result directly)

Here is an example of checking the outcome of an operation:

const int64_t buffer_size = 4096;
std::shared_ptr<arrow::Buffer> buffer;

auto status = arrow::AllocateBuffer(buffer_size, &buffer);
if (!status.ok()) {
   // ... handle error
}

If the caller function itself returns a arrow::Status and wants to propagate any non-successful outcomes, a convenience macro ARROW_RETURN_NON_OK() is available:

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

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