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).

When an API can return either an error code or a successful value, it usually does so by returning the template class arrow::Result. However, some APIs (usually deprecated) return arrow::Status and pass the result value as an out-pointer parameter.

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

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
}

If the caller function itself returns a arrow::Result or arrow::Status and wants to propagate any non-successful outcome, two convenience macros are available:

ARROW_RETURN_NOT_OK takes a arrow::Status parameter and returns it if not successful.
ARROW_ASSIGN_OR_RAISE takes a arrow::Result parameter, assigns its result to a lvalue if successful, or returns the corresponding arrow::Status on error.

For example:

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();
}