torsten
77c67c12ca
Entire-Metadata: .entire/metadata/fb87247f-2a75-407e-b336-cbc8c20ba5a6 Entire-Session: fb87247f-2a75-407e-b336-cbc8c20ba5a6 Entire-Strategy: manual-commit
139 lines
4.7 KiB
C
139 lines
4.7 KiB
C
/*
|
|
* (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 */
|