Add tiledb_stats_is_enabled to C and C++ APIs (#5395)

The C API has functions `tiledb_stats_enable() and
`tiledb_stats_disable()` which affect global process state.

A library or application running on top of tiledb might want to enable
statistics for a span and then restore the previous state. This is not
possible without a way of asking whether stats gathering is currently
enabled.

This pull request adds `tiledb_stats_is_enabled` so that users can check
whether stats are currently enabled. Use of this API is demonstrated in
tests via `ScopedStats`.

---
TYPE: C_API | CPP_API
DESC: add tiledb_stats_is_enabled to C and C++ APIs

---------

Co-authored-by: Ypatia Tsavliri <[email protected]>
Co-authored-by: Theodore Tsirpanis <[email protected]>

examples/cpp_api/using_tiledb_stats.cc

@@ -39,6 +39,25 @@ using namespace tiledb;
 // Name of array.
 std::string array_name("stats_array");
 
+/**
+ * Enables tiledb statistics gathering within a block.
+ */
+class ScopedStats {
+ public:
+  ScopedStats()
+      : enabled_(Stats::is_enabled()) {
+    Stats::enable();
+  }
+  ~ScopedStats() {
+    if (!enabled_) {
+      Stats::disable();
+    }
+  }
+
+ private:
+  bool enabled_;
+};
+
 void create_array(uint32_t row_tile_extent, uint32_t col_tile_extent) {
   Context ctx;
   VFS vfs(ctx);
@@ -86,10 +105,11 @@ void read_array() {
   query.set_subarray(subarray).set_data_buffer("a", values);
 
   // Enable the stats for the read query, and print the report.
-  Stats::enable();
-  query.submit();
+  {
+    ScopedStats stats;
+    query.submit();
+  }
   Stats::dump(stdout);
-  Stats::disable();
 }
 
 int main() {

test/CMakeLists.txt

@@ -98,6 +98,7 @@ set(TILEDB_UNIT_TEST_SOURCES
   src/unit-capi-sparse_neg_2.cc
   src/unit-capi-sparse_real.cc
   src/unit-capi-sparse_real_2.cc
+  src/unit-capi-stats.cc
   src/unit-capi-string.cc
   src/unit-capi-string_dims.cc
   src/unit-capi-update-queries.cc
@@ -179,6 +180,7 @@ if (TILEDB_CPP_API)
     src/cpp-integration-query-condition.cc
     src/unit-cppapi-schema.cc
     src/unit-cppapi-schema-evolution.cc
+    src/unit-cppapi-stats.cc
     src/unit-cppapi-string-dims.cc
     src/unit-cppapi-subarray.cc
     src/unit-cppapi-type.cc

test/src/unit-capi-stats.cc

@@ -0,0 +1,41 @@
+/**
+ * @file unit-capi-stats.cc
+ *
+ * @section LICENSE
+ *
+ * The MIT License
+ *
+ * @copyright Copyright (c) 2023-2024 TileDB Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @section DESCRIPTION
+ *
+ * Tests the C API for stats related functions.
+ */
+
+#include "test/support/src/stats.h"
+#include "tiledb/sm/cpp_api/tiledb"
+
+#include <test/support/tdb_catch.h>
+
+TEST_CASE("tiledb_stats_is_enabled null arg", "[stats]") {
+  auto status = tiledb_stats_is_enabled(nullptr);
+  CHECK(status == TILEDB_ERR);
+}

test/src/unit-cppapi-stats.cc

@@ -0,0 +1,71 @@
+/**
+ * @file unit-cppapi-stats.cc
+ *
+ * @section LICENSE
+ *
+ * The MIT License
+ *
+ * @copyright Copyright (c) 2023-2024 TileDB Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @section DESCRIPTION
+ *
+ * Tests the C++ API for stats related functions.
+ */
+
+#include "test/support/src/stats.h"
+#include "tiledb/sm/cpp_api/tiledb"
+
+#include <test/support/tdb_catch.h>
+
+using namespace tiledb;
+
+TEST_CASE("stats gathering default", "[stats]") {
+  CHECK(!Stats::is_enabled());
+}
+
+TEST_CASE("stats disabled, scoped enable", "[stats]") {
+  CHECK(!Stats::is_enabled());
+  {
+    test::ScopedStats scoped;
+    CHECK(Stats::is_enabled());
+  }
+  CHECK(!Stats::is_enabled());
+}
+
+TEST_CASE("stats enabled, scoped enable", "[stats]") {
+  CHECK(!Stats::is_enabled());
+
+  // outer scope disables when exiting
+  {
+    test::ScopedStats outer;
+    CHECK(Stats::is_enabled());
+
+    // inner scope does not disable since stats was enabled when entering
+    {
+      test::ScopedStats inner;
+      CHECK(Stats::is_enabled());
+    }
+
+    CHECK(Stats::is_enabled());
+  }
+
+  CHECK(!Stats::is_enabled());
+}

test/support/CMakeLists.txt

@@ -45,6 +45,7 @@ set(TILEDB_TEST_SUPPORT_SOURCES
   src/mem_helpers.h
   src/mem_helpers.cc
   src/serialization_wrappers.cc
+  src/stats.cc
   src/temporary_local_directory.cc
   src/vfs_helpers.cc
   )

test/support/src/stats.cc

@@ -0,0 +1,51 @@
+/**
+ * @file   stats.cc
+ *
+ * @section LICENSE
+ *
+ * The MIT License
+ *
+ * @copyright Copyright (c) 2017-2024 TileDB, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @section DESCRIPTION
+ *
+ * This file defines some helpers for tests which use stats gathering.
+ */
+
+#include "test/support/src/stats.h"
+#include "tiledb/sm/cpp_api/tiledb"
+
+using namespace tiledb;
+
+namespace tiledb::test {
+
+ScopedStats::ScopedStats()
+    : enabled_(Stats::is_enabled()) {
+  Stats::enable();
+}
+
+ScopedStats::~ScopedStats() {
+  if (!enabled_) {
+    Stats::disable();
+  }
+}
+
+}  // namespace tiledb::test

test/support/src/stats.h

@@ -0,0 +1,49 @@
+/**
+ * @file   stats.h
+ *
+ * @section LICENSE
+ *
+ * The MIT License
+ *
+ * @copyright Copyright (c) 2017-2024 TileDB, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @section DESCRIPTION
+ *
+ * This file declares some helpers for tests which use stats gathering.
+ */
+
+#ifndef TILEDB_TEST_STATS_HELPERS_H
+#define TILEDB_TEST_STATS_HELPERS_H
+
+namespace tiledb::test {
+
+class ScopedStats {
+ public:
+  ScopedStats();
+  ~ScopedStats();
+
+ private:
+  bool enabled_;
+};
+
+}  // namespace tiledb::test
+
+#endif

tiledb/sm/c_api/tiledb.cc

@@ -1266,6 +1266,12 @@ int32_t tiledb_stats_disable() {
   return TILEDB_OK;
 }
 
+int32_t tiledb_stats_is_enabled(uint8_t* enabled) {
+  ensure_output_pointer_is_valid(enabled);
+  *enabled = tiledb::sm::stats::all_stats.enabled() ? 1 : 0;
+  return TILEDB_OK;
+}
+
 int32_t tiledb_stats_reset() {
   tiledb::sm::stats::all_stats.reset();
   return TILEDB_OK;
@@ -3077,6 +3083,10 @@ CAPI_INTERFACE_NULL(stats_disable) {
   return api_entry_plain<tiledb::api::tiledb_stats_disable>();
 }
 
+CAPI_INTERFACE(stats_is_enabled, uint8_t* enabled) {
+  return api_entry_plain<tiledb::api::tiledb_stats_is_enabled>(enabled);
+}
+
 CAPI_INTERFACE_NULL(stats_reset) {
   return api_entry_plain<tiledb::api::tiledb_stats_reset>();
 }

tiledb/sm/c_api/tiledb.h

@@ -1412,6 +1412,14 @@ TILEDB_EXPORT int32_t tiledb_stats_enable(void) TILEDB_NOEXCEPT;
  */
 TILEDB_EXPORT int32_t tiledb_stats_disable(void) TILEDB_NOEXCEPT;
 
+/**
+ * Returns whether internal statistics gathering is enabled.
+ *
+ * @param enabled Output argument, non-zero for enabled and zero for disabled.
+ * @return `TILEDB_OK` for success and `TILEDB_ERR` for error
+ */
+TILEDB_EXPORT int32_t tiledb_stats_is_enabled(uint8_t* enabled) TILEDB_NOEXCEPT;
+
 /**
  * Reset all internal statistics counters to 0.
  *

tiledb/sm/cpp_api/stats.h

@@ -64,6 +64,18 @@ class Stats {
     check_error(tiledb_stats_disable(), "error disabling stats");
   }
 
+  /**
+   * Returns whether internal statistics gathering is enabled.
+   *
+   * @return true if statistics gathering is enabled and false otherwise.
+   */
+  static bool is_enabled() {
+    uint8_t enabled;
+    check_error(
+        tiledb_stats_is_enabled(&enabled), "error checking stats enabled");
+    return enabled != 0;
+  }
+
   /** Reset all internal statistics counters to 0. */
   static void reset() {
     check_error(tiledb_stats_reset(), "error resetting stats");