what does the last argument to SWIG_NewPointerObj mean?

Question

I have a compatibility library that uses SWIG to access a C++ library. I would find it useful to be able to create a SWIG-wrapped Python object inside this layer (as opposed to accepting the C++ object as an argument or returning one). I.e. I want the PyObject* that points to the SWIG-wrapped C++ object.

I discovered that the SWIG_NewPointerObj function does exactly this. The SWIG-generated xx_wrap.cpp file uses this function, but it's also made available in the header emitted by swig -python -external-runtime swigpyrun.h

HOWEVER, I cannot find any reference to what the last argument to this function is. It appears that it specifies the ownership of the object, but there is no documentation that says what each of the options mean (or even what they all are). It appears that the following are acceptable values:

• 0
• SWIG_POINTER_OWN
• SWIG_POINTER_NOSHADOW
• SWIG_POINTER_NEW = OWN + NOSHADOW
• SWIG_POINTER_DISOWN (I'm not sure if SWIG_NewPointerObj accepts this)
• SWIG_POINTER_IMPLICIT_CONV (I'm not sure if SWIG_NewPointerObj accepts this)

I want to create an object that is used only in my wrapping layer. I want to create it out of my own pointer to the C++ object (so I can change the C++ object's value and have it be reflected in the Python object. I need it so it can be passed to a Python callback function. I want to keep this one instance throughout the life of the program so that I don't waste time creating/destroying identical objects for each callback. Which option is appropriate, and what do I Py_INCREF?

Answer 1

When you create new pointer objects with SWIG_NewPointerObj, you may pass the following flags:

SWIG_POINTER_OWN
SWIG_POINTER_NOSHADOW

If SWIG_POINTER_OWN is set, the destructor of the underlying C++ class will be called when the Python pointer is finalized. By default, the destructor will not be called. See Memory Management

For your use case, you don't need to set any flags at all.

From what I can see in the sources, if SWIG_POINTER_NOSHADOW is set, then a basic wrapped pointer is returned. You will not be able to access member variables in Python. All you'll have is an opaque pointer.

Reference: /usr/share/swig/2.0.7/python/pyrun.swg