PY_OpaqueObject.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * COMMENTS:
 *      Instances of this class hold a reference to a Python object.  When this
 *      object is destroyed, the reference count on the Python object will be
 *      decremented.
 *
 *      Unlike PY_AutoObject.h, it is ok to include this header file from other
 *      header files.
 */

#ifndef __PY_OpaqueObject_h__
#define __PY_OpaqueObject_h__

#include "PY_API.h"
#include <stdlib.h>
#include <cstddef>

class PY_PyObject;

class PY_API PY_OpaqueObject
{
public:
    PY_OpaqueObject() noexcept {};
    PY_OpaqueObject(std::nullptr_t) noexcept {};

    /// Construct instances of this class with an opaque PY_PyObject pointer
    /// (which may be null). On destruction, the reference counter will be
    /// decremented. By default, opaque_py_object will have its reference count
    /// incremented on construction. To avoid this, set new_ref=true to signify
    /// that we are being passed ownership of a new object.
    explicit
    PY_OpaqueObject(void *opaque_py_object, bool new_ref = false) noexcept
    {
        reset(opaque_py_object, new_ref);
    }
    ~PY_OpaqueObject()
    {
        reset();
    }

    /// Copy construct/assign
    /// @{
    PY_OpaqueObject(const PY_OpaqueObject &opaque_object) noexcept
    {
        reset(opaque_object.myOpaqueObject, /*new_ref*/false);
    }
    PY_OpaqueObject &operator=(const PY_OpaqueObject &opaque_object) noexcept
    {
        if (this != &opaque_object)
            reset(opaque_object.myOpaqueObject, /*new_ref*/false);
        return *this;
    }
    /// @}

    /// Move construct/assign
    /// @{
    PY_OpaqueObject(PY_OpaqueObject &&opaque_object) noexcept
        : myOpaqueObject(opaque_object.myOpaqueObject)
    {
        opaque_object.myOpaqueObject = nullptr;
    }
    PY_OpaqueObject &operator=(PY_OpaqueObject &&opaque_object) noexcept
    {
        reset(opaque_object.myOpaqueObject, /*new_ref*/true);
        opaque_object.myOpaqueObject = nullptr;
        return *this;
    }
    PY_OpaqueObject &operator=(std::nullptr_t) noexcept
    {
        reset();
        return *this;
    }
    /// @}

    /// Releases ownership and sets to nullptr
    void reset() noexcept;

    /// Release ownerhsip of old ptr and assign a new PY_PyObject.
    /// If !new_ref (aka borrowed), opaque_py_object's refcount is incremented
    void reset(void *opaque_py_object, bool new_ref) noexcept;

    /// Set to the Py_None()
    void resetToNone();

    /// Return a borrowed reference to our opaque PyObject *.  If the caller
    /// will hold a reference to this object after the PY_OpaqueObject has been
    /// deleted, it is up to the caller to increment the reference count.
    void *opaqueObject() const noexcept
    { return myOpaqueObject; }

    /// Releases ownership of the managed object as a void *, and resets.
    void *releaseOpaqueObject() noexcept
    {
        auto ptr = opaqueObject(); 
        myOpaqueObject = nullptr;
        return ptr;
    }

    /// Return a borrowed reference as a PyObject *.
    ///
    /// Using this method requires that the caller includes PY_CPythonAPI.h,
    /// only call this in a .C file to avoid polluting Python header symbols
    /// into rest of the codebase.
    PY_PyObject *pyObject() const noexcept
    { return static_cast<PY_PyObject*>(myOpaqueObject); }

    /// Releases ownership of the managed object as PY_Object *, and resets.
    ///
    /// Using this method requires that the caller includes PY_CPythonAPI.h,
    /// only call this in a .C file to avoid polluting Python header symbols
    /// into rest of the codebase.
    PY_PyObject *releasePyObject() noexcept
    {
        auto ptr = pyObject(); 
        myOpaqueObject = nullptr;
        return ptr;
    }

    /// The comparison operators and equalsOpaqueObject compare using the __eq__
    /// operator.
    /// @{
    bool operator==(const PY_OpaqueObject &opaque_object) const noexcept
    { return equalsOpaqueObject(opaque_object.myOpaqueObject); }
    bool operator!=(const PY_OpaqueObject &opaque_object) const noexcept
    { return !operator==(opaque_object); }
    bool equalsOpaqueObject(void *opaque_py_object) const noexcept;
    /// @}

    /// Return true if *this owns an object (ie. != nullptr)
    explicit operator bool() const noexcept
    { return myOpaqueObject != nullptr; }

    friend bool
    operator==(const PY_OpaqueObject &opaque_object, std::nullptr_t) noexcept
    {
        return opaque_object.myOpaqueObject == nullptr;
    }
    friend bool
    operator==(std::nullptr_t, const PY_OpaqueObject &opaque_object) noexcept
    {
        return opaque_object.myOpaqueObject == nullptr;
    }
    friend bool
    operator!=(const PY_OpaqueObject &opaque_object, std::nullptr_t) noexcept
    {
        return opaque_object.myOpaqueObject != nullptr;
    }
    friend bool
    operator!=(std::nullptr_t, const PY_OpaqueObject &opaque_object) noexcept
    {
        return opaque_object.myOpaqueObject != nullptr;
    }

private:
    void *myOpaqueObject = nullptr;
};

#endif