MSC06-J. Avoid memory leaks

Even though Java supports memory management through garbage collection, there are innumerable possibilities of introducing memory leaks as a result of programming errors. Furthermore, the garbage collector collects only the unreachable objects and not those that are still reachable. The presence of reachable objects that remain unused indicates memory mismanagement.

Depending on program scale and available memory, an OutOfMemoryError may result when the heap space runs out. This usually results in program failure.

Noncompliant Code Example (Off-By-One Programming Error)

This noncompliant code example shows a leaking Vector object. The memory leak quickly exhausts the heap space as the condition for removing the vector element is mistakenly written as n > 0 instead of n >= 0. As a result, in every iteration, the method leaks one vector element.

public class Leak {
  static Vector vector = new Vector();

  public void useVector(int count) { 	
    for (int n = 0; n < count; n++) {
      vector.add(Integer.toString(n));
    }
    // ...
    for (int n = count - 1; n > 0; n--) { // Free the memory
      vector.removeElementAt(n);
    }	
  }

  public static void main(String[] args) throws IOException {
    Leak le = new Leak();
    int i = 1;
    while(true) {
      System.out.println("Iteration: " + i);
      le.useVector(1);
      i++;
    }
  }
}

Compliant Solution (1)

This compliant solution corrects the mistake by changing the loop condition to n >= 0.

public void useVector(int count) { 	
  for (int n = 0; n < count; n++) {
    vector.add(Integer.toString(n));
  }
  // ...
  for (int n = count - 1; n >= 0; n--) {
    vector.removeElementAt(n);
  }
}	

Compliant Solution (2)

Prefer the use of standard language semantics where possible, as shown in this compliant solution.

public void useVector(int count) { 	
  for (int n = 0; n < count; n++) {
    vector.add(Integer.toString(n));
  }
  // ...
  while (!vector.isEmpty()){
    vector.removeElementAt(vector.size() - 1);	        	    
  }
}

Compliant Solution (3)

An alternative way of clearing the vector is to use the vector.clear() method.

public void useVector(int count) { 	
  for (int n = 0; n < count; n++) {
    vector.add(Integer.toString(n));
  }
  // ...
  vector.clear(); // Clear the vector
}

Likewise, if a range of elements have to be removed from the vector, vector.subList(fromIndex, toIndex).clear() can be used. In the context of this compliant solution, the fromIndex and the toIndex can both be 0 as the count variable is 1 on each iteration [[API 2006]].

Noncompliant Code Example (Non-Local Instance Field)

This noncompliant code example creates a HashMap instance field within the class body but uses it only in the doSomething() method.

public class Storer {
  private HashMap<Integer,String> hm = new HashMap<Integer, String>();
  
  private void doSomething() {
    hm.put(1, "java");  // hm is used only here and never referenced again
    // ...
  }
}

It is not obvious that it will continue to persist as long as the class Storer's instance is alive.

Compliant Solution (Reduce Scope of Instance Field)

This compliant solution declares the HashMap within the doSomething() method.

public class Storer {
  private void doSomething() {
    HashMap<Integer,String> hm = new HashMap<Integer,String>();
    hm.put(1,"java");
    // ...
  }
}

Localizing or confining the instance field to a narrower scope gives the garbage collector a better chance of succeeding at collecting the object in a timely manner. Short-lived objects are always collected quickly by generational garbage collectors.

Noncompliant Code Example (Lapsed Listener)

This noncompliant code example demonstrates unintentional object retention and is commonly called the Lapsed Listener. The button continues to hold a reference of the reader object even after completion of the readSomething() method.

public class LapseEvent extends JApplet   {
  JButton button;
  public void init() {
    button = new JButton("Click Me");
    getContentPane().add(button, BorderLayout.CENTER);
    Reader reader = new Reader();
    button.addActionListener(reader);
    try {
      reader.readSomething();
    } catch (IOException e) { 
      // Handle exception 
    }		 
  }
}

class Reader implements ActionListener{
  public void actionPerformed(ActionEvent e)  {
    Toolkit.getDefaultToolkit().beep();
  }
  public void readSomething() throws IOException {
    // Read from file
  }
}

