Todd Schiller - Checker Framework

Making Wrong Code... Wrong

2014-12-08T00:00:00-05:00

Joel Spolsky has a popular post from 2005 on "Making Wrong Code Look Wrong". In this post, I'll address his suggestion to use Hungarian Notation. It turns out we can now do better: we can make wrong code... wrong!

Hungarian Notation is a naming scheme that conveys information about methods and variables. For example, we might use the prefix "us" to denote variables that hold unsafe values, e.g., user input. This notation makes it easy to notice the SQL injection vulnerability in the following code:

String usUser = getUserInput();
executeSqlQuery("SELECT * FROM users WHERE user='" + usUser + "'");

The problem with Hungarian Notation is that you still have to manually inspect the code. For real projects, manual inspection is insufficient because of overloading, overridding, threading, version control merges, etc. Testing is also insufficient because it can "show the presence of bugs, but never show their absence."

Type Qualifiers

Hungarian Notation typically doesn't convey arbitrary information about a variable/parameter. Rather, the notation describes the set of values an expression may or may not have. In the example above, the "us" prefix tells us that usUser is not just a String, but a potentially unsafe String. The prefix is "qualifying" the variable's type.

Java 8 brought language support for user-defined Type Qualifiers. Instead of using naming schemes, we can now define custom Type Qualifiers that we can use in method signatures:

public void executeSqlQuery(@Safe String query) { ... }
public @Unsafe String getUserInput() { ... }

and method bodies:

@Unsafe String usUser = getUserInput();
executeSqlQuery("SELECT * FROM users WHERE user='" + usUser + "'");

Enforcing Type Qualifiers

Type Qualifiers are easier to read than Hungarian Notation because you don't have to parse (possibly multiple) prefixes and suffixes. In some cases, however, Type Qualifiers are harder to reason about. Using Type Qualifiers, the qualifier is typically only written on declarations. Using Hungarian Notation, the qualifier appears at every occurence of the variable.

Luckily, there are tools that can reason about Type Qualifiers for us, just like the Java compiler reasons about types. One such tool is the Checker Framework. Using the Checker Framework, we can define a checker that issues a warning wherever an @Unsafe expression is used where a @Safe expression is required. It's as simple as telling the Checker Framework that @Safe is a subtype of @Unsafe — a safe value can be used wherever an @Unsafe value is expected, but not vice versa:

@TypeQualifier
@SubtypeOf({})
@DefaultQualifierInHierarchy // By default, expressions are potentially unsafe
@Target({ ElementType.TYPE_USE, ElementType.TYPE_PARAMETER })
public @interface Unsafe {}

@TypeQualifier
@SubtypeOf({ Unsafe.class }) // @Safe is a subtype of @Unsafe
@Target({ ElementType.TYPE_USE, ElementType.TYPE_PARAMETER })
public @interface Safe {}

What makes the Checker Framework particularly effective is its flow-sensitivity. Checkers can reason about the type of a variable throughout the method:

String user = getUserInput();

// WARNING: user is known to be @Unsafe
executeSqlQuery("SELECT * FROM users WHERE user='" + user + "'");

// encode has return type @Safe String
user = encode(user);

// SAFE: user is known to be @Safe
executeSqlQuery("SELECT * FROM users WHERE user='" + user + "'");

In practice, flow-sensitivity means that you rarely have to annotate local variables.

For a more thorough introduction to Type Qualifiers in Java 8, check out my article on InfoQ . Complete instructions for creating your own checker can be found in the Checker Framework documentation.

Enforcing Hungarian Notation

As we've seen, Hungarian Notation and Type Qualifiers are both techniques for qualifying types. Therefore, it should come as no surprise that we can leverage Type Qualifiers and the Checker Framework to automatically enforce Hungarian Notation.

To do so, we just need to have the Checker Framework read names as if we were reasoning about the code ourselves. For our running example, we have the following "type introduction" rule:

If the name of a variable or parameter has the prefix "s", add a @Safe annotation to its type.

We implement the rule by adding logic to the AnnotatedTypeFactory for our checker. The following method adds the @Safe qualifier to local variables:

private Pattern safeRegex = Pattern.compile("s[A-Z_].*");
private AnnotationMirror SAFE = AnnotationUtils.fromClass(elements, Safe.class);

@Override
public Void visitVariable(VariableTree node, AnnotatedTypeMirror type) {
  if (safeRegex.matcher(node.getName()).matches()) {
    type.replaceAnnotation(SAFE);
  }
  return super.visitVariable(node, type);
}

