BlockHound Documentation

BlockHound operates as a Java Agent that instruments a predefined set of blocking methods within the JVM. It works by injecting a check at the beginning of method bodies to determine if the current thread is permitted to execute a blocking operation.

Java Method Detection

For standard Java methods, BlockHound alters the bytecode to insert a call to reactor.blockhound.BlockHoundRuntime.checkBlocking at the start of the method body. For example, a java.net.Socket.connect call is instrumented to include a check before the actual connection logic is executed.

Native Method Detection

Since native methods (like java.lang.Thread.sleep) cannot be instrumented directly because they lack a Java method body, BlockHound uses a relocation technique:

1. The original native method is renamed (e.g., to $$BlockHound$$_sleep).
2. A new Java method is created with the original signature.
3. This new method performs the checkBlocking call and then delegates to the renamed native implementation.

This approach ensures minimal overhead, adding only a single method hop.

// Example of how a Java method is instrumented
public void connect(SocketAddress endpoint, int timeout) {
    reactor.blockhound.BlockHoundRuntime.checkBlocking(
        "java.net.Socket",
        "connect",
        /*method modifiers*/
    );
    // original implementation follows...
}

BlockHound uses a ThreadLocal<Boolean> named IS_ALLOWED to track whether blocking is permitted in the current thread. This allows the agent to support white-listed methods (like class loading) that might perform blocking operations without triggering an error.

The IS_ALLOWED State

• false: Blocking is not allowed in this thread. Any blocking call will trigger a report/error.
• true: Blocking is explicitly allowed.
• null: The thread state is indeterminate (used as an optimization for non-blocking threads).

The Workflow

1. Check: When an instrumented method is called, BlockHoundRuntime.checkBlocking reads the IS_ALLOWED value. If it is false, it reports the violation.
2. Context Switching: When entering an "allowed" context (e.g., inside a ClassLoader), BlockHound captures the previous IS_ALLOWED state, sets it to true, executes the logic, and restores the previous state in a finally block.

This mechanism ensures that the check is an $O(1)$ operation consisting of a single ThreadLocal read, making it performant enough for production use.

When adding BlockHound to your project, always include a test that asserts the integration is working correctly. This prevents false positives caused by the agent being incorrectly installed or not installed at all. A simple way to verify this using Project Reactor is to schedule a task that performs a blocking operation (like Thread.sleep(0)) on a parallel scheduler and assert that it throws a BlockingOperationError.

@Test
public void blockHoundWorks() throws TimeoutException, InterruptedException {
    try {
        FutureTask<?> task = new FutureTask<>(() -> {
            Thread.sleep(0);
            return "";
        });
        Schedulers.parallel().schedule(task);

        task.get(10, TimeUnit.SECONDS);
        Assert.fail("should fail");
    } catch (ExecutionException e) {
        Assert.assertTrue("detected", e.getCause() instanceof BlockingOperationError);
    }
}

When running BlockHound in a Tomcat webapp, do not embed the BlockHound dependency within the webapp itself. Instead, place the BlockHound JAR in the Tomcat shared lib directory.

If using the Cargo Maven plugin, you can configure a shared classpath for the dependency.

<dependencies>
    <dependency>
        <groupId>io.projectreactor.tools</groupId>
        <artifactId>blockhound</artifactId>
        <version>(latest blockhound version)</version>
        <scope>provided</scope>
    </dependency>
    ...
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.codehaus.cargo</groupId>
            <artifactId>cargo-maven3-plugin</artifactId>
            <version>1.10.4</version>
            <configuration>
                <container>
                    <containerId>tomcat9x</containerId>
                    <type>embedded</type>
                    <dependencies>
                        <dependency>
                            <groupId>io.projectreactor.tools</groupId>
                            <artifactId>blockhound</artifactId>
                            <classpath>shared</classpath>
                        </dependency>
                    </dependencies>
                </container>
                <deployables>
                    <deployable>
                        <type>war</type>
                        <location>${project.build.directory}/${project.build.finalName}.war</location>
                        <properties>
                            <context>/</context>
                        </properties>
                    </deployable>
                </deployables>
            </configuration>
        </plugin>
    </plugins>
</build>