diff options
author | Georg Brandl <georg@python.org> | 2007-08-15 14:27:07 (GMT) |
---|---|---|
committer | Georg Brandl <georg@python.org> | 2007-08-15 14:27:07 (GMT) |
commit | 739c01d47b9118d04e5722333f0e6b4d0c8bdd9e (patch) | |
tree | f82b450d291927fc1758b96d981aa0610947b529 /Doc/lib/libgc.tex | |
parent | 2d1649094402ef393ea2b128ba2c08c3937e6b93 (diff) | |
download | cpython-739c01d47b9118d04e5722333f0e6b4d0c8bdd9e.zip cpython-739c01d47b9118d04e5722333f0e6b4d0c8bdd9e.tar.gz cpython-739c01d47b9118d04e5722333f0e6b4d0c8bdd9e.tar.bz2 |
Delete the LaTeX doc tree.
Diffstat (limited to 'Doc/lib/libgc.tex')
-rw-r--r-- | Doc/lib/libgc.tex | 196 |
1 files changed, 0 insertions, 196 deletions
diff --git a/Doc/lib/libgc.tex b/Doc/lib/libgc.tex deleted file mode 100644 index 0d3408b..0000000 --- a/Doc/lib/libgc.tex +++ /dev/null @@ -1,196 +0,0 @@ -\section{\module{gc} --- - Garbage Collector interface} - -\declaremodule{extension}{gc} -\modulesynopsis{Interface to the cycle-detecting garbage collector.} -\moduleauthor{Neil Schemenauer}{nas@arctrix.com} -\sectionauthor{Neil Schemenauer}{nas@arctrix.com} - -This module provides an interface to the optional garbage collector. It -provides the ability to disable the collector, tune the collection -frequency, and set debugging options. It also provides access to -unreachable objects that the collector found but cannot free. Since the -collector supplements the reference counting already used in Python, you -can disable the collector if you are sure your program does not create -reference cycles. Automatic collection can be disabled by calling -\code{gc.disable()}. To debug a leaking program call -\code{gc.set_debug(gc.DEBUG_LEAK)}. Notice that this includes -\code{gc.DEBUG_SAVEALL}, causing garbage-collected objects to be -saved in gc.garbage for inspection. - -The \module{gc} module provides the following functions: - -\begin{funcdesc}{enable}{} -Enable automatic garbage collection. -\end{funcdesc} - -\begin{funcdesc}{disable}{} -Disable automatic garbage collection. -\end{funcdesc} - -\begin{funcdesc}{isenabled}{} -Returns true if automatic collection is enabled. -\end{funcdesc} - -\begin{funcdesc}{collect}{\optional{generation}} -With no arguments, run a full collection. The optional argument -\var{generation} may be an integer specifying which generation to collect -(from 0 to 2). A \exception{ValueError} is raised if the generation number -is invalid. -The number of unreachable objects found is returned. - -\versionchanged[The optional \var{generation} argument was added]{2.5} -\end{funcdesc} - -\begin{funcdesc}{set_debug}{flags} -Set the garbage collection debugging flags. -Debugging information will be written to \code{sys.stderr}. See below -for a list of debugging flags which can be combined using bit -operations to control debugging. -\end{funcdesc} - -\begin{funcdesc}{get_debug}{} -Return the debugging flags currently set. -\end{funcdesc} - -\begin{funcdesc}{get_objects}{} -Returns a list of all objects tracked by the collector, excluding the -list returned. -\versionadded{2.2} -\end{funcdesc} - -\begin{funcdesc}{set_threshold}{threshold0\optional{, - threshold1\optional{, threshold2}}} -Set the garbage collection thresholds (the collection frequency). -Setting \var{threshold0} to zero disables collection. - -The GC classifies objects into three generations depending on how many -collection sweeps they have survived. New objects are placed in the -youngest generation (generation \code{0}). If an object survives a -collection it is moved into the next older generation. Since -generation \code{2} is the oldest generation, objects in that -generation remain there after a collection. In order to decide when -to run, the collector keeps track of the number object allocations and -deallocations since the last collection. When the number of -allocations minus the number of deallocations exceeds -\var{threshold0}, collection starts. Initially only generation -\code{0} is examined. If generation \code{0} has been examined more -than \var{threshold1} times since generation \code{1} has been -examined, then generation \code{1} is examined as well. Similarly, -\var{threshold2} controls the number of collections of generation -\code{1} before collecting generation \code{2}. -\end{funcdesc} - -\begin{funcdesc}{get_count}{} -Return the current collection counts as a tuple of -\code{(\var{count0}, \var{count1}, \var{count2})}. -\versionadded{2.5} -\end{funcdesc} - -\begin{funcdesc}{get_threshold}{} -Return the current collection thresholds as a tuple of -\code{(\var{threshold0}, \var{threshold1}, \var{threshold2})}. -\end{funcdesc} - -\begin{funcdesc}{get_referrers}{*objs} -Return the list of objects that directly refer to any of objs. This -function will only locate those containers which support garbage -collection; extension types which do refer to other objects but do not -support garbage collection will not be found. - -Note that objects which have already been dereferenced, but which live -in cycles and have not yet been collected by the garbage collector can -be listed among the resulting referrers. To get only currently live -objects, call \function{collect()} before calling -\function{get_referrers()}. - -Care must be taken when using objects returned by -\function{get_referrers()} because some of them could still be under -construction and hence in a temporarily invalid state. Avoid using -\function{get_referrers()} for any purpose other than debugging. - -\versionadded{2.2} -\end{funcdesc} - -\begin{funcdesc}{get_referents}{*objs} -Return a list of objects directly referred to by any of the arguments. -The referents returned are those objects visited by the arguments' -C-level \member{tp_traverse} methods (if any), and may not be all -objects actually directly reachable. \member{tp_traverse} methods -are supported only by objects that support garbage collection, and are -only required to visit objects that may be involved in a cycle. So, -for example, if an integer is directly reachable from an argument, that -integer object may or may not appear in the result list. - -\versionadded{2.3} -\end{funcdesc} - -The following variable is provided for read-only access (you can -mutate its value but should not rebind it): - -\begin{datadesc}{garbage} -A list of objects which the collector found to be unreachable -but could not be freed (uncollectable objects). By default, this list -contains only objects with \method{__del__()} methods.\footnote{Prior to - Python 2.2, the list contained all instance objects in unreachable - cycles, not only those with \method{__del__()} methods.} -Objects that have -\method{__del__()} methods and are part of a reference cycle cause -the entire reference cycle to be uncollectable, including objects -not necessarily in the cycle but reachable only from it. Python doesn't -collect such cycles automatically because, in general, it isn't possible -for Python to guess a safe order in which to run the \method{__del__()} -methods. If you know a safe order, you can force the issue by examining -the \var{garbage} list, and explicitly breaking cycles due to your -objects within the list. Note that these objects are kept alive even -so by virtue of being in the \var{garbage} list, so they should be -removed from \var{garbage} too. For example, after breaking cycles, do -\code{del gc.garbage[:]} to empty the list. It's generally better -to avoid the issue by not creating cycles containing objects with -\method{__del__()} methods, and \var{garbage} can be examined in that -case to verify that no such cycles are being created. - -If \constant{DEBUG_SAVEALL} is set, then all unreachable objects will -be added to this list rather than freed. -\end{datadesc} - - -The following constants are provided for use with -\function{set_debug()}: - -\begin{datadesc}{DEBUG_STATS} -Print statistics during collection. This information can -be useful when tuning the collection frequency. -\end{datadesc} - -\begin{datadesc}{DEBUG_COLLECTABLE} -Print information on collectable objects found. -\end{datadesc} - -\begin{datadesc}{DEBUG_UNCOLLECTABLE} -Print information of uncollectable objects found (objects which are -not reachable but cannot be freed by the collector). These objects -will be added to the \code{garbage} list. -\end{datadesc} - -\begin{datadesc}{DEBUG_INSTANCES} -When \constant{DEBUG_COLLECTABLE} or \constant{DEBUG_UNCOLLECTABLE} is -set, print information about instance objects found. -\end{datadesc} - -\begin{datadesc}{DEBUG_OBJECTS} -When \constant{DEBUG_COLLECTABLE} or \constant{DEBUG_UNCOLLECTABLE} is -set, print information about objects other than instance objects found. -\end{datadesc} - -\begin{datadesc}{DEBUG_SAVEALL} -When set, all unreachable objects found will be appended to -\var{garbage} rather than being freed. This can be useful for debugging -a leaking program. -\end{datadesc} - -\begin{datadesc}{DEBUG_LEAK} -The debugging flags necessary for the collector to print -information about a leaking program (equal to \code{DEBUG_COLLECTABLE | -DEBUG_UNCOLLECTABLE | DEBUG_INSTANCES | DEBUG_OBJECTS | DEBUG_SAVEALL}). -\end{datadesc} |