The logic is the same for parameters and fields. You can find a full implementation of the checker on GitHub.

The result is a system that combines the conciceness of Hungarian Notation with the safety of compile-time checking:

// Parameter sQuery is given the @Safe annotation
public void executeSqlQuery(String sQuery){ ... }

// WARNING: sUser is given the @Safe annotation
String sUser = getUserInput();

Summary

This post demonstrated how Type Qualifiers and the Checker Framework can enforce Hungarian Notation at compile-time. Compile-time checking makes wrong code not just look wrong, but actually wrong!

The source code for the checker is available on GitHub at: https://github.com/twschiller/hungarian-checker.

This post was inspired by a talk that Charles Simonyi gave on May 10, 2012 at the University of Washington about the importance of notation.

Enforcing memory allocation patterns with an effect system

2014-11-23T00:00:00-05:00

Writing performant Java software often means controlling allocation patterns to prevent garbage collection. For example, a program for processing financial FIX messages in real-time might use a fixed buffer to avoid allocations altogether.

In many cases, it's easy to determine whether code allocates memory. However, manually verifying allocation patterns becomes more difficult when method calls and method overriding are involved.

This post describes how to build an effect system to automatically enforce allocation patterns. If you've programmed in Java before, you've used an effect system: checked exceptions are an effect system.

Effect Systems

Unlike type systems, which indicate which type(s) an expression may have, effect systems indicate which effect(s) a statement or block may have. For example, the following method has the effect that it may throw a FileNotFoundException:

public void maybeThrow() throws FileNotFoundException { ... }

The method above may throw the exception — or it may not. It's perfectly legal to annotate an empty method as potentially throwing an exception!

The compiler enforces that the caller of a method either: (1) handles the exception with a catch block, or (2) declares that it might also throw the exception (or a supertype of the exception).

Enforcing Allocation Patterns

For enforcing allocation patterns, we'd like to do something similar. The developer should be able to annotate which methods may allocate memory. Fortunately, the ability to define method annotations has existed since Java 1.5:

@MayAlloc
public void mayAlloc(...) { ... }

More interestingly, the developer should be able to annotate which methods should not allocate memory:

@NoAlloc
public void safeMethod(...) { ... }

Based on these annotations, we'd like the compiler to check that no method marked as @NoAlloc ever (1) itself allocates memory, or (2) calls a method that directly or indirectly allocates memory.

To make the compiler perform these checks, we'll use the Checker Framework, a tool for defining custom Java type systems. It's designed to take advantage of the new Type Annotations feature in Java 8. However, to implement a basic allocation effect system, we'll just use method annotations.

The full checker implementation is available on GitHub.

Defining Annotations

First we'll define the annotations @MayAlloc and @NoAlloc that the developer can write on method declarations:

@Target(ElementType.METHOD)
public @interface MayAlloc { }

@Target(ElementType.METHOD)
public @interface NoAlloc { }

Since we're using the Checker Framework, we also have to define a type annotation for the default checker to process. For our checker, we'll just define a type annotation @EffectType that we'll tell the Checker Framework to apply everywhere:

@TypeQualifier
@DefaultQualifierInHierarchy // Apply the annotation automatically
@SubtypeOf({}) // The annotation is not related to anything else
@ImplicitFor(trees = { Tree.Kind.NULL_LITERAL })
@Target({ ElementType.TYPE_USE, ElementType.TYPE_PARAMETER })
public @interface EffectType { }

For some effect systems, it is beneficial to define additional type annotations. See the Checker Framework's GUI Effect Checker as an example.

Creating a Checker

Now that we've defined our annotations, we can define a checker AllocEffect:

@TypeQualifiers({ EffectType.class }) // Don't list the method annotations
public class AllocEffectChecker extends BaseTypeChecker { }

Every checker has two main parts. The Type Factory populates annotations on methods and types. The Visitor checks that the annotations are consistent, and that the code is consistent with the annotations. Using the Checker Framework naming convention, the type factory and visitor for our checker will be called AllocEffectTypeFactory and AllocEffectVisitor, respectively.

The Annotation Factory

The AllocEffectTypeFactory will compute annotations for methods that don't have developer-written annotations. Our factory will follow two rules:

