Please note:The SCons wiki is now restored from the attack in March 2013. All old passwords have been invalidated. Please reset your password if you have an account. If you note missing pages, please report them to Also, new account creation is currently disabled due to an ongoing spam flood (2013/08/27).

Memory Reduction War Stories

Episode 2: Breaking Reference Cycles

Garbage occurs if objects refer too each other in a circular fashion. Such reference cycles cannot be freed automatically and must be collected by the garbage collector. While it is sometimes hard to avoid creating reference cycles, preventing such cycles saves garbage collection time and limits the lifetime of objects.

Anyway, is that a problem in SCons? Let's see how much garbage is produced building a simple "Hello World program".


   1 env = Environment()
   2 SConscript('src/SConscript', exports='env')


   1 Import('env')
   2 env.Program('hello.c', CPPPATH='.')

The garbage can be measured with the garbage debug flag which turns off the garbage collector and prints the garbage that would have been collected. To reduce the noise, the output can be redirected to a file which can be used to build reference graphs to illustrate the cycles graphically.

> $SCONS --debug=garbage --garbage=leak.txt
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
gcc -o src/hello.o -c -Isrc src/hello.c
gcc -o src/hello src/hello.o
scons: done building targets.
Garbage reference graph saved to: leak.txt
Garbage:      893 collected objects (   403 in cycles):    562.06 KB

If graphviz is installed, a PDF can be generated with the following commands:

dot -o leak.txt
dot -Tps -o leak.eps
epstopdf leak.eps

What can be seen are a number of small cycles involving only three or four objects and a few very big cycles.

Patch 1: Don't refer to your own stack frame

The big cycles are connected by a hierarchy of interconnected frame objects. After some digging through the SCons source code I found a number of spots where stack-frames are extracted to deal with exceptions or get access to variables stored in the frame of one of the calling functions. The culprit is a local reference to the own stack-frame which creates a cycle: The local variables are stored in the frame. If the frame is referred by one of the variables a cycle has been created.

Once the problem was found, it was quite easy to fix. As information is searched in one of the prior frames, one can start with the parent frame to prevent the cycle creation. The attached patch solves this problem: leak_frame.patch

Another clean build with the patched version reveals the effect:

Garbage:      564 collected objects (   185 in cycles):    255.60 KB

Patch 2: Weak Methods and Weak Proxies

The remaining cycles all involve bound methods as depicted.


The pattern in the code looks like the following:

   1 class Foo:
   2   def __init__(self, variant):
   3     if variant == 'Alice':
   4       self.method = self.alice
   5     elif variant == 'Bob':
   6       self.method = self.bob
   7   def alice(self):
   8     pass
   9   def bob(self):
  10     pass

What can be done is to use weak methods to refer to the bound methods. This is safe because the method is referenced by the instance it is attached to. If the method refers back (with im_self) a cycle is created. However, the cycle can be avoided if the method only holds a weak reference to the object: leak_weakmethod.patch

Compiling again we are told that building our hello world example, no garbage is produced at all!

Garbage:        0 collected objects (     0 in cycles):      0     B

There is one problem with this approach, though. Calling a weak method is slower than calling a bound method:

   1 import weakref
   3 class WeakMethod(object):
   4     __slots__ = ('f', 'c')
   5     def __init__( self , f ) :
   6         self.f = f.im_func
   7         self.c = weakref.ref( f.im_self )
   8     def __call__( self , *arg ) :
   9         try:
  10             return self.f(self.c(), *arg)
  11         except AttributeError:
  12             raise TypeError, 'Method called on dead object'
  14 class A:
  15     def __init__(self, variant):
  16         if variant:
  17             self.h = self.f
  18         else:
  19             self.h = self.g
  20     def f(self):
  21         pass
  22     def g(self):
  23         pass
  25 class B:
  26     def __init__(self, variant):
  27         if variant:
  28             self.h = WeakMethod(self.f)
  29         else:
  30             self.h = WeakMethod(self.g)
  31     def f(self):
  32         pass
  33     def g(self):
  34         pass
  37 import timeit
  38 t = timeit.Timer('a.h()', 'from __main__ import A \na = A(1)')
  39 print "%.3f usec/call" % (1000000 * t.timeit(1000000) / 1000000)
  40 t = timeit.Timer('a.h()', 'from __main__ import B \na = B(1)')
  41 print "%.3f usec/call" % (1000000 * t.timeit(1000000) / 1000000)

0.378 usec/call (Bound Method invocation)
1.429 usec/call (Weak Method invocation)

For real-life use cases, the difference is small but measurable. An up-to-date check of Ardour takes around 43s without and 46s with the weak method patch applied.

LudwigHaehne/ReferenceCycles (last edited 2008-07-11 18:33:10 by LudwigHaehne)