XPtr.h

Go to the documentation of this file.

//
// XPtr.h: Rcpp R/C++ interface class library -- smart external pointers
//
// Copyright (C) 2009 - 2020  Dirk Eddelbuettel and Romain Francois
// Copyright (C) 2021         Dirk Eddelbuettel, Romain Francois and Iñaki Ucar
//
// This file is part of Rcpp.
//
// Rcpp is free software: you can redistribute it and/or modify it
// under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 2 of the License, or
// (at your option) any later version.
//
// Rcpp is distributed in the hope that it will be useful, but
// WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Rcpp.  If not, see <http://www.gnu.org/licenses/>.
 
#ifndef Rcpp_XPtr_h
#define Rcpp_XPtr_h
 
#include <RcppCommon.h>
 
namespace Rcpp {
 
template <typename T>
void standard_delete_finalizer(T* obj) {                                                                                                // #nocov start
    delete obj;
}
 
template <typename T, void Finalizer(T*) >
void finalizer_wrapper(SEXP p) {
    if (TYPEOF(p) != EXTPTRSXP)
        return;
 
    T* ptr = (T*) R_ExternalPtrAddr(p);
    RCPP_DEBUG_3("finalizer_wrapper<%s>(SEXP p = <%p>). ptr = %p", DEMANGLE(T), p, ptr)
 
    if (ptr == NULL)
        return;
 
    // Clear before finalizing to avoid behavior like access of freed memory
    R_ClearExternalPtr(p);
 
    Finalizer(ptr);
}                                                                                                                                                                               // #nocov end
 
template <
    typename T,
    template <class> class StoragePolicy = PreserveStorage,
    void Finalizer(T*) = standard_delete_finalizer<T>,
    #ifdef RCPP_USE_FINALIZE_ON_EXIT
        bool finalizeOnExit = true
    #else
        bool finalizeOnExit = false
    #endif
>
class XPtr :
    public StoragePolicy< XPtr<T,StoragePolicy, Finalizer, finalizeOnExit> >,
    public SlotProxyPolicy< XPtr<T,StoragePolicy, Finalizer, finalizeOnExit> >,
    public AttributeProxyPolicy< XPtr<T,StoragePolicy, Finalizer, finalizeOnExit> >,
    public TagProxyPolicy< XPtr<T,StoragePolicy, Finalizer, finalizeOnExit> >,
    public ProtectedProxyPolicy< XPtr<T,StoragePolicy, Finalizer, finalizeOnExit> >,
    public RObjectMethods< XPtr<T,StoragePolicy, Finalizer, finalizeOnExit> >
{
public:
 
    typedef StoragePolicy<XPtr> Storage;

    explicit XPtr(SEXP x) { checked_set(x); };

    explicit XPtr(SEXP x, SEXP tag, SEXP prot) {
        checked_set(x);
        R_SetExternalPtrTag(x, tag);
        R_SetExternalPtrProtected(x, prot);
    };

    explicit XPtr(T* p, bool set_delete_finalizer = true,
                  SEXP tag = R_NilValue, SEXP prot = R_NilValue) {
        RCPP_DEBUG_2("XPtr(T* p = <%p>, bool set_delete_finalizer = %s, SEXP tag = R_NilValue, SEXP prot = R_NilValue)", p, (set_delete_finalizer ? "true" : "false"))
        Storage::set__(R_MakeExternalPtr((void*)p , tag, prot));
        if (set_delete_finalizer) {
            setDeleteFinalizer();                                                                                               // #nocov
        }
    }
 
    XPtr(const XPtr& other) {
        Storage::copy__(other);
    }
 
    XPtr& operator=(const XPtr& other) {
        Storage::copy__(other);
        return *this;
    }

    inline T* get() const {
        return (T*)(R_ExternalPtrAddr(Storage::get__()));
    }

    typedef void (*unspecified_bool_type)();
    static void unspecified_bool_true() {}
    operator unspecified_bool_type() const {
        return get() == NULL ? 0 : unspecified_bool_true;
    }
    bool operator!() const {
        return get() == NULL;
    }

    inline T* checked_get() const {
        T* ptr = get();
        if (ptr == NULL)
            throw ::Rcpp::exception("external pointer is not valid");                                                                   // #nocov
        return ptr;
    }

    T& operator*() const {
        return *(checked_get());
    }

    T* operator->() const {
        return checked_get();
    }
 
    void setDeleteFinalizer() {                                                                                                                                                 // #nocov start
        R_RegisterCFinalizerEx(Storage::get__(), finalizer_wrapper<T,Finalizer>,
                               (Rboolean) finalizeOnExit);
    }                                                                                                                                                                                                   // #nocov end

    void release() {
 
        if (get() != NULL) {
            // Call the finalizer -- note that this implies that finalizers
            // need to be ready for a NULL external pointer value (our
            // default C++ finalizer is since delete NULL is a no-op).
            // This clears the external pointer just before calling the finalizer,
            // to avoid interesting behavior with co-dependent finalizers.
            finalizer_wrapper<T,Finalizer>(Storage::get__());
        }
    }
 
    inline operator T*() {
        return checked_get();
    }
 
    void update(SEXP) {}
 
private:
    inline void checked_set(SEXP x) {
        if (TYPEOF(x) != EXTPTRSXP) {
            const char* fmt = "Expecting an external pointer: [type=%s].";                                              // #nocov
            throw ::Rcpp::not_compatible(fmt, Rf_type2char(TYPEOF(x)));                                                 // #nocov
        }
        Storage::set__(x);
    }
 
};
 
} // namespace Rcpp
 
#endif