If a method is unannotated, add the @MayAlloc annotation.
If an unannotated method overrides another method, inherit the annotation(s) from the overridden methods. If the developer writes a @MayAlloc annotation on a method overridding a method declared as @NoAlloc, emit a warning.

To enforce the second rule, we'll have the checker compute the range of effects each method can have based on the Java type hierarchy. Computing a range is overkill for an effect system with just 2 effects, but it provides a good basis for adding new features to the checker.

To define a range of effects, we have to define the relationship between each effect. Typically we'll use a hierarchy, just like in the standard Java type system. The two effects @NoAlloc and @MayAlloc have the following subtyping relation:

There's two ways to think about this. First, the set of methods that may or may not allocate memory must be a superset of the methods which may not allocate memory. Conversely, the @NoAlloc annotation provides a strictly stronger guarantee than the @MayAlloc annotation.

To check whether an operation (e.g., method call) is valid, we'll use a method checkEffect to check whether the operation's effect is a subtype of the effect of the method it's being called from. If not, we'll have Check Framework emit a warning:

public void checkEffect(Effect callerEffect, Effect targetEffect, Tree node) {
  if (targetEffect.compareTo(callerEffect) > 0) {
    // The target effect is a supertype of the effect of the enclosing method

    // The message call.invalid.alloc is defined in a .properties file
    checker.report(Result.failure("call.invalid.alloc", targetEffect, callerEffect),
	               node);
  }
}

The Annotation Checker

Now that each method has an annotation, we'll define a checker AllocEffectVisitor to enforce the annotations. There are three rules we want to enforce:

If a method with a @NoAlloc annotation uses the new operator, emit a warning.
If a method with a @NoAlloc annotation calls a method with the @MayAlloc annotation, emit a warning.
If the developer has written both @MayAlloc and @NoAlloc on a method, emit a warning.

Using these rules, it's always safe for a method to call another method that has the @NoAlloc annotation.

The Checker Framework's visitor implementation, BaseTypeVisitor, recursively visits each node in the program's Abstract Syntax Tree. To enforce the first rule, we'll override the visitNewArray and checkConstructorInvocation visitor methods. Our implementation will check that the enclosing method has the @MayAlloc annotation:

@Override
public Void visitNewArray(NewArrayTree node, Void p) {

  // The 'new' operator is just like a method that has a @MayAlloc annotation
  Effect targetEffect = new Effect(MayAlloc.class);

  // Get the annotation for the enclosing method
  MethodTree callerTree = TreeUtils.enclosingMethod(getCurrentPath());
  ExecutableElement callerElt = TreeUtils.elementFromDeclaration(callerTree);

  // Make sure the two effects are consistent. That is, that target
  // effect is a subtype of the calling effect. Because the
  // targetEffect is @MayAlloc, this checks that the method
  // annotation is @MayAlloc too.
  checkEffect(callerEffect, targetEffect, node);

  return super.visitNewArray(node, p);
}

To enforce the second rule, we'll override the visitMethodInvocation method. The implementation is the same, except we use the effect of the method being called:

@Override
public Void visitMethodInvocation(MethodInvocationTree node, Void p) {

  // Get the annotation for the method being called
  ExecutableElement methodElt = TreeUtils.elementFromUse(node);
  Effect targetEffect = atypeFactory.getDeclaredEffect(methodElt);

  // ... same as for visitNewArray(...)
}

To enforce the third rule, we'll override the visitMethod method to report an error if a method has both a @MayAlloc and @NoAlloc annotation:

@Override
public Void visitMethod(MethodTree node, Void p) {
  ExecutableElement methElt = TreeUtils.elementFromDeclaration(node);
  AnnotationMirror mayAlloc = atypeFactory.getDeclAnnotation(methElt, MayAlloc.class);
  AnnotationMirror noAlloc = atypeFactory.getDeclAnnotation(methElt, NoAlloc.class);

  if (mayAlloc != null && noAlloc != null) {
    checker.report(Result.failure("annotations.conflicts"), node);
  }

  return super.visitMethod(node, p);
}

Running the Checker

At this point, we've built a basic checker for memory allocations. You can download the full implementation on GitHub. To run the checker, use javac with the -processor argument and the checker on the classpath (setting the classpath with the -cp flag, as necessary):

:::bash
javac -processor com.toddschiller.checker.AllocEffectChecker com/toddschiller/experiments/AllocationEffects.java

The implementation on GitHub also supplies a debug mode, which you can enable by passing the -Alint=debugSpew flag to the compiler. The debug mode reports each check performed by the checker.

