Module Expr Str ImportFrom alias Import alias Import alias Assign NameStore ListLoad Str Str Str Str FunctionDef arguments args NameParam NameParam defaults NameLoad body Expr Str If UnaryOpNot Call NameLoad NameLoad NameLoad body Raise Call NameLoad BinOpMod Str NameLoad TryExcept body Assign NameStore Call AttributeLoad NameLoad attr NameLoad handlers ExceptHandler type NameLoad body Assign NameStore NameLoad If NameLoad body Assign NameStore Call AttributeLoad NameLoad attr NameLoad orelse Assign NameStore Call AttributeLoad NameLoad attr If NameLoad body Assign NameStore ListComp NameLoad comprehension NameStore NameLoad Call NameLoad NameLoad NameLoad orelse Assign NameStore ListComp NameLoad comprehension NameStore NameLoad CompareIs Call NameLoad NameLoad NameLoad Return NameLoad decorator_list Assign NameStore CompareIn Str AttributeLoad NameLoad attr If NameLoad body Delete NameDel ClassDef bases NameLoad body Expr Str FunctionDef arguments args NameParam NameParam defaults NameLoad body Assign AttributeStore NameLoad attr NameLoad decorator_list FunctionDef arguments args NameParam defaults body Expr Call AttributeLoad NameLoad attr decorator_list FunctionDef arguments args NameParam NameParam NameParam NameParam defaults body Expr Call AttributeLoad NameLoad attr If AttributeLoad NameLoad attr body Expr Call AttributeLoad NameLoad attr decorator_list decorator_list Assign NameStore Call NameLoad Expr Str Assign NameStore Call NameLoad keyword NameLoad Expr Str
N/A N/A The Python Garbage Collector (`GC`_) doesn't usually get too much
attention, probably because:

  - Python's `reference counting`_ effectively handles the vast majority of
    unused objects
  - People are slowly learning to avoid implementing `object.__del__()`_
  - The collection itself strikes a good balance between simplicity and
    power (`tunable generation sizes`_)
  - The collector itself is fast and rarely the cause of long pauses
    associated with GC in other runtimes

Even so, for many applications, the time will come when the developer
will need to track down:

  - Circular references
  - Misbehaving objects (locks, ``__del__()``)
  - Memory leaks
  - Or just ways to shave off a couple percent of execution time

Thanks to the :mod:`gc` module, the GC is a well-instrumented entry
point for exactly these tasks, and ``gcutils`` aims to facilitate it
further.

.. _GC: https://docs.python.org/2/glossary.html#term-garbage-collection
.. _reference counting: https://docs.python.org/2/glossary.html#term-reference-count
.. _object.__del__(): https://docs.python.org/2/glossary.html#term-reference-count
.. _tunable generation sizes: https://docs.python.org/2/library/gc.html#gc.set_threshold
 __future__ print_function N/A gc N/A sys N/A __all__ N/A get_all GCToggler toggle_gc toggle_gc_postcollect get_all N/A N/A type_obj include_subtypes N/A True N/A N/A Get a list containing all instances of a given type.  This will
    work for the vast majority of types out there.

    >>> class Ratking(object): pass
    >>> wiki, hak, sport = Ratking(), Ratking(), Ratking()
    >>> len(get_all(Ratking))
    3

    However, there are some exceptions. For example, ``get_all(bool)``
    returns an empty list because ``True`` and ``False`` are
    themselves built-in and not tracked.

    >>> get_all(bool)
    []

    Still, it's not hard to see how this functionality can be used to
    find all instances of a leaking type and track them down further
    using :func:`gc.get_referrers` and :func:`gc.get_referents`.

    ``get_all()`` is optimized such that getting instances of
    user-created types is quite fast. Setting *include_subtypes* to
    ``False`` will further increase performance in cases where
    instances of subtypes aren't required.

    .. note::

      There are no guarantees about the state of objects returned by
      ``get_all()``, especially in concurrent environments. For
      instance, it is possible for an object to be in the middle of
      executing its ``__init__()`` and be only partially constructed.
     N/A N/A N/A isinstance type_obj type N/A N/A N/A TypeError N/A expected a type, not %r type_obj N/A N/A N/A type_is_tracked N/A N/A gc is_tracked type_obj N/A N/A N/A AttributeError N/A N/A type_is_tracked False N/A type_is_tracked N/A N/A to_check N/A N/A gc get_referrers type_obj N/A N/A to_check N/A N/A gc get_objects N/A include_subtypes N/A N/A ret N/A x N/A x to_check N/A isinstance x type_obj N/A N/A ret N/A x N/A x to_check N/A N/A type x type_obj N/A ret N/A N/A _IS_PYPY N/A __pypy__ N/A sys builtin_module_names N/A _IS_PYPY N/A N/A get_all GCToggler N/A object N/A N/A The ``GCToggler`` is a context-manager that allows one to safely
    take more control of your garbage collection schedule. Anecdotal
    experience says certain object-creation-heavy tasks see speedups
    of around 10% by simply doing one explicit collection at the very
    end, especially if most of the objects will stay resident.

    Two GCTogglers are already present in the ``gcutils`` module:

    - :data:`toggle_gc` simply turns off GC at context entrance, and
      re-enables at exit
    - :data:`toggle_gc_postcollect` does the same, but triggers an
      explicit collection after re-enabling.

    >>> with toggle_gc:
    ...     x = [object() for i in range(1000)]

    Between those two instances, the ``GCToggler`` type probably won't
    be used much directly, but is documented for inheritance purposes.
     __init__ N/A N/A self postcollect N/A False N/A N/A N/A self postcollect postcollect N/A __enter__ N/A N/A self N/A N/A N/A N/A N/A gc disable N/A __exit__ N/A N/A self exc_type exc_val exc_tb N/A N/A N/A N/A N/A gc enable N/A N/A self postcollect N/A N/A N/A N/A gc collect N/A N/A N/A toggle_gc N/A GCToggler N/A A context manager for disabling GC for a code block. See
:class:`GCToggler` for more details. N/A toggle_gc_postcollect N/A GCToggler postcollect True N/A A context manager for disabling GC for a code block, and collecting
before re-enabling. See :class:`GCToggler` for more details.