Move tiledb_ctx_alloc_with_error to the stable API header and use it in the C++ API. (#5667)

Move `tiledb_ctx_alloc_with_error` to the stable API header and use it
in the C++ API.

---
TYPE: C_API
DESC: The `tiledb_ctx_alloc_with_error` function was moved to the stable
API header.

---
TYPE: CPP_API
DESC: Improved error reporting when creating a context fails.

Author: teo-tsirpanis

CMakeLists.txt

@@ -314,7 +314,6 @@ list(APPEND TILEDB_C_API_RELATIVE_HEADERS
     "${CMAKE_SOURCE_DIR}/tiledb/api/c_api/buffer/buffer_api_external.h"
     "${CMAKE_SOURCE_DIR}/tiledb/api/c_api/buffer_list/buffer_list_api_external.h"
     "${CMAKE_SOURCE_DIR}/tiledb/api/c_api/config/config_api_external.h"
-    "${CMAKE_SOURCE_DIR}/tiledb/api/c_api/context/context_api_experimental.h"
     "${CMAKE_SOURCE_DIR}/tiledb/api/c_api/context/context_api_external.h"
     "${CMAKE_SOURCE_DIR}/tiledb/api/c_api/current_domain/current_domain_api_enum.h"
     "${CMAKE_SOURCE_DIR}/tiledb/api/c_api/current_domain/current_domain_api_external_experimental.h"

tiledb/api/c_api/context/context_api.cc

@@ -31,7 +31,6 @@
  */
 
 #include "../config/config_api_internal.h"
-#include "context_api_experimental.h"
 #include "context_api_external.h"
 #include "context_api_internal.h"
 #include "tiledb/api/c_api_support/c_api_support.h"

tiledb/api/c_api/context/context_api_experimental.h

@@ -73,6 +73,39 @@ typedef struct tiledb_ctx_handle_t tiledb_ctx_t;
 TILEDB_EXPORT capi_return_t
 tiledb_ctx_alloc(tiledb_config_t* config, tiledb_ctx_t** ctx) TILEDB_NOEXCEPT;
 
+/**
+ * Creates a TileDB context, which contains the TileDB storage manager
+ * that manages everything in the TileDB library.
+ *
+ * **Examples:**
+ *
+ * Without config (i.e., use default configuration):
+ *
+ * @code{.c}
+ * tiledb_ctx_t* ctx;
+ * tiledb_error_t* error;
+ * tiledb_ctx_alloc_with_error(NULL, &ctx, &error);
+ * @endcode
+ *
+ * With some config:
+ *
+ * @code{.c}
+ * tiledb_ctx_t* ctx;
+ * tiledb_error_t* error;
+ * tiledb_ctx_alloc_with_error(config, &ctx, &error);
+ * @endcode
+ *
+ * @param[in] config The configuration parameters (`NULL` means default).
+ * @param[out] ctx The TileDB context to be created.
+ * @param[out] error Error object returned upon error (`NULL` if there is
+ *     no error).
+ * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error.
+ */
+TILEDB_EXPORT capi_return_t tiledb_ctx_alloc_with_error(
+    tiledb_config_t* config,
+    tiledb_ctx_t** ctx,
+    tiledb_error_t** error) TILEDB_NOEXCEPT;
+
 /**
  * Destroys the TileDB context, freeing all associated memory and resources.
  *

tiledb/api/c_api/context/context_api_external.h

@@ -44,7 +44,6 @@
 #include "tiledb/api/c_api/array_schema/array_schema_api_experimental.h"
 #include "tiledb/api/c_api/array_schema_evolution/array_schema_evolution_api_experimental.h"
 #include "tiledb/api/c_api/attribute/attribute_api_external_experimental.h"
-#include "tiledb/api/c_api/context/context_api_experimental.h"
 #include "tiledb/api/c_api/current_domain/current_domain_api_external_experimental.h"
 #include "tiledb/api/c_api/enumeration/enumeration_api_experimental.h"
 #include "tiledb/api/c_api/fragment_info/fragment_info_api_experimental.h"

tiledb/sm/c_api/tiledb_experimental.h

@@ -79,27 +79,19 @@ class Context {
    * Constructor. Creates a TileDB Context with default configuration.
    * @throws TileDBError if construction fails
    */
-  Context() {
-    tiledb_ctx_t* ctx;
-    if (tiledb_ctx_alloc(nullptr, &ctx) != TILEDB_OK)
-      throw TileDBError("[TileDB::C++API] Error: Failed to create context");
-    ctx_ = std::shared_ptr<tiledb_ctx_t>(ctx, Context::free);
-    error_handler_ = default_error_handler;
-
+  Context()
+      : ctx_(make_ctx(nullptr))
+      , error_handler_(default_error_handler) {
     set_tag("x-tiledb-api-language", "c++");
   }
 
   /**
    * Constructor. Creates a TileDB context with the given configuration.
    * @throws TileDBError if construction fails
    */
-  explicit Context(const Config& config) {
-    tiledb_ctx_t* ctx;
-    if (tiledb_ctx_alloc(config.ptr().get(), &ctx) != TILEDB_OK)
-      throw TileDBError("[TileDB::C++API] Error: Failed to create context");
-    ctx_ = std::shared_ptr<tiledb_ctx_t>(ctx, Context::free);
-    error_handler_ = default_error_handler;
-
+  explicit Context(const Config& config)
+      : ctx_(make_ctx(config.ptr().get()))
+      , error_handler_(default_error_handler) {
     set_tag("x-tiledb-api-language", "c++");
   }
 
@@ -264,6 +256,21 @@ class Context {
   /** An error handler callback. */
   std::function<void(const std::string&)> error_handler_;
 
+  static std::shared_ptr<tiledb_ctx_t> make_ctx(tiledb_config_t* config) {
+    tiledb_ctx_t* ctx;
+    tiledb_error_t* err;
+    tiledb_ctx_alloc_with_error(config, &ctx, &err);
+    if (err != nullptr) {
+      const char* msg_cstr;
+      tiledb_error_message(err, &msg_cstr);
+      std::string msg = "[TileDB::C++API] Error: Failed to create context: " +
+                        std::string(msg_cstr);
+      tiledb_error_free(&err);
+      throw TileDBError(msg);
+    }
+    return std::shared_ptr<tiledb_ctx_t>(ctx, Context::free);
+  }
+
   /** Wrapper function for freeing a context C object. */
   static void free(tiledb_ctx_t* ctx) {
     tiledb_ctx_free(&ctx);