As a result, the garbage collector does not collect the reader object. A similar problem occurs with inner classes as they hold an implicit reference to the outer class.

Noncompliant Code Example (Exception Before Remove)

To resolve this problem, a matching pair of the removeActionListener() should be used, as shown below.

Reader reader = new Reader();
button.addActionListener(reader);
try {
  reader.readSomething();  // Can skip next line
  button.removeActionListener(reader);  // Dereferenced, but control flow can change
} catch (IOException e) { 
  // Forward to handler 
}		 

Unfortunately, this is not the panacea because an exception in the reader.readSomething() method can change the control flow in such a way that the removeActionListener statement is never executed.

Compliant Solution (finally Block)

This compliant solution uses the finally block to ensure that the reader object's reference is unregistered.

Reader reader = new Reader();
button.addActionListener(reader);
try {
  reader.readSomething();
} catch (IOException e) { 
  // Handle exception 
} finally {
  button.removeActionListener(reader);  // Always executed
}

Noncompliant Code Example (Member Object Leaks)

This noncompliant code example implements a stack data structure [[Bloch 2008]]. The main issue is that it does not allow the garbage collector to deallocate memory after the pop operation.

public class Stack {
  private Object[] elements;
  private int size = 0;

  public Stack(int initialCapacity) {
    this.elements = new Object[initialCapacity];
  }

  public void push(Object e) {
    ensureCapacity();
    elements[size++] = e;
  }

  public Object pop() { // This method causes memory leaks
    if (size == 0) {
      throw new EmptyStackException();
    }
    return elements[--size];
  }
  /**
  * Ensure space for at least one more element, roughly
  * doubling the capacity each time the array needs to grow.
  */
  private void ensureCapacity() {
    if (elements.length == size) {
      Object[] oldElements = elements;
      elements = new Object[2 * elements.length + 1];
      System.arraycopy(oldElements, 0, elements, 0, size);
    }
  }
}

The object references are retained even after the element is pop'ed. Such obsolete references are not garbage collected automatically. This can get even more deceitful because none of the objects referenced by the offending object get garbage collected.

Compliant Solution (Assign null to Elements of Data Structures)

This compliant solution assigns null values to all obsolete references.

public Object pop() {
  if (size==0)
    throw new EmptyStackException(); // Ensures object consistency
  Object result = elements[--size];
  elements[size] = null; // Eliminate obsolete reference
  return result;
} 

The garbage collector can include individual element-objects in its list of objects to free. A NullPointerException results on subsequent attempts to access the particular object.

While these examples may not model production scenarios, it is not uncommon to uncover obsolete references when dealing with data structures such as hash tables containing many large-sized records. It is prudent to assign null to array-like custom data structures, however, doing so with individual objects or local variables has no specific advantages. The garbage collector is sufficiently equipped to handle these cases [[Commes 2007]].

Noncompliant Code Example (Strong References)

A common variant of the aforementioned noncompliant code example is the unintentional retention of objects when using a Map or a similar Collections object. In this noncompliant code example, a server maintains temporary metadata about all secure connections it commits to.

class HashMetaData {
  private Map<SSLSocket, InetAddress> m = Collections.synchronizedMap(new HashMap<SSLSocket, InetAddress>());
  public void storeTempConnection(SSLSocket sock, InetAddress ip) {
    m.put(sock, ip);  
  }
  public void removeTempConnection(SSLSocket sock) {
    m.remove(sock);  
  }	
}

Although the metadata is designed to be transient by nature, it persists even after the particular socket is closed, until removeTempConnection() is invoked. Unless some notification logic is installed, it is impossible to determine the best time to eliminate the object reference by calling removeTempConnection(). Moreover, nulling out original objects or referents (Socket connections) proves to be unwieldy.

Compliant Solution (Weak References)

This compliant solution uses weak references to mitigate the issue.

// ...
private Map<SSLSocket, InetAddress> m = Collections.synchronizedMap(new WeakHashMap<SSLSocket, InetAddress>());

Strong references do not allow the garbage collector to reclaim the objects that are stored compositely, such as in a Map. According to the Java API [[API 2006]], weak reference objects: "... do not prevent their referents from being made finalizable, finalized, and then reclaimed."

