| .. Licensed to the Apache Software Foundation (ASF) under one |
| .. or more contributor license agreements. See the NOTICE file |
| .. distributed with this work for additional information |
| .. regarding copyright ownership. The ASF licenses this file |
| .. to you under the Apache License, Version 2.0 (the |
| .. "License"); you may not use this file except in compliance |
| .. with the License. You may obtain a copy of the License at |
| |
| .. http://www.apache.org/licenses/LICENSE-2.0 |
| |
| .. Unless required by applicable law or agreed to in writing, |
| .. software distributed under the License is distributed on an |
| .. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| .. KIND, either express or implied. See the License for the |
| .. specific language governing permissions and limitations |
| .. under the License. |
| |
| .. default-domain:: cpp |
| .. highlight:: cpp |
| |
| .. cpp:namespace:: arrow |
| |
| 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 :class:`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 :class:`std::shared_ptr` but sometimes also :class:`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 |
| :class:`arrow::Status` instance. Arrow doesn't throw exceptions of its |
| own, but third-party exceptions might propagate through, especially |
| :class:`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 |
| :class:`arrow::Result <template\<class T\> arrow::Result>`. However, |
| some APIs (usually deprecated) return :class:`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 :class:`arrow::Result` or |
| :class:`arrow::Status` and wants to propagate any non-successful outcome, two |
| convenience macros are available: |
| |
| * :c:macro:`ARROW_RETURN_NOT_OK` takes a :class:`arrow::Status` parameter |
| and returns it if not successful. |
| |
| * :c:macro:`ARROW_ASSIGN_OR_RAISE` takes a :class:`arrow::Result` parameter, |
| assigns its result to a *lvalue* if successful, or returns the corresponding |
| :class:`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(); |
| } |
| |
| .. seealso:: |
| :doc:`API reference for error reporting <api/support>` |