/*
 * (c) Copyright, Real-Time Innovations, 2025.
 * All rights reserved.
 *
 * No duplications, whole or partial, manual or electronic, may be made
 * without express written permission.  Any such copies, or
 * revisions thereof, must display this notice unaltered.
 * This code contains trade secrets of Real-Time Innovations, Inc.
 */

#ifndef reda_sharedPointer_h
#define reda_sharedPointer_h

#include "osapi/osapi_type.h"
#include "reda/reda_dll.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief A structure that mimics the C++ shared_ptr smart pointer.
 *
 * This structure is used to manage shared ownership of a dynamically allocated
 * object. It ensures that the object is properly deallocated when the last
 * reference to it is destroyed.
 *
 * Here is a basic example of how to use this structure:
 * \code
 *     struct MyObject *obj = MyObject_new();
 *     struct REDASharedPointer *sharedPtr = REDASharedPointer_makeShared(
 *         obj,
 *         MyObject_delete);
 *     CreateThreadThatUsesObject(REDASharedPointer_share(sharedPtr));
 *     REDASharedPointer_release(sharedPtr);
 * \endcode
 * Where the code of CreateThreadThatUsesObject is as follows:
 * \code
 *     void CreateThreadThatUsesObject(struct REDASharedPointer *sharedPtr) {
 *         struct MyObject *obj = REDASharedPointer_get(sharedPtr);
 *         // Use obj
 *         REDASharedPointer_release(sharedPtr);
 *     }
 * \endcode
 */
struct REDASharedPointer;

/**
 * @brief A function pointer prototype for the shared pointer destructor.
 *
 * This function is called when the last thread with a reference to the shared
 * pointer calls REDASharedPointer_release. It is in charge of releasing the
 * memory associated with the object managed by the shared pointer.
 */
typedef void (*REDASharedPointerDataDestructorFnc)(void *data);

/**
 * @brief Create a new REDASharedPointer object associated with a given object.
 *
 * @param[in] ptr The object to be shared.
 * @param[in] destructor A destructor function in charge of releasing the
 * memory associated with ptr. This function will be automatically called
 * when the last thread with a reference to the shared pointer calls
 * REDASharedPointer_release.
 *
 * @return A new REDASharedPointer object. NULL if failure (e.g, out of memory).
 *
 * @see REDASharedPointer_release
 */
extern REDADllExport struct REDASharedPointer *REDASharedPointer_makeShared(
        void *ptr,
        REDASharedPointerDataDestructorFnc destructor);

/**
 * @brief Share ownership of the object referenced by the shared pointer.
 *
 * This function should be called by the thread that intends to share the object
 * with another thread before actually passing the shared pointer reference.
 *
 * @attention If this function is called after the thread has already called
 * REDASharedPointer_release, it will result in undefined behavior.
 *
 * @param[in] self The shared pointer.
 *
 * @return A reference to the shared pointer.
 *
 * @see REDASharedPointer_release
 */
extern REDADllExport struct REDASharedPointer *REDASharedPointer_share(
        struct REDASharedPointer *self);

/**
 * @brief Retrieve the object managed by the shared pointer.
 *
 * @pre The shared pointer reference must be obtained through
 * REDASharedPointer_share or REDASharedPointer_makeShared (for the initial
 * reference).
 *
 * @attention If this function is called after the thread has already called
 * REDASharedPointer_release, it will result in undefined behavior.
 *
 * @param[in] self The shared pointer.
 *
 * @return A pointer to the object managed by the shared pointer.
 */
extern REDADllExport void *REDASharedPointer_get(
        struct REDASharedPointer *self);

/**
 * @brief Release the shared pointer when a thread is done using it.
 *
 * This function should be called by any thread that has a reference to the
 * shared pointer when it is done using the object. This includes both the
 * thread that created the shared pointer using REDASharedPointer_makeShared and
 * any thread that obtained a reference through REDASharedPointer_share.
 *
 * When the last thread with a reference to the shared pointer calls this
 * function, the object managed by the shared pointer and the shared pointer
 * itself will be automatically deleted.
 *
 * @pre The shared pointer must have been obtained through
 * REDASharedPointer_share or REDASharedPointer_makeShared before calling this
 * function.
 *
 * @param[inout] self The shared pointer to release.
 *
 * @see REDASharedPointer_share and REDASharedPointer_makeShared
 */
extern REDADllExport void REDASharedPointer_release(
        struct REDASharedPointer *self);

#ifdef __cplusplus
} /* extern "C" */
#endif

#include "reda/reda_sharedPointer_impl.h"

#endif /* reda_sharedPointer_h */