xref: /commonlibrary/c_utils/base/include/refbase.h

30   * memory resources correctly when an object's life time expires.
58  * of references to the corresponding RefBase object and one kind
59  * of references to the RefCounter object itself.
61  * There are two different references for a single object.\n
62  * A strong reference holds the reference directly pointing to the object,
63  * and the object should be alive as long as the strong reference exists.\n
64  * A weak reference holds a reference indirectly pointing to the object,
65  * and the object is not always alive/existent
74      * RefBase object.
91      * the corresponding RefBase object.
101      * @brief Gets the count of references to the RefCounter object.
103      * @return Count of references to the RefCounter object.
108      * @brief Increments the count of references to the RefCounter object by 1.
113      * @brief Decrements the count of references to the RefCounter object by 1.
116      * `delete this` will be called to deallocate this RefCounter object.
130      * corresponding RefBase object by 1.
138      * corresponding RefBase object by 1.
148      * corresponding RefBase object.
156      * corresponding RefBase object by 1.
164      * corresponding RefBase object by 1.
168      * corresponding RefBase object with no strong reference ever,
169      * or the RefBase object with 0 strong reference but an extended
176      * corresponding RefBase object.
207      * corresponding RefBase object by 1.
218      * the corresponding RefBase object by 1 (simplified).
226      * @brief Checks if the corresponding RefBase object
234      * @brief Extends the life-time of corresponding RefBase object.
236      * This allows the corresponding object keep alive
238      * @note The RefBase object will be deallocated
268     RefPtrCallback callback_ = nullptr; // Callback function to deallocate the corresponding RefBase object
293  * to the correspond RefBase object.
295  * A WeakRefCounter object can be shared by multiple wptr objects.\n
296  * It holds the references to the corresponding RefBase and RefCounter object.
298  * target and its RefCounter object are deallocated. The WeakRefCounter
299  * object can remain alive even if the referenced target is deallocated.
304      * @brief Constructs a WeakRefCounter object.
306      * @param counter Pointer to corresponding RefCounter object.
307      * @param cookie Pointer to corresponding RefBase object.
314      * @brief Gets the current pointer to the corresponding RefBase object.
316      * @return A void pointer to the RefBase object.
317      * If the corresponding object is not alive, a `nullptr` will be returned.
324      * @brief Increments the count of references to this WeakRefCounter object.
328      * referenced to this WeakRefCount object.
334      * @brief Decrements the count of references to this WeakRefCounter object.
336      * @note This WeakRefCounter object will be deallocated when this count
342      * @brief Gets the count recorded by this WeakRefCounter object.
344      * @return Count recorded by this WeakRefCounter object.
352      * the corresponding RefBase object (to promote a wptr to a sptr).
360                                   // WeakRefCounter object
362                                   // that references this WeakRefCounter object.
363     RefCounter *refCounter_ = nullptr; // Reference to the RefCounter object of
364                                        // the corresponding RefBase object
365     void *cookie_ = nullptr; // Pointer to the corresponding RefBase object
382      * @note This function constructs a new RefCounter object
383      * and binds it to the RefBase object.
390      * @note This function unbinds this RefBase object from the
391      * original RefCounter object, and then binds it to the
392      * newly constructed RefCounter object.
404      * @note This function binds this RefBase object with the RefCounter
405      * object of the argument `other`, which will unbind the
406      * RefCounter object. No counts operation will be processed.
413      * @brief Callback function to deallocate this object.
416      * this RefBase object by simply calling `delete(this)`.
421      * @brief Extends the life time of the RefBase object.
423      * @note The object whose life time has been extended will not be
443      * If the life time is not extended, this object will be deallocated
454      * corresponding RefCounter object does not exist.
456      * object exists.
461     * @brief Creates a weak reference to this RefBase object.
463     * @param cookie Void pointer to this RefBase object.
464     * @return Pointer to the newly created WeakRefCounter object.
471      * @brief Gets the pointer to corresponding counter object.
473      * @return Pointer to the counter object.
481      * object exists.
489      * object exists.
497      * RefCounter object does not exist.
551      * or the corresponding RefCounter object does not exist.
556      * @brief Checks if the life time of this RefBase object has been extended.
558      * @return `true` if the life time of this RefBase object has been extended;
559      * `false` if the RefBase object has a normal life time or the corresponding
560      * RefCounter object does not exist.
593      * @brief Enables tracking of the RefBase object. This function will
604                                  // counter of this RefBase object
612  * @brief Strong reference smart pointer to a RefBase object
613  * (or an object of its subclass).
615  * It directly reference the RefBase object.
630      * @brief Create a new object with class type (T) and provide a new sptr to manage it.
632      * @note We strongly recommend using `sptr::MakeSptr` to create a object and manage it.
633      * This approach avoids object pointer leaks, which can avoid many potential memory problems.
635      * @return A sptr which manage a new object with class type (T).
636      * @param args Constructor parameters of the new object to be managed by sptr.
642      * @brief Constructor with the specified object to be managed.
643      * And We do not recommend using this interface to create an sptr object.
654      * @param other Input sptr object.
662      * @param other Input sptr object.
669      * @param other Input sptr object.
670      * @note The original strong reference in target sptr object will
679      * @param other Input sptr object.
687      * @param p WeakRefCounter object which hold the reference to the
688      * managed object.
694      * @brief Gets the pointer to the managed object.
704      * @brief Sets the pointer to the managed object.
706      * @param other Another pointer object to be managed by sptr.
713      * @brief Removes the reference to the managed object held by current sptr.
722      * @return Raw pointer to the managed object.
723      * @note The sptr object will not be converted. Only the member raw
734      * @return `true` if refbase object is not a "null ptr"; `false` otherwise.
744      * This function will return the object managed by this sptr.
746      * @return Reference to the specific object managed by sptr.
756      * This function will return the specified member of the object
765      * @brief Copy assignment operator with the specified object to be managed.
766      * And We do not recommend using this interface to create an sptr object.
770      * input object will be established.
771      * @param other Another object to be managed by this sptr.
779      * @note The original reference will be removed, and the same object
780      * with the input sptr object will be managed by this sptr.
781      * @param other Another sptr object with the same managed class type (T).
789      * @note The original reference will be removed, and the same object
790      * with the input wptr object will be managed by this sptr.
792      * @param other Another wptr object with the same managed class type (T).
800      * @note The original reference will be removed, and the same object
801      * with the input sptr object will be managed by this sptr.
802      * @note This sptr will interpret the managed object as the type (T).
803      * @param other Another sptr object with a different managed class type (O).
812      * @return `true` if the sptr points to the same object with input
821      * @return `true` if the sptr does not point to the same object
833      * @return `true` if the same object is managed by the sptr and wptr;
854      * @return `true` if the same object is managed by two sptrs;
872     T *refs_ = nullptr; // Raw pointer to the specific managed object
1053  * @brief Weak reference smart pointer to a RefBase object
1054  * (or an object of its subclass).
1056  * A weak reference indirectly references the RefBase object
1057  * and directly references the WeakRefCounter object.
1071      * @brief Constructor with the specified object to be managed.
1073      * This function will create WeakRefCounter object for `other`
1076      * @note A WeakRefCounter object will not be created if `other`
1086      * This function will share the WeakRefCounter object of `other` with this
1096      * This function will create a WeakRefCounter object for the managed
1097      * object of `other`, and set the count of weak references properly.
1128      * @brief Copy assignment operator with the specified object to be managed.
1130      * @note The current wptr will unbind the original WeakRefCounter object,
1131      * create a new WeakRefCounter object, and then set the count of weak
1133      * @param other Another object to be managed by this wptr.
1138      * @brief Copy assignment operator with the specified object to be managed.
1143      * @param other Another object to be managed by this wptr.
1153      * @note The current wptr will unbind the original WeakRefCounter object,
1154      * share the WeakRefCounter object with `other`, and then set the count of
1156      * @param other Another wptr object. Objects managed by it will also be
1165      * @note The current wptr will unbind the original WeakRefCounter object,
1166      * create a new WeakRefCounter object, and then set the count of weak
1168      * @param other A sptr object. Objects managed by it will also be
1179      * @param other An wptr object. Objects managed by it will also be
1193      * @param other An sptr object. Objects managed by it will also be
1203      * This function will return the object managed by this wptr.
1205      * @return Specific object managed by wptr.
1215      * This function will return the specified object member managed
1245      * @param other Input reference to a wptr object.
1253      * @param other Input reference to a wptr object.
1262      * @brief Equal-to operator between the wptr and input sptr object.
1264      * @param other Input reference to an sptr object.
1270      * @brief Not-equal-to operator between the wptr and input sptr object.
1272      * @param other Input reference to an sptr object.
1281      * @brief Gets the pointer to the RefBase object.
1283      * @return Raw pointer to the RefBase object.
1284      * @note `nullptr` will be returned if the managed object has been
1290      * @brief Gets the count of weak references in a WeakRefCounter object.
1292      * The value indicates how many wptrs share the same WeakRefCounter object.
1304      * the managed object.
1317      * This function will create an sptr object based on the object
1328     WeakRefCounter *refs_ = nullptr; // Pointer to the corresponding WeakRefCounter object
1421     T *object = reinterpret_cast<T *>(other);
1423     if (object != nullptr) {
1424         newWeakRef = object->CreateWeakRef(object);

Indexes created Thu Nov 07 10:32:03 CST 2024