https://github.com/reactor/BlockHound
Java agent to detect blocking calls from non-blocking threads.
https://github.com/reactor/BlockHound
Last synced: about 1 year ago
JSON representation
Java agent to detect blocking calls from non-blocking threads.
- Host: GitHub
- URL: https://github.com/reactor/BlockHound
- Owner: reactor
- License: apache-2.0
- Created: 2018-12-04T20:00:53.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2025-04-09T09:03:34.000Z (about 1 year ago)
- Last Synced: 2025-04-10T14:13:14.070Z (about 1 year ago)
- Language: Java
- Homepage:
- Size: 521 KB
- Stars: 1,409
- Watchers: 36
- Forks: 97
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Support: docs/supported_testing_frameworks.md
Awesome Lists containing this project
README
# BlockHound
[](https://repo1.maven.org/maven2/io/projectreactor/tools/blockhound/)
[](https://repo.spring.io/milestone/io/projectreactor/tools/blockhound/)
[](https://repo.spring.io/snapshot/io/projectreactor/tools/blockhound/)
[](https://gitter.im/reactor/BlockHound)
Java agent to detect blocking calls from non-blocking threads.
## How it works
BlockHound will transparently instrument the JVM classes and intercept blocking calls (e.g. IO) if they are performed from threads marked as "non-blocking operations only" (ie. threads implementing Reactor's `NonBlocking` marker interface, like those started by `Schedulers.parallel()`). If and when this happens (but remember, this should never happen! :stuck_out_tongue_winking_eye:), an error will be thrown. Here is an example:
```java
// Example.java
BlockHound.install();
Mono.delay(Duration.ofSeconds(1))
.doOnNext(it -> {
try {
Thread.sleep(10);
}
catch (InterruptedException e) {
throw new RuntimeException(e);
}
})
.block();
```
Will result in:
```
reactor.blockhound.BlockingOperationError: Blocking call! java.lang.Thread.sleep
at java.base/java.lang.Thread.sleep(Native Method)
at com.example.Example.lambda$exampleTest$0(Example.java:16)
```
Note that it points to the exact place where the blocking call got triggered. In this example it was `Example.java:16`.
## Getting it
Download it from Maven Central repositories (stable releases only) or repo.spring.io:
_Gradle_
```groovy
repositories {
mavenCentral()
// maven { url 'https://repo.spring.io/milestone' }
// maven { url 'https://repo.spring.io/snapshot' }
}
dependencies {
testImplementation 'io.projectreactor.tools:blockhound:$LATEST_RELEASE'
// testImplementation 'io.projectreactor.tools:blockhound:$LATEST_MILESTONE'
// testImplementation 'io.projectreactor.tools:blockhound:$LATEST_SNAPSHOT'
}
```
with Kotlin DSL
```kotlin
repositories {
mavenCentral()
// maven("https://repo.spring.io/milestone")
// maven("https://repo.spring.io/snapshot")
}
dependencies {
testImplementation("io.projectreactor.tools:blockhound:$LATEST_RELEASE")
// testImplementation("io.projectreactor.tools:blockhound:$LATEST_MILESTONE")
// testImplementation("io.projectreactor.tools:blockhound:$LATEST_SNAPSHOT")
}
```
_Maven_
```xml
io.projectreactor.tools
blockhound
$LATEST_RELEASE
```
Where:
|||
|-|-|
|`$LATEST_RELEASE`|[](https://repo1.maven.org/maven2/io/projectreactor/tools/blockhound/)|
|`$LATEST_MILESTONE`|[](https://repo.spring.io/milestone/io/projectreactor/tools/blockhound/)|
|`$LATEST_SNAPSHOT`|[](https://repo.spring.io/snapshot/io/projectreactor/tools/blockhound/)|
## JDK13+ support
for JDK 13+, it is no longer allowed redefining native methods. So for the moment, as a temporary work around, please use the
`-XX:+AllowRedefinitionToAddDeleteMethods` jvm argument:
_Maven_
```xml
org.apache.maven.plugins
maven-surefire-plugin
2.22.2
-XX:+AllowRedefinitionToAddDeleteMethods
```
_Gradle_
```groovy
tasks.withType(Test).all {
if (JavaVersion.current().isCompatibleWith(JavaVersion.VERSION_13)) {
jvmArgs += [
"-XX:+AllowRedefinitionToAddDeleteMethods"
]
}
}
```
with Kotlin DSL
```kotlin
tasks.withType().all {
if (JavaVersion.current().isCompatibleWith(JavaVersion.VERSION_13)) {
jvmArgs("-XX:+AllowRedefinitionToAddDeleteMethods")
}
}
```
## Built-in integrations
Although BlockHound supports [the SPI mechanism to integrate with](https://github.com/reactor/BlockHound/blob/master/docs/custom_integrations.md), it comes with a few built-in integrations:
1. [Project Reactor](https://projectreactor.io)
Version 3.2.x is supported out of the box.
Starting with `reactor-core` version 3.3.0, there is [a built-in integration in Reactor itself](https://github.com/reactor/reactor-core/blob/v3.3.0.RELEASE/reactor-core/src/main/java/reactor/core/scheduler/ReactorBlockHoundIntegration.java) that uses [the SPI](https://github.com/reactor/BlockHound/blob/master/docs/custom_integrations.md).
2. [RxJava 2](https://github.com/ReactiveX/RxJava/) is supported.
RxJava 3 and further versions of RxJava will require an SPI to be implemented, either by the framework or user. See [this PR to RxJava](https://github.com/ReactiveX/RxJava/pull/6692) with an example of the SPI's implementation.
# Quick Start
See [the docs](./docs/README.md).
-------------------------------------
_Licensed under [Apache Software License 2.0](www.apache.org/licenses/LICENSE-2.0)_
_Sponsored by [Pivotal](https://pivotal.io)_