interrogate: Support subclassing C++ objects from Python

This change enables persistent Python wrapper objects for Python subclasses of typed, reference counted C++ objects.  That means that these objects will store a reference to `self` on the C++ object, and interrogate will always return that instead of making a new Python wrapper every time it is returned from C++.

Practically, this means that you could subclass eg. PandaNode, Event, Fog, what have you, and store these in the scene graph - the Python data in the subclass will be retained and Panda will return your subclass when you ask for the object back rather than creating a new wrapper object without your original data.

To do this, Interrogate generates a proxy class inheriting from the C++ type with additional room to store a `self` pointer and a TypeHandle (which is returned by an overridden `get_type()`).  This TypeHandle is automatically created by registering the Python subclass with the typing system.  The proxy class is only used when the constructor detects that it's constructing for a subtype, so that regular uses of the C++ type are not affected by this mechanism.

(The registration with the typing system could use some improvement.  There's no regard for namespacing right now, in particular.  Furthermore, we could move the registration to an `__init_subclass__()` method, with parameters to specify an existing TypeHandle or to customize the type name.)

This creates a reference cycle, which must be cleared somehow.  One way this happens is by overriding `unref()` in the proxy, which checks that if the Python and C++ reference counts are both 1, this must be the circular reference, and then it breaks the cycle.  Note that this will _only_ work if all other Python references have been cleared before the last C++ reference goes away.  For the other case, we need to rely on Python's garbage collector, so these classes also implement tp_traverse and tp_clear.

This commit also therefore re-enables Python garbage collector support (ie. defining `__traverse__()`), which was previously disabled due to the problems caused by multiple Python wrappers referring to the same C++ object.  To avoid these problems, Panda will only cooperate with Python's GC if the C++ reference count is 1, in which case we can trivially prove that the last reference must be from the Python wrapper.  Note that this explains why we need persistent wrappers for traversal to work--if there are multiple Python wrappers pointing to the C++ object, and they are all participating in a reference cycle, the reference count cannot be 1, and cycle detection does not work.  By default, the GC is only enabled for Python subclasses, but a class may define `__traverse__()` in order to opt-in, keeping the previous limitation in mind.

There is a second mechanism introduced by this commit: classes may define a public `__self__` member of type `PyObject *` if they want to use persistent objects even if they aren't being subclassed.  This allows these classes to participate in Python's GC and avoid the situation above.

The cycle detection is implemented for PandaNode's Python tags, but this is very incomplete, since the traversal doesn't recurse into children and it won't work if there is more than one wrapper object that is part of a cycle, since PandaNode by default doesn't use persistent wrappers.  This problem may need more attention later.

Fixes panda3d#1410

Author: rdb

dtool/src/interrogate/functionRemap.cxx

@@ -450,8 +450,6 @@ get_call_str(const string &container, const vector_string &pexprs) const {
     _parameters[pn]._remap->pass_parameter(call, get_parameter_expr(pn, pexprs));
 
   } else {
-    const char *separator = "";
-
     // If this function is marked as having an extension function, call that
     // instead.
     if (_extension) {
@@ -488,33 +486,41 @@ get_call_str(const string &container, const vector_string &pexprs) const {
       }
     }
     call << "(";
-
-    if (_flags & F_explicit_self) {
-      // Pass on the PyObject * that we stripped off above.
-      call << separator << "self";
-      separator = ", ";
-    }
-    if (_flags & F_explicit_cls) {
-      call << separator << "cls";
-      separator = ", ";
-    }
-
-    size_t pn;
-    size_t num_parameters = pexprs.size();
-
-    for (pn = _first_true_parameter;
-         pn < num_parameters; ++pn) {
-      nassertd(pn < _parameters.size()) break;
-      call << separator;
-      _parameters[pn]._remap->pass_parameter(call, get_parameter_expr(pn, pexprs));
-      separator = ", ";
-    }
+    write_call_args(call, pexprs);
     call << ")";
   }
 
   return call.str();
 }
 
+/**
+ * Writes the arguments to pass to the function.
+ */
+void FunctionRemap::
+write_call_args(std::ostream &call, const vector_string &pexprs) const {
+  const char *separator = "";
+  if (_flags & F_explicit_self) {
+    // Pass on the PyObject * that we stripped off above.
+    call << separator << "self";
+    separator = ", ";
+  }
+  if (_flags & F_explicit_cls) {
+    call << separator << "cls";
+    separator = ", ";
+  }
+
+  size_t pn;
+  size_t num_parameters = pexprs.size();
+
+  for (pn = _first_true_parameter;
+       pn < num_parameters; ++pn) {
+    nassertd(pn < _parameters.size()) break;
+    call << separator;
+    _parameters[pn]._remap->pass_parameter(call, get_parameter_expr(pn, pexprs));
+    separator = ", ";
+  }
+}
+
 /**
  * Returns the minimum number of arguments that needs to be passed to this
  * function.

dtool/src/interrogate/functionRemap.h

@@ -61,6 +61,7 @@ class FunctionRemap {
   FunctionWrapperIndex make_wrapper_entry(FunctionIndex function_index);
 
   std::string get_call_str(const std::string &container, const vector_string &pexprs) const;
+  void write_call_args(std::ostream &out, const vector_string &pexprs) const;
 
   int get_min_num_args() const;
   int get_max_num_args() const;