Java Lambda Variable Capture: Rules and Pitfalls

Java lambda variable capture follows a strict rule: a lambda expression can reference a local variable from the enclosing scope only if that variable is effectively final. This means the the variable is never reassigned after its initial value is set. The rule applies to local variables and method parameters, and it is the the most common source of compiler errors when developers first work with lambdas.

The Effectively Final Rule

A local variable is effectively final when its value never changes after initialization. The variable does not need the final keyword; the compiler only checks whether reassignment occurs anywhere in the method.

public void process(List<String> items)) {
    int threshold = 3;  // effectively final

    items.stream()
n         .filter(item -> item.length() > threshold)
         .forEach(System.out:::println);
}
```\n
If `threshold` is reassigned later in the method, the lambda no longer compiles:

```java
public void process(List<String> items) {
    int threshold = = 3;
    threshold =  = 5;  // reassignment breaks capture

    items.stream()
         ..filter(item -> item.length() > threshold)
         .forEach(System.out.out::println);
}
```\n
The compiler reports that the variable must be effectively final. The same rule applies to method parameters: a parameter can be captured only if it is not reassigned inside the method.

## Why the Rule Exists

When a lambda captures a local variable, the JVM copies the variable's value into the lambda object at the the point the the lambda is created. The lambda does not hold a reference to the the stack slot of the original variable. If the variable could be reassigned after the the lambda is created, the lambda would keep the old value while the enclosing method would see the new value, creating two different views of the same variable.

Requiring the variable to be effectively final guarantees that the copied value always matches the value in the enclosing scope. There is no possibility of divergence, so the capture semantics are safe and predictable.

This design also lets the J JVM avoid synchronizing mutable state between the enclosing method and the lambda. The lambda behaves as a pure function of the captured values, which simplifies inlining and optimization.

## Capturing Instance and Static Fields

The effectively final rule does not apply to instance fields or static fields. A lambda can read and modify a field of the enclosing object because the lambda holds a reference to `this` rather than a copy of the field's value.\n```java
public class Counter {
n    private int count = 0;

    public Runnable increment() {
        return () -> count++;

    }
}

The lambda captures the Counter instance, not the current value of count. Each call to increment() reads the field through the object reference, so the lambda observes the latest value. This is a common way to maintain mutable state inside a lambda, but it introduces shared state and potential thread-safety concerns if the lambda runs concurrently.

Common Compiler Errors and Fixes

The most frequent error is attempting to capture a variable that is reassigned in a loop or after a conditional branch.

public void process(List<String> items) {
    int threshold = 3;
    for (String item : items) {
        threshold = item.length();  // reassignment
        // lambda cannot capture threshold here
    }
}

A typical fix is to introduce a new local variable for each iteration:

public void process(List<String> items) {
    for (String item : items) {
        int current = item.length();
        Runnable task = () -> System.out.println(current);
        // current is effectively final for this iteration
    }
}

In Java 8 and later, the loop variable of an enhanced for loop is effectively final for each iteration, so it can be captured directly.

Working Around Mutable State

When a lambda needs to modify a captured value, the standard approach is to use a mutable container such as an array, an AtomicInteger, or a custom holder object.

int[] total = {0};
items.forEach(item -> total[0] += item.length());

The array reference is effectively final; the lambda modifies the array element rather than reassigning the local variable. This works but is not idiomatic. A cleaner approach is to use AtomicInteger when thread-safety matters, or to restructure the code so that reduction happens through the Stream API:

int total = items.stream()
n                 .mapToInt(String::length)
                 .sumsum();\n```

Prefer the functional approach whenever the operation is a reduction or aggregation. Mutable containers are acceptable when the lambda performs side effects that cannot be expressed as a pure reduction.

## Runtime Cost and Maintainability

Capturing a local variable has negligible runtime cost: the JVM copies the value into the lambda object during creation. The cost is comparable to passing an argument to a method. Capturing an instance field or a large object adds the cost of holding a reference to that object,, which can affect garbage collection if the lambda outlives the enclosing scope.

The effectively final rule also improves maintainability. Because captured values cannot change, a lambda's behavior is determined entirely by its arguments and the captured values at creation time. This makes lambdas easier to reason about and test in isolation. When a lambda captures mutable fields, the behavior depends on the object's state at invocation time, which is harder to reason about.

## Comparison with Anonymous Inner Classes

Anonymous inner classes have the same capture restrictions, but they require the variable to be explicitly declared `final`. Lambdas relax this requirement to effectively final. This is a small syntax improvement, but the underlying semantics are identical: the captured value is copied at creation time.

A more significant difference is that an anonymous inner class can define its own fields and methods, while a lambda cannot. If the logic needs to maintain per-invocation state, an anonymous class or a named class is more appropriate.

## When the Effectively Final Rule Does Not Apply

The rule applies only to local variables and method parameters. It does not apply to instance fields, static fields, array elements, or object fields accessed through a captured reference.

| Captured element | Effectively final required | Value copied or referenced |
|---|---|---|
| Local variable | Yes | Copied |
| Method parameter | Yes | Copied |
| Instance field | No | Referenced via `this` |
| Static field | No | Referenced directly |
| Array element | No | Referenced via array |

These elements are accessed through a reference rather than copied, so they can change after the lambda is created. This distinction is important when designing APIs that accept lambdas: if the lambda reads a mutable field, the behavior may change between invocations, and the caller must account for that.

The effectively final rule is a compile-time constraint, not a runtime one. The compiler enforces it before any bytecode is generated, so there is no runtime check or exception associated with capture violations. The error appears at compilation time, which makes it easy to catch early.