For the example file AllocationEffects.java, the checker reports 6 warnings. The two assignments

@NoAlloc
public void shouldWarn() {
  int x = mayAllocateMemory(); // an unannotated method
  int y = new Integer(3);
}

are both flagged by the checker:

AllocationEffects.java:42: error: [call.invalid.alloc] Calling a method with MayAlloc effect from a context limited to NoAlloc effects.
            int i = new Integer(2);
                    ^
AllocationEffects.java:56: error: [call.invalid.alloc] Calling a method with MayAlloc effect from a context limited to NoAlloc effects.
        int x = mayAllocateMemory();
                                 ^

Improving the Checker

Now that we've implemented a basic checker, there's two important questions to ask:

Can the checker emit a warning even when the program won't allocate memory (false positives)?
More importantly, are there any allocations that the checker will fail to report (false negatives)?

Eliminating False Warnings

The first question is easier to answer — of course! Just like the Java type checker, our checker doesn't consider values or control flow:

public void conditionallyAlloc(boolean alloc) {
  if (alloc) doAlloc();
}

@NoAlloc
public void noAlloc(){
  conditionallyAlloc(false); // WARNING!
}

Looking at the implementation of conditionallyAlloc, we ideally wouldn't get a warning. But, if we were to write an annotation for the the conditionallyAlloc method, what would we write? Unfortunately our vocabulary of just @NoAlloc and @MayAlloc is insufficient.

One way to solve the problem would be to let the developer write an annotation @MayAllocIf("alloc"), referring to the boolean alloc parameter. While we could modify the checker to support this particular annotation, we quickly run into a wall trying to support other expressions — we'd have to figure out how to verify arbitrary logic at compile-time!

In this case, a reasonable solution might be to ignore the warning by adding an @SuppressWarnings("alloceffect") annotation to the call to conditionallyAlloc. ("alloceffect" is the name of the checker in lower-case).

However, in many cases, it is better to refactor the code. Code that a checker can reason about is generally also easier for a human developer to reason about.

Can you think of other cases for which the checker will issue false warnings? Are there common patterns (e.g., the singleton pattern) where it would make sense to introduce special annotations?

Identifying All Allocations

Identifying allocations that the checker will miss is trickier — are all allocations the result of the new keyword?

Ignoring reflection and system calls, the answer appears to be "yes". However, some uses of new can be obfuscated. Consider a class with a static field and a method that accesses that field:

public class AllocOnLoad {
  public final static Integer five;
  static {
    // The static initializer can contain arbitrary code
    five = new Integer(5);
  }
}

public class Other {
  @NoAlloc
  public void addFive(int x){
    return x + AllocOnLoad.five; // Warning?
  }
}

When the program runs, if a call to addFive is the first time the AllocOnLoad class if referenced during the execution, the static initializer will run and memory will be allocated. On all subsequent calls, no memory will be allocated.

To catch this behavior, the developer would need annotate classes with whether or not their static initializer may allocate memory. The checker could then treat class references similar to method calls.

The problem with this approach is that it would lead to a lot of false positives. A potential solution would be to allow the developer to specify that certain classes have already been loaded when a method is called, à la:

@NoAlloc
@RequireLoaded({AllocOnLoad.class})
public void addFive(int x) {
  return x + AllocOnLoad.five; // Safe!
}

Implementing such a system would involve introducing an effect system to track which classes each method loads. The difference is that the effect system would need to track which classes must have been loaded. For example, the addFive method would have the effect @Loads({AllocOnLoad.class}) because the method always references the AllocOnLoad class.

Writing down which classes a method must load is tedious and error-prone. The developer has to consider all the classes transitively referenced by the method. Therefore, this information would be a good candidate for automatic inference.

Can you think of other cases where the checker would miss an allocation? What happens when you concatenate two strings: str1 + str2?

Summary

This post described an effect system for enforcing memory allocation patterns. We introduced two method annotations, @MayAlloc and @NoAlloc, to describe the effect of each method. We then used the Checker Framework to enforce that no memory allocations are either directly or indirectly performed by methods marked as @NoAlloc.

For more information about implementing effect systems with the Checker Framework, check out the framework's GUI Effect Checker, which checks for UI threading errors. Unlike the basic checker we built, it makes use of the Checker Framework's type annotation features to support common UI programming idioms.

The source code for the allocation checker is available on GitHub at: https://github.com/twschiller/alloc-effect-checker