Fray Detects Concurrency Issues in JVM Languages

Carnegie Mellon University has introduced Fray, a concurrency testing tool for JVM programs to catch bugs and replay them. Written in Kotlin and based on this research paper, Fray can’t find all concurrency issues, but uses recent research to maximize the chances of detecting them. Fray uses shadow locking, a technique that incorporates extra locks to mediate access to shared resources in a specific order.

Fray supports Java versions including JDK 25 and has successfully discovered bugs in the JDK, Lucene, Kafka, Flink and Guava. The framework is capable of detecting multi-threading issues, but not bugs caused by concurrent memory writes.The following plugin and dependency configuration is required for Maven:

<plugin>
    <groupId>org.pastalab.fray.maven</groupId>
    <artifactId>fray-plugins-maven</artifactId>
    <version>0.6.9</version>
    <executions>
        <execution>
            <id>prepare-fray</id>
            <goals>
                <goal>prepare-fray</goal>
            </goals>
        </execution>
    </executions>
</plugin>

<dependency>
    <groupId>org.pastalab.fray</groupId>
    <artifactId>fray-junit</artifactId>
    <version>0.6.9</version>
    <scope>test</scope>
</dependency>

Alternatively, the following plugin configuration can be used for Gradle:

plugins {
    id("org.pastalab.fray.gradle") version "0.6.9"
}

After configuring Gradle, the tests can be run with the following command:

./gradlew frayTest

Lastly, IntelliJ may be used to run Fray tests by following the IDE documentation on GitHub.

After configuring the build system, JUnit 5 can be used to run tests by annotating the class with @ExtendWith(FrayTestExtension.class) and annotating the tests with @ConcurrencyTest:

@ExtendWith(FrayTestExtension.class)
public class MyFirstTest {
    @ConcurrencyTest
    public void myTest() {
        …
    }
}

The following BankAccount class is a simplified example that might result in a deadlock when multiple threads access the synchronized code:

public class BankAccount {
    public BankAccount(double balance) {
        this.balance = balance;
    }

    private double balance;

    public void transfer(double amount, BankAccount toAccount) {
        synchronized (this) {
            synchronized (toAccount) {
                this.balance -= amount;
                toAccount.balance += amount;
            }
        }
    }
}

To detect the deadlock, a Fray test is created, which explicitly sets the number of iterations to ten. The complete set of parameters can be found in the ConcurrencyTest.kt on GitHub.

@ExtendWith(FrayTestExtension.class)
public class BankAccountTest {
    public void myBankAccountTest() throws InterruptedException {
        BankAccount bankAccount1 = new BankAccount(5000);
        BankAccount bankAccount2 = new BankAccount(6000);

        Thread thread1 = new Thread(() -> {
            bankAccount1.transfer(100, bankAccount2);
        });

        Thread thread2 = new Thread(() -> {
            bankAccount2.transfer(50, bankAccount1);
        });

        thread1.start();
        thread2.start();
        thread1.join();
        thread2.join();
    }

    @ConcurrencyTest(
            iterations = 10,
            )
    public void runMyBankAccountTestUsingFray() throws InterruptedException {
        myBankAccountTest();
    }
}

Running the above test results in the following error after the first four (out of ten) iterations:

[ERROR] Errors: 
[ERROR] org.example.BankAccountTest.runMyBankAccountTestUsingFray
[INFO]   Run 1: PASS
[INFO]   Run 2: PASS
[INFO]   Run 3: PASS
[ERROR]   Run 4: BankAccountTest.runMyBankAccountTestUsingFray:33->myBankAccountTest:25->Object.wait:-1 » Deadlock
[INFO]   Run 5: PASS
[INFO]   Run 6: PASS
[INFO]   Run 7: PASS
[INFO]   Run 8: PASS
[INFO]   Run 9: PASS
[INFO]   Run 10: PASS

Alternatively, for other testing frameworks apart from JUnit, the FrayInTestLauncher class may be used:

public void myTest() {
    FrayInTestLauncher.INSTANCE.launchFrayTest(() -> {
        …
    });
}

Fray will automatically generate a test case when a test fails, to reproduce the failure. Detailed information is logged in the report folder. When using Maven, the report folder is located inside target/fray/fray-report. This folder may be used to reproduce the failure in two different ways.

The first option is to rerun the test with the same scheduler and recorded random choices as described in the Feedback-guided Adaptive Testing of Distributed Systems Designs paper. Therefore, the path to the replay file should be set in the ConcurrencyTest annotation:

@ConcurrencyTest(
        replay = "[path to report]/recording"
)

Running the test again immediately results in the following error:

Error: org.pastalab.fray.runtime.DeadlockException

The test passes after resolving the deadlock inside the example application.

Alternatively, the test can be executed again with the exact thread schedule observed in the original execution. Therefore, the schedule needs to be recorded with the following Java option: -Dfray.recordSchedule=true. After recording the schedule, the ReplayScheduler class should be used in the ConcurrencyTest annotation:

@ConcurrencyTest(
    scheduler = ReplayScheduler.class,
    replay = "[path to report]/recording"
)

Alternative frameworks to detect concurrency issues in Java code include VMLens, Java Concurrency Stress (jcstress), and Lincheck from IntelliJ IDEA. More information on Fray can be found in the usage guide or in the technical report.