A referent is the object that is being referred to. As soon as any strong references to the object are found to have phased out, the garbage collector reclaims the referent. With WeakHashMap, the map's key is weakly referred to and as a result determines whether the corresponding referents are ready to be collected. An object becomes eligible for garbage collection when only weak references to the referent exist. A weak reference allows the code to refer to the referent without holding its garbage collection. This approach is only suitable when the lifetime of the object is required to be the same as the lifetime of the key.

It is not enough to facilitate the garbage collection of unneeded objects with weak references. It is critical to prune the data structure so that more entries can be accommodated in the newly created space. This can be achieved by calling the get() method of WeakHashMap and removing the entry that corresponds to the null return value (polling). A more efficient method is to use a reference queue [[Goetz 2005b]].

Compliant Solution (Reference Queue)

Reference queues provide a way to receive notifications when a referent is garbage collected. If the referent is assigned the value null, it is eventually garbage collected. However, the HashMap continues to strongly reference the WeakReference object and the corresponding value (for each entry in the HashMap).

As soon as the GC clears the reference (which referred to the referent), it adds the corresponding WeakReference object to the reference queue. It remains there unless some operation is performed on the queue (such as a put() or remove()). After such an operation, the WeakReference object in the hashmap is also collected. Alternatively, this two-step procedure can be carried out manually by using the following code:

class HashMetaData {
  private Map<WeakReference<SSLSocket>, InetAddress> m = 
    Collections.synchronizedMap(new HashMap<WeakReference<SSLSocket>, InetAddress>());
  ReferenceQueue queue = new ReferenceQueue();
  
  public void storeTempConnection(SSLSocket sock, InetAddress ip) {
    WeakReference<SSLSocket> wr = new WeakReference<SSLSocket>(sock, queue);
    while ((wr = (WeakReference) queue.poll()) != null) { // poll for dead entries before adding more
      m.remove(wr); // Removes the WeakReference object and the value (not the referent)
    }  
    m.put(wr, ip);
  }

  public void removeTempConnection(SSLSocket sock) {
    m.remove(sock);  
  }	
}

Note that the two-argument constructor of WeakReference takes a Queue argument and must be used to perform direct queue processing. Dead entries may be pruned prior to insertion.

Compliant Solution (Soft References)

It is also permissible to use soft references because they guarantee that the referent will be reclaimed before an OutOfMemoryError results but no sooner than the time when memory begins to run out.

class HashMetaData {
  private Map<SoftReference<SSLSocket>, InetAddress> m = 
    Collections.synchronizedMap(new HashMap<SoftReference<SSLSocket>, InetAddress>());
  ReferenceQueue queue = new ReferenceQueue();

  public void storeTempConnection(SSLSocket sock, InetAddress ip) {
    SoftReference<SSLSocket> sr = new SoftReference<SSLSocket>(sock, queue);
    while ((sr = (SoftReference) queue.poll()) != null) {
      m.remove(sr); // Removes the WeakReference object and the value (not the referent)
    }  
    m.put(sr, ip);
  }

  public void removeTempConnection(SSLSocket sock) {
    m.remove(sock);  
  }	
}

Soft references are preferred over weak references for applications such as caching because weak references are garbage collected more aggressively, to the point that they become unsuitable.

Risk Assessment

Memory leaks in Java applications may be exploited to cause denial of service.

Automated Detection

TODO

Related Vulnerabilities

Search for vulnerabilities resulting from the violation of this guideline on the CERT website.

Bibliography

[[API 2006]] Class Vector, Class WeakReference
[[Gupta 2005]]
[[Bloch 2008]] Item 6: Eliminate obsolete object references
[[Commes 2007]] Memory Leak Avoidance
[[Goetz 2005]] Lapsed listeners
[[Goetz 2005b]] "Memory leaks with global Maps" and "Reference queues"
[[MITRE 2009]] CWE ID 401 "Failure to Release Memory Before Removing Last Reference (aka 'Memory Leak')"

[!The CERT Oracle Secure Coding Standard for Java^button_arrow_left.png!]      [!The CERT Oracle Secure Coding Standard for Java^button_arrow_up.png!]      [!The CERT Oracle Secure Coding Standard for Java^button_arrow_right.png!]