Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 4be93d0

Browse files
tim-onetim-one
committed
Rearranged and added comments to object.h, to clarify many things
that have taken me "too long" to reverse-engineer over the years. Vastly reduced the nesting level and redundancy of #ifdef-ery. Took a light stab at repairing comments that are no longer true. sys_gettotalrefcount(): Changed to enable under Py_REF_DEBUG. It was enabled under Py_TRACE_REFS, which was much heavier than necessary. sys.gettotalrefcount() is now available in a Py_REF_DEBUG-only build.
1 parent 144dea3 commit 4be93d0

3 files changed

Lines changed: 125 additions & 82 deletions

File tree

‎Include/object.h‎

Lines changed: 120 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,8 @@ the use of objects to ensure they are properly garbage-collected.
1313
Objects are never allocated statically or on the stack; they must be
1414
accessed through special macros and functions only. (Type objects are
1515
exceptions to the first rule; the standard types are represented by
16-
statically initialized type objects.)
16+
statically initialized type objects, although work on type/class unification
17+
for Python 2.2 made it possible to have heap-allocated type objects too).
1718
1819
An object has a 'reference count' that is increased or decreased when a
1920
pointer to the object is copied or deleted; when the reference count
@@ -51,32 +52,76 @@ whose size is determined when the object is allocated.
5152
*/
5253

5354
#ifdef Py_DEBUG
55+
/* Turn on aggregate reference counting. This arranges that extern
56+
* _Py_RefTotal hold a count of all references, the sum of ob_refcnt
57+
* across all objects. The value can be gotten programatically via
58+
* sys.gettotalrefcount() (which exists only if Py_REF_DEBUG is enabled).
59+
* In a debug-mode build, this is where the "8288" comes from in
60+
*
61+
* >>> 23
62+
* 23
63+
* [8288 refs]
64+
* >>>
65+
*
66+
* Note that if this count increases when you're not storing away new objects,
67+
* there's probably a leak. Remember, though, that in interactive mode the
68+
* special name "_" holds a reference to the last result displayed!
69+
*/
70+
#define Py_REF_DEBUG
5471

55-
/* Turn on heavy reference debugging */
72+
/* Turn on heavy reference debugging. This is major surgery. Every PyObject
73+
* grows two more pointers, to maintain a doubly-linked list of all live
74+
* heap-allocated objects (note that, e.g., most builtin type objects are
75+
* not in this list, as they're statically allocated). This list can be
76+
* materialized into a Python list via sys.getobjects() (which exists only
77+
* if Py_TRACE_REFS is enabled). Py_TRACE_REFS implies Py_REF_DEBUG.
78+
*/
5679
#define Py_TRACE_REFS
80+
#endif /* Py_DEBUG */
5781

58-
/* Turn on reference counting */
82+
/* Py_TRACE_REFS implies Py_REF_DEBUG. */
83+
#if defined(Py_TRACE_REFS) && !defined(Py_REF_DEBUG)
5984
#define Py_REF_DEBUG
60-
61-
#endif /* Py_DEBUG */
85+
#endif
6286

6387
#ifdef Py_TRACE_REFS
64-
#define PyObject_HEAD \
65-
struct _object *_ob_next, *_ob_prev; \
66-
int ob_refcnt; \
67-
struct _typeobject *ob_type;
68-
#define PyObject_HEAD_INIT(type) 0, 0, 1, type,
69-
#else /* !Py_TRACE_REFS */
70-
#define PyObject_HEAD \
71-
int ob_refcnt; \
88+
/* Define pointers to support a doubly-linked list of all live heap objects. */
89+
#define _PyObject_HEAD_EXTRA \
90+
struct _object *_ob_next; \
91+
struct _object *_ob_prev;
92+
93+
#define _PyObject_EXTRA_INIT 0, 0,
94+
95+
#else
96+
#define _PyObject_HEAD_EXTRA
97+
#define _PyObject_EXTRA_INIT
98+
#endif
99+
100+
/* PyObject_HEAD defines the initial segment of every PyObject. */
101+
#define PyObject_HEAD \
102+
_PyObject_HEAD_EXTRA \
103+
int ob_refcnt; \
72104
struct _typeobject *ob_type;
73-
#define PyObject_HEAD_INIT(type) 1, type,
74-
#endif /* !Py_TRACE_REFS */
75105

76-
#define PyObject_VAR_HEAD \
77-
PyObject_HEAD \
106+
#define PyObject_HEAD_INIT(type) \
107+
_PyObject_EXTRA_INIT \
108+
1, type,
109+
110+
/* PyObject_VAR_HEAD defines the initial segment of all variable-size
111+
* container objects. These end with a declaration of an array with 1
112+
* element, but enough space is malloc'ed so that the array actually
113+
* has room for ob_size elements. Note that ob_size is an element count,
114+
* not necessarily a byte count.
115+
*/
116+
#define PyObject_VAR_HEAD \
117+
PyObject_HEAD \
78118
int ob_size; /* Number of items in variable part */
79119

