Document the ROCTX API

Change-Id: I63a04139d1640ea5d52f6143cf2e9bfc0614a894

src/roctx/roctx.cpp

@@ -22,113 +22,63 @@
 #include "roctracer_roctx.h"
 #include "ext/prof_protocol.h"
 
-#include <cassert>
-
 #include "callback_table.h"
-#include "util/exception.h"
-#include "util/logger.h"
 
-#define PUBLIC_API __attribute__((visibility("default")))
-
-#define API_METHOD_PREFIX try {
-#define API_METHOD_SUFFIX_NRET                                                                     \
-  }                                                                                                \
-  catch (const std::exception& e) {                                                                \
-    ERR_LOGGING(__FUNCTION__ << "(), " << e.what());                                               \
-  }
-
-#define API_METHOD_CATCH(X)                                                                        \
-  }                                                                                                \
-  catch (const std::exception& e) {                                                                \
-    ERR_LOGGING(__FUNCTION__ << "(), " << e.what());                                               \
-    return X;                                                                                      \
-  }                                                                                                \
-  assert(false && "should not reach here");
-
-////////////////////////////////////////////////////////////////////////////////
-// Library errors enumeration
-typedef enum {
-  ROCTX_STATUS_SUCCESS = 0,
-  ROCTX_STATUS_ERROR = 1,
-} roctx_status_t;
-
-///////////////////////////////////////////////////////////////////////////////////////////////////
-// Library implementation
-//
 namespace {
 
 roctracer::CallbackTable<ACTIVITY_DOMAIN_ROCTX, ROCTX_API_ID_NUMBER> callbacks;
-thread_local int range_level(0);
+thread_local int nested_range_level(0);
 
 }  // namespace
 
-// Logger instantiation
-roctracer::util::Logger::mutex_t roctracer::util::Logger::mutex_;
-std::atomic<roctracer::util::Logger*> roctracer::util::Logger::instance_{};
+uint32_t ROCTX_API roctx_version_major() { return ROCTX_VERSION_MAJOR; }
+uint32_t ROCTX_API roctx_version_minor() { return ROCTX_VERSION_MINOR; }
 
-///////////////////////////////////////////////////////////////////////////////////////////////////
-// Public library methods
-//
-
-PUBLIC_API uint32_t roctx_version_major() { return ROCTX_VERSION_MAJOR; }
-PUBLIC_API uint32_t roctx_version_minor() { return ROCTX_VERSION_MINOR; }
-
-PUBLIC_API void roctxMarkA(const char* message) {
-  API_METHOD_PREFIX
+void ROCTX_API roctxMarkA(const char* message) {
   roctx_api_data_t api_data{};
   api_data.args.roctxMarkA.message = message;
   callbacks.Invoke(ROCTX_API_ID_roctxMarkA, &api_data);
-  API_METHOD_SUFFIX_NRET
 }
 
-PUBLIC_API int roctxRangePushA(const char* message) {
-  API_METHOD_PREFIX
+int ROCTX_API roctxRangePushA(const char* message) {
   roctx_api_data_t api_data{};
   api_data.args.roctxRangePushA.message = message;
   callbacks.Invoke(ROCTX_API_ID_roctxRangePushA, &api_data);
 
-  return range_level++;
-  API_METHOD_CATCH(-1);
+  return nested_range_level++;
 }
 
-PUBLIC_API int roctxRangePop() {
-  API_METHOD_PREFIX
-
+int ROCTX_API roctxRangePop() {
   roctx_api_data_t api_data{};
   callbacks.Invoke(ROCTX_API_ID_roctxRangePop, &api_data);
 
-  if (range_level == 0) EXC_RAISING(ROCTX_STATUS_ERROR, "Pop from empty stack!");
-  return --range_level;
-  API_METHOD_CATCH(-1)
+  if (nested_range_level == 0) return -1;
+  return --nested_range_level;
 }
 
-PUBLIC_API roctx_range_id_t roctxRangeStartA(const char* message) {
-  API_METHOD_PREFIX
-  static std::atomic<roctx_range_id_t> roctx_range_counter(1);
+roctx_range_id_t ROCTX_API roctxRangeStartA(const char* message) {
+  static std::atomic<roctx_range_id_t> start_stop_range_id(1);
 
   roctx_api_data_t api_data{};
   api_data.args.roctxRangeStartA.message = message;
   callbacks.Invoke(ROCTX_API_ID_roctxRangeStartA, &api_data);
 
-  return roctx_range_counter++;
-  API_METHOD_CATCH(-1)
+  return start_stop_range_id++;
 }
 
-PUBLIC_API void roctxRangeStop(roctx_range_id_t rangeId) {
-  API_METHOD_PREFIX
+void ROCTX_API roctxRangeStop(roctx_range_id_t rangeId) {
   roctx_api_data_t api_data{};
   api_data.args.roctxRangeStop.id = rangeId;
   callbacks.Invoke(ROCTX_API_ID_roctxRangeStop, &api_data);
-  API_METHOD_SUFFIX_NRET
 }
 
-extern "C" PUBLIC_API bool RegisterApiCallback(uint32_t op, void* callback, void* arg) {
+extern "C" bool ROCTX_EXPORT RegisterApiCallback(uint32_t op, void* callback, void* arg) {
   if (op >= ROCTX_API_ID_NUMBER) return false;
   callbacks.Set(op, reinterpret_cast<activity_rtapi_callback_t>(callback), arg);
   return true;
 }
 
-extern "C" PUBLIC_API bool RemoveApiCallback(uint32_t op) {
+extern "C" bool ROCTX_EXPORT RemoveApiCallback(uint32_t op) {
   if (op >= ROCTX_API_ID_NUMBER) return false;
   callbacks.Set(op, nullptr, nullptr);
   return true;