Add get_referents function. Closes SF patch #402925.

Modules/gcmodule.c

@@ -677,6 +677,53 @@ gc_get_thresh(PyObject *self, PyObject *args)
 	return Py_BuildValue("(iii)", threshold0, threshold1, threshold2);
 }
 
+struct referents{
+	PyObject *objs;
+	int seen;
+};
+
+static int
+referentsvisit(PyObject* obj, struct referents* refs)
+{
+	if (PySequence_Contains (refs->objs, obj)) {
+		refs->seen = 1;
+		return 1;
+	}
+	return 0;
+}
+
+static void
+gc_referents_for(PyObject *objs, PyGC_Head *list, PyObject *resultlist)
+{
+	PyGC_Head *gc;
+	PyObject *obj;
+	traverseproc traverse;
+	struct referents refs = {objs, 0};
+	for (gc = list->gc_next; gc != list; gc = gc->gc_next){
+	  obj = PyObject_FROM_GC(gc);
+		traverse = obj->ob_type->tp_traverse;
+		if (obj == objs || obj == resultlist)
+			continue;
+		if (traverse(obj, (visitproc)referentsvisit, &refs)) {
+			PyList_Append(resultlist, obj);
+			refs.seen = 0;
+		}
+	}
+}
+
+static char gc_get_referents__doc__[]=
+"get_referents(*objs) -> list\n\
+Return the list of objects that directly refer to any of objs.";
+
+static PyObject*
+gc_get_referents(PyObject *self, PyObject* args)
+{
+	PyObject *result = PyList_New(0);
+	gc_referents_for(args, &generation0, result);
+	gc_referents_for(args, &generation1, result);
+	gc_referents_for(args, &generation2, result);
+	return result;
+}
 
 static char gc__doc__ [] =
 "This module provides access to the garbage collector for reference cycles.\n"
@@ -689,6 +736,7 @@ static char gc__doc__ [] =
 "get_debug() -- Get debugging flags.\n"
 "set_threshold() -- Set the collection thresholds.\n"
 "get_threshold() -- Return the current the collection thresholds.\n"
+"get_referents() -- Return the list of objects that refer to an object.\n"
 ;
 
 static PyMethodDef GcMethods[] = {
@@ -700,6 +748,8 @@ static PyMethodDef GcMethods[] = {
 	{"set_threshold",  gc_set_thresh, METH_VARARGS, gc_set_thresh__doc__},
 	{"get_threshold",  gc_get_thresh, METH_VARARGS, gc_get_thresh__doc__},
 	{"collect",	   gc_collect,	  METH_VARARGS, gc_collect__doc__},
+	{"get_referents",  gc_get_referents, METH_VARARGS,
+		gc_get_referents__doc__},
 	{NULL,	NULL}		/* Sentinel */
 };