120+
/* Nothing is actually declared to be a PyObject, but every pointer to
121+
* a Python object can be cast to a PyObject*. This is inheritance built
122+
* by hand. Similarly every pointer to a variable-size Python object can,
123+
* in addition, be cast to PyVarObject*.
124+
*/
80125
typedef struct _object {
81126
PyObject_HEAD
82127
} PyObject;
@@ -88,13 +133,14 @@ typedef struct {
88133

89134
/*
90135
Type objects contain a string containing the type name (to help somewhat
91-
in debugging), the allocation parameters (see newobj() and newvarobj()),
92-
and methods for accessing objects of the type. Methods are optional,a
136+
in debugging), the allocation parameters (see PyObject_New() and
137+
PyObject_NewVar()),
138+
and methods for accessing objects of the type. Methods are optional, a
93139
nil pointer meaning that particular kind of access is not available for
94140
this type. The Py_DECREF() macro uses the tp_dealloc method without
95141
checking for a nil pointer; it should always be implemented except if
96142
the implementation can guarantee that the reference count will never
97-
reach zero (e.g., for type objects).
143+
reach zero (e.g., for statically allocated type objects).
98144
99145
NB: the methods for certain type groups are now contained in separate
100146
method blocks.
@@ -121,7 +167,7 @@ typedef int (*traverseproc)(PyObject *, visitproc, void *);
121167
typedef struct {
122168
/* For numbers without flag bit Py_TPFLAGS_CHECKTYPES set, all
123169
arguments are guaranteed to be of the object's type (modulo
124-
coercion hacks that is -- i.e. if the type's coercion function
170+
coercion hacks -- i.e. if the type's coercion function
125171
returns other types, then these are allowed as well). Numbers that
126172
have the Py_TPFLAGS_CHECKTYPES flag bit set should check *both*
127173
arguments for proper type and implement the necessary conversions
@@ -378,8 +424,7 @@ extern DL_IMPORT(long) _Py_HashPointer(void*);
378424
#define Py_PRINT_RAW 1 /* No string quotes etc. */
379425

380426
/*
381-
382-
Type flags (tp_flags)
427+
`Type flags (tp_flags)
383428
384429
These flags are used to extend the type structure in a backwards-compatible
385430
fashion. Extensions can use the flags to indicate (and test) when a given
@@ -397,7 +442,6 @@ Type definitions should use Py_TPFLAGS_DEFAULT for their tp_flags value.
397442
398443
Code can use PyType_HasFeature(type_ob, flag_value) to test whether the
399444
given type object has a specified feature.
400-
401445
*/
402446

403447
/* PyBufferProcs contains bf_getcharbuffer */
@@ -458,18 +502,25 @@ given type object has a specified feature.
458502

459503
/*
460504
The macros Py_INCREF(op) and Py_DECREF(op) are used to increment or decrement
461-
reference counts. Py_DECREF calls the object's deallocator function; for
505+
reference counts. Py_DECREF calls the object's deallocator function when
506+
the refcount falls to 0; for
462507
objects that don't contain references to other objects or heap memory
463508
this can be the standard function free(). Both macros can be used
464-
wherever a void expression is allowed. The argument shouldn't be a
465-
NIL pointer. The macro _Py_NewReference(op) is used only to initialize
466-
reference counts to 1; it is defined here for convenience.
509+
wherever a void expression is allowed. The argument must not be a
510+
NIL pointer. If it may be NIL, use Py_XINCREF/Py_XDECREF instead.
511+
The macro _Py_NewReference(op) initialize reference counts to 1, and
512+
in special builds (Py_REF_DEBUG, Py_TRACE_REFS) performs additional
513+
bookkeeping appropriate to the special build.
467514
468515
We assume that the reference count field can never overflow; this can
469-
be proven when the size of the field is the same as the pointer size
470-
but even with a 16-bit reference count field it is pretty unlikely so
471-
we ignore the possibility. (If you are paranoid, make it a long.)
472-
516+
be proven when the size of the field is the same as the pointer size, so
517+
we ignore the possibility. Provided a C int is at least 32 bits (which
518+
is implicitly assumed in many parts of this code), that's enough for
519+
about 2**31 references to an object.
520+
521+
XXX The following became out of date in Python 2.2, but I'm not sure
522+
XXX what the full truth is now. Certainly, heap-allocated type objects
523+
XXX can and should be deallocated.
473524
Type objects should never be deallocated; the type pointer in an object
474525
is not considered to be a reference to the type object, to save
475526
complications in the deallocation function. (This is actually a
@@ -483,62 +534,60 @@ variable first, both of which are slower; and in a multi-threaded
483534
environment the global variable trick is not safe.)
484535
*/
485536

486-
#ifdef Py_TRACE_REFS
487-
#ifndef Py_REF_DEBUG
488-
#define Py_REF_DEBUG
537+
#ifdef Py_REF_DEBUG
538+
extern DL_IMPORT(long) _Py_RefTotal;
539+
#define _PyMAYBE_BUMP_REFTOTAL _Py_RefTotal++
540+
#else
541+
#define _PyMAYBE_BUMP_REFTOTAL (void)0
489542
#endif
543+
544+
#ifdef COUNT_ALLOCS
545+
extern DL_IMPORT(void) inc_count(PyTypeObject *);
546+
#define _PyMAYBE_BUMP_COUNT(OP) inc_count((OP)->ob_type)
547+
#define _PyMAYBE_BUMP_FREECOUNT(OP) (OP)->ob_type->tp_frees++
548+
#else
549+
#define _PyMAYBE_BUMP_COUNT(OP) (void)0
550+
#define _PyMAYBE_BUMP_FREECOUNT(OP) (void)0
490551
#endif
491552

492553
#ifdef Py_TRACE_REFS
493-
extern DL_IMPORT(void) _Py_Dealloc(PyObject *);
554+
/* Py_TRACE_REFS is such major surgery that we call external routines. */
494555
extern DL_IMPORT(void) _Py_NewReference(PyObject *);
495556
extern DL_IMPORT(void) _Py_ForgetReference(PyObject *);
557+
extern DL_IMPORT(void) _Py_Dealloc(PyObject *);
496558
extern DL_IMPORT(void) _Py_PrintReferences(FILE *);
497559
extern DL_IMPORT(void) _Py_ResetReferences(void);
498-
#endif
499-
500-
#ifndef Py_TRACE_REFS
501-
#ifdef COUNT_ALLOCS
502-
#define _Py_Dealloc(op) ((op)->ob_type->tp_frees++, (*(op)->ob_type->tp_dealloc)((PyObject *)(op)))
503-
#define _Py_ForgetReference(op) ((op)->ob_type->tp_frees++)
504-
#else /* !COUNT_ALLOCS */
505-
#define _Py_Dealloc(op) (*(op)->ob_type->tp_dealloc)((PyObject *)(op))
506-
#define _Py_ForgetReference(op) /*empty*/
507-
#endif /* !COUNT_ALLOCS */
508-
#endif /* !Py_TRACE_REFS */
509560

510-
#ifdef COUNT_ALLOCS
511-
extern DL_IMPORT(void) inc_count(PyTypeObject *);
512-
#endif
561+
#else
562+
/* Without Py_TRACE_REFS, there's little enough to do that we expand code
563+
* inline.
564+
*/
565+
#define _Py_NewReference(op) ( \
566+
_PyMAYBE_BUMP_COUNT(op), \
567+
_PyMAYBE_BUMP_REFTOTAL, \
568+
(op)->ob_refcnt = 1)
513569

