feat: added base object type

lib/include/cardano/object.h

@@ -0,0 +1,111 @@
+/**
+ * \file object.h
+ *
+ * \author luisd.bianchi
+ * \date   Mar 03, 2024
+ *
+ * \section LICENSE
+ *
+ * Copyright 2024 Biglup Labs
+ *
+ * Licensed 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
+ *
+ *     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.
+ */
+
+#ifndef cardano_object_H
+#define cardano_object_H
+
+/* INCLUDES ******************************************************************/
+
+#include <cardano/error.h>
+#include <cardano/export.h>
+#include <cardano/typedefs.h>
+
+/* DECLARATIONS **************************************************************/
+
+#ifdef __cplusplus
+extern "C" {
+#endif /* __cplusplus */
+
+/**
+ * @brief A pointer to a function that deallocates a Cardano object.
+ *
+ * This typedef defines the signature for deallocator functions used within the Cardano library.
+ * Deallocator functions are responsible for freeing the resources associated with a Cardano object.
+ * The function pointed to by this typedef is expected to handle the deallocation of both the object's
+ * specific resources (if any) and the object itself.
+ *
+ * @param data A pointer to the object to be deallocated. While the parameter is of type `void*` to
+ * allow for generic handling of different object types, it is intended that the actual object passed
+ * to the deallocator function will be a specific type derived from the base `cardano_object_t` structure.
+ * Implementations of the deallocator function should cast `data` to the appropriate specific type
+ * as needed to correctly free its resources.
+ */
+typedef void (*cardano_object_deallocator_t)(void* data);
+
+/**
+ * \brief Base object type.
+ *
+ * All objects in the library are derived from this type.
+ */
+typedef struct cardano_object_t
+{
+    size_t                       ref_count;
+    cardano_object_deallocator_t deallocator;
+} cardano_object_t;
+
+/**
+ * \brief Decrements the object's reference count.
+ *
+ * If the reference count reaches zero, the object memory is deallocated.
+ *
+ * \param object[in] Pointer to the object whose reference count is to be decremented.
+ */
+CARDANO_EXPORT void cardano_object_unref(cardano_object_t** object);
+
+/**
+ * \brief Increments the object's reference count.
+ *
+ * Ensures that the object remains allocated until the last reference is released.
+ *
+ * \param object[in] object whose reference count is to be incremented.
+ */
+CARDANO_EXPORT void cardano_object_ref(cardano_object_t* object);
+
+/**
+ * \brief Retrieves the object's current reference count.
+ *
+ * \warning Does not account for transitive references.
+ *
+ * \param object[in] Target object.
+ * \return Current reference count of the object.
+ */
+CARDANO_EXPORT size_t cardano_object_refcount(const cardano_object_t* object);
+
+/**
+ * \brief Moves a object, decrementing its reference count without deallocating.
+ *
+ * Useful for transferring object ownership to functions that will increase the reference count.
+ *
+ * \warning Memory will leak if the reference count isn't properly managed after a move.
+ *
+ * \param object[in] object to be moved.
+ * \return The object with its reference count decremented.
+ */
+CARDANO_NODISCARD
+CARDANO_EXPORT cardano_object_t* cardano_object_move(cardano_object_t* object);
+
+#ifdef __cplusplus
+}
+#endif /* __cplusplus */
+
+#endif // cardano_object_H

lib/src/object.c

@@ -0,0 +1,94 @@
+/**
+ * \file object.c
+ *
+ * \author angel.castillo
+ * \date   Mar 03, 2024
+ *
+ * \section LICENSE
+ *
+ * Copyright 2024 Biglup Labs
+ *
+ * Licensed 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
+ *
+ *     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.
+ */
+
+/* INCLUDES ******************************************************************/
+
+#include <cardano/object.h>
+
+#include <assert.h>
+#include <stdlib.h>
+
+#include "./config.h"
+
+/* DEFINITIONS ****************************************************************/
+
+void
+cardano_object_unref(cardano_object_t** object)
+{
+  if ((object == NULL) || (*object == NULL))
+  {
+    return;
+  }
+
+  cardano_object_t* reference = *object;
+
+  if (reference->ref_count > 0U)
+  {
+    reference->ref_count -= 1U;
+  }
+
+  if (reference->ref_count == 0U)
+  {
+    assert(reference->deallocator != NULL);
+    reference->deallocator(reference);
+    *object = NULL;
+  }
+}
+
+void
+cardano_object_ref(cardano_object_t* object)
+{
+  if (object == NULL)
+  {
+    return;
+  }
+
+  object->ref_count += 1U;
+}
+
+size_t
+cardano_object_refcount(const cardano_object_t* object)
+{
+  if (object == NULL)
+  {
+    return 0;
+  }
+
+  return object->ref_count;
+}
+
+cardano_object_t*
+cardano_object_move(cardano_object_t* object)
+{
+  if (object == NULL)
+  {
+    return NULL;
+  }
+
+  if (object->ref_count > 0U)
+  {
+    object->ref_count -= 1U;
+  }
+
+  return object;
+}