File indexing completed on 2024-04-28 15:53:57
0001 #!/usr/bin/env python2.7 0002 # -*- coding: utf-8 -*- 0003 """:synopsis: Interface to the cycle-detecting garbage collector. 0004 """ 0005 """ 0006 A list of objects which the collector found to be unreachable but could not be 0007 freed (uncollectable objects). By default, this list contains only objects with 0008 :meth:`__del__` methods. [#]_ Objects that have :meth:`__del__` methods and are 0009 part of a reference cycle cause the entire reference cycle to be uncollectable, 0010 including objects not necessarily in the cycle but reachable only from it. 0011 Python doesn't collect such cycles automatically because, in general, it isn't 0012 possible for Python to guess a safe order in which to run the :meth:`__del__` 0013 methods. If you know a safe order, you can force the issue by examining the 0014 *garbage* list, and explicitly breaking cycles due to your objects within the 0015 list. Note that these objects are kept alive even so by virtue of being in the 0016 *garbage* list, so they should be removed from *garbage* too. For example, 0017 after breaking cycles, do ``del gc.garbage[:]`` to empty the list. It's 0018 generally better to avoid the issue by not creating cycles containing objects 0019 with :meth:`__del__` methods, and *garbage* can be examined in that case to 0020 verify that no such cycles are being created. 0021 0022 If :const:`DEBUG_SAVEALL` is set, then all unreachable objects will be added to 0023 this list rather than freed. 0024 0025 The following constants are provided for use with :func:`set_debug`: 0026 0027 0028 """ 0029 garbage = None 0030 """ 0031 Print statistics during collection. This information can be useful when tuning 0032 the collection frequency. 0033 0034 0035 """ 0036 DEBUG_STATS = None 0037 """ 0038 Print information on collectable objects found. 0039 0040 0041 """ 0042 DEBUG_COLLECTABLE = None 0043 """ 0044 Print information of uncollectable objects found (objects which are not 0045 reachable but cannot be freed by the collector). These objects will be added to 0046 the ``garbage`` list. 0047 0048 0049 """ 0050 DEBUG_UNCOLLECTABLE = None 0051 """ 0052 When :const:`DEBUG_COLLECTABLE` or :const:`DEBUG_UNCOLLECTABLE` is set, print 0053 information about instance objects found. 0054 0055 0056 """ 0057 DEBUG_INSTANCES = None 0058 """ 0059 When :const:`DEBUG_COLLECTABLE` or :const:`DEBUG_UNCOLLECTABLE` is set, print 0060 information about objects other than instance objects found. 0061 0062 0063 """ 0064 DEBUG_OBJECTS = None 0065 """ 0066 When set, all unreachable objects found will be appended to *garbage* rather 0067 than being freed. This can be useful for debugging a leaking program. 0068 0069 0070 """ 0071 DEBUG_SAVEALL = None 0072 """ 0073 The debugging flags necessary for the collector to print information about a 0074 leaking program (equal to ``DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE | 0075 DEBUG_INSTANCES | DEBUG_OBJECTS | DEBUG_SAVEALL``). 0076 0077 """ 0078 DEBUG_LEAK = None 0079 def enable(): 0080 """ 0081 Enable automatic garbage collection. 0082 0083 0084 """ 0085 pass 0086 0087 def disable(): 0088 """ 0089 Disable automatic garbage collection. 0090 0091 0092 """ 0093 pass 0094 0095 def isenabled(): 0096 """ 0097 Returns true if automatic collection is enabled. 0098 0099 0100 """ 0101 pass 0102 0103 def collect(generation): 0104 """ 0105 With no arguments, run a full collection. The optional argument *generation* 0106 may be an integer specifying which generation to collect (from 0 to 2). A 0107 :exc:`ValueError` is raised if the generation number is invalid. The number of 0108 unreachable objects found is returned. 0109 0110 """ 0111 pass 0112 0113 def set_debug(flags): 0114 """ 0115 Set the garbage collection debugging flags. Debugging information will be 0116 written to ``sys.stderr``. See below for a list of debugging flags which can be 0117 combined using bit operations to control debugging. 0118 0119 0120 """ 0121 pass 0122 0123 def get_debug(): 0124 """ 0125 Return the debugging flags currently set. 0126 0127 0128 """ 0129 pass 0130 0131 def get_objects(): 0132 """ 0133 Returns a list of all objects tracked by the collector, excluding the list 0134 returned. 0135 0136 """ 0137 pass 0138 0139 def set_threshold(threshold0,threshold1,threshold2): 0140 """ 0141 Set the garbage collection thresholds (the collection frequency). Setting 0142 *threshold0* to zero disables collection. 0143 0144 The GC classifies objects into three generations depending on how many 0145 collection sweeps they have survived. New objects are placed in the youngest 0146 generation (generation ``0``). If an object survives a collection it is moved 0147 into the next older generation. Since generation ``2`` is the oldest 0148 generation, objects in that generation remain there after a collection. In 0149 order to decide when to run, the collector keeps track of the number object 0150 allocations and deallocations since the last collection. When the number of 0151 allocations minus the number of deallocations exceeds *threshold0*, collection 0152 starts. Initially only generation ``0`` is examined. If generation ``0`` has 0153 been examined more than *threshold1* times since generation ``1`` has been 0154 examined, then generation ``1`` is examined as well. Similarly, *threshold2* 0155 controls the number of collections of generation ``1`` before collecting 0156 generation ``2``. 0157 0158 0159 """ 0160 pass 0161 0162 def get_count(): 0163 """ 0164 Return the current collection counts as a tuple of ``(count0, count1, 0165 count2)``. 0166 0167 """ 0168 pass 0169 0170 def get_threshold(): 0171 """ 0172 Return the current collection thresholds as a tuple of ``(threshold0, 0173 threshold1, threshold2)``. 0174 0175 0176 """ 0177 pass 0178 0179 def get_referrers(objs): 0180 """ 0181 Return the list of objects that directly refer to any of objs. This function 0182 will only locate those containers which support garbage collection; extension 0183 types which do refer to other objects but do not support garbage collection will 0184 not be found. 0185 0186 Note that objects which have already been dereferenced, but which live in cycles 0187 and have not yet been collected by the garbage collector can be listed among the 0188 resulting referrers. To get only currently live objects, call :func:`collect` 0189 before calling :func:`get_referrers`. 0190 0191 Care must be taken when using objects returned by :func:`get_referrers` because 0192 some of them could still be under construction and hence in a temporarily 0193 invalid state. Avoid using :func:`get_referrers` for any purpose other than 0194 debugging. 0195 0196 """ 0197 pass 0198 0199 def get_referents(objs): 0200 """ 0201 Return a list of objects directly referred to by any of the arguments. The 0202 referents returned are those objects visited by the arguments' C-level 0203 :attr:`tp_traverse` methods (if any), and may not be all objects actually 0204 directly reachable. :attr:`tp_traverse` methods are supported only by objects 0205 that support garbage collection, and are only required to visit objects that may 0206 be involved in a cycle. So, for example, if an integer is directly reachable 0207 from an argument, that integer object may or may not appear in the result list. 0208 0209 """ 0210 pass 0211 0212 def is_tracked(obj): 0213 """ 0214 Returns True if the object is currently tracked by the garbage collector, 0215 False otherwise. As a general rule, instances of atomic types aren't 0216 tracked and instances of non-atomic types (containers, user-defined 0217 objectsmore) are. However, some type-specific optimizations can be present 0218 in order to suppress the garbage collector footprint of simple instances 0219 (e.g. dicts containing only atomic keys and values):: 0220 0221 >>> gc.is_tracked(0) 0222 False 0223 >>> gc.is_tracked("a") 0224 False 0225 >>> gc.is_tracked([]) 0226 True 0227 >>> gc.is_tracked({}) 0228 False 0229 >>> gc.is_tracked({"a": 1}) 0230 False 0231 >>> gc.is_tracked({"a": []}) 0232 True 0233 0234 """ 0235 pass 0236