514-
#ifdef Py_REF_DEBUG
570+
#define _Py_ForgetReference(op) (_PyMAYBE_BUMP_FREECOUNT(op))
515571

516-
extern DL_IMPORT(long) _Py_RefTotal;
572+
#define _Py_Dealloc(op) ( \
573+
_Py_ForgetReference(op), \
574+
(*(op)->ob_type->tp_dealloc)((PyObject *)(op)))
517575

518-
#ifndef Py_TRACE_REFS
519-
#ifdef COUNT_ALLOCS
520-
#define _Py_NewReference(op) (inc_count((op)->ob_type), _Py_RefTotal++, (op)->ob_refcnt = 1)
521-
#else
522-
#define _Py_NewReference(op) (_Py_RefTotal++, (op)->ob_refcnt = 1)
523-
#endif
524576
#endif /* !Py_TRACE_REFS */
525577

526-
#define Py_INCREF(op) (_Py_RefTotal++, (op)->ob_refcnt++)
527-
/* under Py_REF_DEBUG: also log negative ref counts after Py_DECREF() !! */
578+
#define Py_INCREF(op) ( \
579+
_PyMAYBE_BUMP_REFTOTAL, \
580+
(op)->ob_refcnt++)
581+
582+
#ifdef Py_REF_DEBUG
583+
/* under Py_REF_DEBUG: also log negative ref counts after Py_DECREF() !! */
528584
#define Py_DECREF(op) \
529585
if (--_Py_RefTotal, 0 < (--((op)->ob_refcnt))) ; \
530586
else if (0 == (op)->ob_refcnt) _Py_Dealloc( (PyObject*)(op)); \
531-
else ((void)fprintf( stderr, "%s:%i negative ref count %i\n", \
587+
else ((void)fprintf(stderr, "%s:%i negative ref count %i\n", \
532588
__FILE__, __LINE__, (op)->ob_refcnt), abort())
533-
#else /* !Py_REF_DEBUG */
534589

535-
#ifdef COUNT_ALLOCS
536-
#define _Py_NewReference(op) (inc_count((op)->ob_type), (op)->ob_refcnt = 1)
537590
#else
538-
#define _Py_NewReference(op) ((op)->ob_refcnt = 1)
539-
#endif
540-
541-
#define Py_INCREF(op) ((op)->ob_refcnt++)
542591
#define Py_DECREF(op) \
543592
if (--(op)->ob_refcnt != 0) \
544593
; \
@@ -547,7 +596,6 @@ extern DL_IMPORT(long) _Py_RefTotal;
547596
#endif /* !Py_REF_DEBUG */
548597

549598
/* Macros to use in case the object pointer may be NULL: */
550-
551599
#define Py_XINCREF(op) if ((op) == NULL) ; else Py_INCREF(op)
552600
#define Py_XDECREF(op) if ((op) == NULL) ; else Py_DECREF(op)
553601

@@ -557,18 +605,14 @@ where NULL (nil) is not suitable (since NULL often means 'error').
557605
558606
Don't forget to apply Py_INCREF() when returning this value!!!
559607
*/
560-
561608
extern DL_IMPORT(PyObject) _Py_NoneStruct; /* Don't use this directly */
562-
563609
#define Py_None (&_Py_NoneStruct)
564610

565611
/*
566612
Py_NotImplemented is a singleton used to signal that an operation is
567613
not implemented for a given type combination.
568614
*/
569-
570615
extern DL_IMPORT(PyObject) _Py_NotImplementedStruct; /* Don't use this directly */
571-
572616
#define Py_NotImplemented (&_Py_NotImplementedStruct)
573617

574618
/* Rich comparison opcodes */
@@ -624,7 +668,9 @@ is set (see errors.h), and the function result differs: functions that
624668
normally return a pointer return NULL for failure, functions returning
625669
an integer return -1 (which could be a legal return value too!), and
626670
other functions return 0 for success and -1 for failure.
627-
Callers should always check for errors before using the result.
671+
Callers should always check for errors before using the result. If
672+
an error was set, the caller must either explicitly clear it, or pass
673+
the error on to its caller.
628674
629675
Reference Counts
630676
----------------

‎Objects/object.c‎

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1858,9 +1858,7 @@ _Py_NewReference(PyObject *op)
18581858
op->_ob_prev = &refchain;
18591859
refchain._ob_next->_ob_prev = op;
18601860
refchain._ob_next = op;
1861-
#ifdef COUNT_ALLOCS
1862-
inc_count(op->ob_type);
1863-
#endif
1861+
_PyMAYBE_BUMP_COUNT(op);
18641862
}
18651863

18661864
void
@@ -1885,9 +1883,7 @@ _Py_ForgetReference(register PyObject *op)
18851883
op->_ob_next->_ob_prev = op->_ob_prev;
18861884
op->_ob_prev->_ob_next = op->_ob_next;
18871885
op->_ob_next = op->_ob_prev = NULL;
1888-
#ifdef COUNT_ALLOCS
1889-
op->ob_type->tp_frees++;
1890-
#endif
1886+
_PyMAYBE_BUMP_FREECOUNT(op);
18911887
}
18921888

18931889
void

‎Python/sysmodule.c‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -469,11 +469,10 @@ sys_getrefcount(PyObject *self, PyObject *arg)
469469
return PyInt_FromLong(arg->ob_refcnt);
470470
}
471471

472-
#ifdef Py_TRACE_REFS
472+
#ifdef Py_REF_DEBUG
473473
static PyObject *
474474
sys_gettotalrefcount(PyObject *self)
475475
{
476-
extern long _Py_RefTotal;
477476
return PyInt_FromLong(_Py_RefTotal);
478477
}
479478

@@ -564,6 +563,8 @@ static PyMethodDef sys_methods[] = {
564563
#endif
565564
#ifdef Py_TRACE_REFS
566565
{"getobjects", _Py_GetObjects, METH_VARARGS},
566+
#endif
567+
#ifdef Py_REF_DEBUG
567568
{"gettotalrefcount", (PyCFunction)sys_gettotalrefcount, METH_NOARGS},
568569
#endif
569570
{"getrefcount", (PyCFunction)sys_getrefcount, METH_O, getrefcount_doc},

0 commit comments

Comments
 (0)