Top Description Inners Fields Constructors Methods
reactor.blockhound

public Class BlockHound

extends Object
Class Inheritance
Imports
net.bytebuddy.agent.ByteBuddyAgent, net.bytebuddy.agent.builder.AgentBuilder, .AgentBuilder.DescriptionStrategy, .AgentBuilder.InitializationStrategy, .AgentBuilder.PoolStrategy, .AgentBuilder.RedefinitionStrategy, .AgentBuilder.RedefinitionStrategy.DiscoveryStrategy, .AgentBuilder.TypeStrategy, net.bytebuddy.asm.Advice, net.bytebuddy.dynamic.ClassFileLocator, net.bytebuddy.matcher.ElementMatchers, net.bytebuddy.pool.TypePool, .TypePool.CacheProvider, reactor.blockhound.integration.BlockHoundIntegration, java.lang.instrument.ClassFileTransformer, .Instrumentation, java.util.*, java.util.concurrent.ConcurrentHashMap, java.util.concurrent.atomic.AtomicBoolean, java.util.function.Consumer, .Function, .Predicate, java.util.stream.Stream, .StreamSupport
BlockHound is a tool to detect blocking calls from non-blocking threads. To use it, you need to "install" it first with either BlockHound#install(BlockHoundIntegration...) or BlockHound#builder(). On installation, it will run the instrumentation and add the check to the blocking methods. Note that the installation can (and should) only be done once, subsequent install calls will be ignored. Hence, the best place to put the install call is before all tests or in the beginning of your "public static void main" method. If you have it automatically installed (e.g. via a testing framework integration), you can apply the customizations by using the SPI mechanism (see BlockHoundIntegration).

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
BlockHound.BlockHoundPoolStrategy

public static class
BlockHound.Builder

Field Summary

Modifier and TypeField and Description
private static final AtomicBoolean
INITIALIZED

pack-priv static final String
PREFIX

Constructor Summary

AccessConstructor and Description
private
BlockHound()

Method Summary

Modifier and TypeMethod and Description
public static BlockHound.Builder

Returns:

a fresh BlockHound.Builder
builder()

Creates a completely new BlockHound.Builder that *does not* have any integration applied.

public static void
install(BlockHoundIntegration...
an array of integrations to automatically apply on the intermediate builder
integrations)

Loads integrations with ServiceLoader, adds provided integrations, and installs the BlockHound instrumentation.

public static void
premain(String
Options for the agent.
agentArgs, Instrumentation
Instrumentation API.
inst)

Entrypoint for installation via the -javaagent= command-line option.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

INITIALIZEDback to summary
private static final AtomicBoolean INITIALIZED
PREFIXback to summary
pack-priv static final String PREFIX

Constructor Detail

BlockHoundback to summary
private BlockHound()

Method Detail

builderback to summary
public static BlockHound.Builder builder()

Creates a completely new BlockHound.Builder that *does not* have any integration applied. Use it only if you want to ignore the built-in SPI mechanism (see install(BlockHoundIntegration...)).

Returns:BlockHound.Builder

a fresh BlockHound.Builder

See Also
BlockHound#install(BlockHoundIntegration...)
installback to summary
public static void install(BlockHoundIntegration... integrations)

Loads integrations with ServiceLoader, adds provided integrations, and installs the BlockHound instrumentation. If you don't want to load the integrations, use builder() method.

Parameters
integrations:BlockHoundIntegration[]

an array of integrations to automatically apply on the intermediate builder

See Also
BlockHound#builder()
premainback to summary
public static void premain(String agentArgs, Instrumentation inst)

Entrypoint for installation via the -javaagent= command-line option.

Parameters
agentArgs:String

Options for the agent.

inst:Instrumentation

Instrumentation API.

See Also
java.lang.instrument
reactor.blockhound back to summary

private final Class BlockHound.BlockHoundPoolStrategy

extends Object
implements PoolStrategy
Class Inheritance
All Implemented Interfaces
net.bytebuddy.agent.builder.AgentBuilder.PoolStrategy

Field Summary

Modifier and TypeField and Description
public static final AgentBuilder.PoolStrategy
INSTANCE

Constructor Summary

AccessConstructor and Description
private
BlockHoundPoolStrategy()

Method Summary

Modifier and TypeMethod and Description
public TypePool
typePool(ClassFileLocator
The class file locator to use.
classFileLocator, ClassLoader
The class loader for which the class file locator was created or null if the boot loader.
classLoader, String
The name of the currently instrumented type.
name)

Implements net.bytebuddy.agent.builder.AgentBuilder.PoolStrategy.typePool.

Creates a type pool for a given class file locator.
public TypePool
typePool(ClassFileLocator
The class file locator to use.
classFileLocator, ClassLoader
The class loader for which the class file locator was created or null if the boot loader.
classLoader)

Implements net.bytebuddy.agent.builder.AgentBuilder.PoolStrategy.typePool.

Creates a type pool for a given class file locator.
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

INSTANCEback to summary
public static final AgentBuilder.PoolStrategy INSTANCE

Constructor Detail

BlockHoundPoolStrategyback to summary
private BlockHoundPoolStrategy()

Method Detail

typePoolback to summary
public TypePool typePool(ClassFileLocator classFileLocator, ClassLoader classLoader, String name)

Implements net.bytebuddy.agent.builder.AgentBuilder.PoolStrategy.typePool.

Doc from net.bytebuddy.agent.builder.AgentBuilder.PoolStrategy.typePool.

Creates a type pool for a given class file locator. If a cache is used, the type that is currently instrumented is not used.

Parameters
classFileLocator:ClassFileLocator

The class file locator to use.

classLoader:ClassLoader

The class loader for which the class file locator was created or null if the boot loader.

name:String

The name of the currently instrumented type.

Returns:TypePool

A type pool for the supplied class file locator.

Annotations
@Override
typePoolback to summary
public TypePool typePool(ClassFileLocator classFileLocator, ClassLoader classLoader)

Implements net.bytebuddy.agent.builder.AgentBuilder.PoolStrategy.typePool.

Doc from net.bytebuddy.agent.builder.AgentBuilder.PoolStrategy.typePool.

Creates a type pool for a given class file locator.

Parameters
classFileLocator:ClassFileLocator

The class file locator to use.

classLoader:ClassLoader

The class loader for which the class file locator was created or null if the boot loader.

Returns:TypePool

A type pool for the supplied class file locator.

Annotations
@Override
reactor.blockhound back to summary

public Class BlockHound.Builder

extends Object
Class Inheritance

Field Summary

Modifier and TypeField and Description
private final Map<String, Map<String, Boolean>>
allowances

private final Map<String, Map<String, Set<String>>>
blockingMethods

private Instrumentation
configuredInstrumentation

private Predicate<Thread>
dynamicThreadPredicate

private Consumer<BlockingMethod>
onBlockingMethod

private Predicate<Thread>
threadPredicate

Constructor Summary

AccessConstructor and Description
pack-priv
Builder()

Method Summary

Modifier and TypeMethod and Description
public BlockHound.Builder

Returns:

this
addDynamicThreadPredicate(Predicate<Thread>
a predicate to append to the current instance of the predicate
predicate)

Appends the provided predicate to the current one.

public BlockHound.Builder

Returns:

this
allowBlockingCallsInside(String
class' name (e.g. "java.lang.Thread")
className, String
a method name
methodName)

Allows blocking calls inside any method of a class with name identified by the provided className and which name matches the provided methodName.

public BlockHound.Builder

Returns:

this
blockingMethodCallback(Consumer<BlockingMethod>
a consumer of the detected blocking method call's description (BlockingMethod).
consumer)

Overrides the callback that is being triggered when a blocking method is detected

public BlockHound.Builder

Returns:

this
disallowBlockingCallsInside(String
class' name (e.g. "java.lang.Thread")
className, String
a method name
methodName)

Disallows blocking calls inside any method of a class with name identified by the provided className and which name matches the provided methodName.

public BlockHound.Builder

Returns:

this
dynamicThreadPredicate(Function<Predicate<Thread>, Predicate<Thread>>
a function to immediately apply on the current instance of the predicate
function)

Replaces the current dynamic thread predicate with the result of applying the provided function.

public void
install()

Installs the agent and runs the instrumentation, but only if BlockHound wasn't installed yet (it is global).

private void
instrument(Instrumentation instrumentation)

public BlockHound.Builder

Returns:

this
loadIntegrations(BlockHoundIntegration...
an array of integrations to automatically apply on the builder using with(BlockHoundIntegration)
integrations)

Loads integrations with ServiceLoader and adds provided integrations using {with(BlockHoundIntegration)}.

public BlockHound.Builder

Returns:

this
markAsBlocking(Class<T>
a class reference
clazz, String
a method name
methodName, String
a method descriptor in JVM's format
signature)

Marks provided method of the provided class as "blocking".

public BlockHound.Builder

Returns:

this
markAsBlocking(String
class' name (e.g. "java.lang.Thread")
className, String
a method name
methodName, String
a method signature (in JVM's format)
signature)

Marks provided method of the class identified by the provided name as "blocking".

public BlockHound.Builder

Returns:

this
nonBlockingThreadPredicate(Function<Predicate<Thread>, Predicate<Thread>>
a function to immediately apply on the current instance of the predicate
function)

Replaces the current non-blocking thread predicate with the result of applying the provided function.

private void
testInstrumentation()

public BlockHound.Builder

Returns:

this
with(BlockHoundIntegration
an integration to apply
integration)

Applies the provided BlockHoundIntegration to the current builder

public BlockHound.Builder

Returns:

this
with(Instrumentation
The instrumentation instance to use.
instrumentation)

Configure the Instrumentation to use.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

allowancesback to summary
private final Map<String, Map<String, Boolean>> allowances
blockingMethodsback to summary
private final Map<String, Map<String, Set<String>>> blockingMethods
configuredInstrumentationback to summary
private Instrumentation configuredInstrumentation
dynamicThreadPredicateback to summary
private Predicate<Thread> dynamicThreadPredicate
onBlockingMethodback to summary
private Consumer<BlockingMethod> onBlockingMethod
threadPredicateback to summary
private Predicate<Thread> threadPredicate

Constructor Detail

Builderback to summary
pack-priv Builder()

Method Detail

addDynamicThreadPredicateback to summary
public BlockHound.Builder addDynamicThreadPredicate(Predicate<Thread> predicate)

Appends the provided predicate to the current one.

Parameters
predicate:Predicate<Thread>

a predicate to append to the current instance of the predicate

Returns:BlockHound.Builder

this

allowBlockingCallsInsideback to summary
public BlockHound.Builder allowBlockingCallsInside(String className, String methodName)

Allows blocking calls inside any method of a class with name identified by the provided className and which name matches the provided methodName.

There are two special cases for methodName:

  • static initializers are currently supported by their JVM reserved name of "<clinit>"
  • constructors are currently not supported (ByteBuddy cannot weave the necessary instrumentation around a constructor that throws an exception, see gh174)
Parameters
className:String

class' name (e.g. "java.lang.Thread")

methodName:String

a method name

Returns:BlockHound.Builder

this

blockingMethodCallbackback to summary
public BlockHound.Builder blockingMethodCallback(Consumer<BlockingMethod> consumer)

Overrides the callback that is being triggered when a blocking method is detected

Parameters
consumer:Consumer<BlockingMethod>

a consumer of the detected blocking method call's description (BlockingMethod).

Returns:BlockHound.Builder

this

disallowBlockingCallsInsideback to summary
public BlockHound.Builder disallowBlockingCallsInside(String className, String methodName)

Disallows blocking calls inside any method of a class with name identified by the provided className and which name matches the provided methodName.

There are two special cases for methodName:

  • static initializers are currently supported by their JVM reserved name of "<clinit>"
  • constructors are currently not supported (ByteBuddy cannot weave the necessary instrumentation around a constructor that throws an exception, see gh174)
Parameters
className:String

class' name (e.g. "java.lang.Thread")

methodName:String

a method name

Returns:BlockHound.Builder

this

dynamicThreadPredicateback to summary
public BlockHound.Builder dynamicThreadPredicate(Function<Predicate<Thread>, Predicate<Thread>> function)

Replaces the current dynamic thread predicate with the result of applying the provided function.

Warning

Consider always using Predicate#or(Predicate) and not override the previous one: dynamicThreadPredicate(current -> current.or(MyMarker.class::isInstance))

Parameters
function:Function<Predicate<Thread>, Predicate<Thread>>

a function to immediately apply on the current instance of the predicate

Returns:BlockHound.Builder

this

installback to summary
public void install()

Installs the agent and runs the instrumentation, but only if BlockHound wasn't installed yet (it is global).

instrumentback to summary
private void instrument(Instrumentation instrumentation)
loadIntegrationsback to summary
public BlockHound.Builder loadIntegrations(BlockHoundIntegration... integrations)

Loads integrations with ServiceLoader and adds provided integrations using {with(BlockHoundIntegration)}. If you don't want to load the integrations using service loader, only use with(BlockHoundIntegration) method.

Parameters
integrations:BlockHoundIntegration[]

an array of integrations to automatically apply on the builder using with(BlockHoundIntegration)

Returns:BlockHound.Builder

this

See Also
BlockHound#builder()
markAsBlockingback to summary
public BlockHound.Builder markAsBlocking(Class<T> clazz, String methodName, String signature)

Marks provided method of the provided class as "blocking". The descriptor should be in JVM's format: https://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/types.html#wp276

Parameters
clazz:Class<T>

a class reference

methodName:String

a method name

signature:String

a method descriptor in JVM's format

Returns:BlockHound.Builder

this

markAsBlockingback to summary
public BlockHound.Builder markAsBlocking(String className, String methodName, String signature)

Marks provided method of the class identified by the provided name as "blocking". The descriptor should be in JVM's format: https://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/types.html#wp276

Parameters
className:String

class' name (e.g. "java.lang.Thread")

methodName:String

a method name

signature:String

a method signature (in JVM's format)

Returns:BlockHound.Builder

this

nonBlockingThreadPredicateback to summary
public BlockHound.Builder nonBlockingThreadPredicate(Function<Predicate<Thread>, Predicate<Thread>> function)

Replaces the current non-blocking thread predicate with the result of applying the provided function.

Warning

Consider always using Predicate#or(Predicate) and not override the previous one: nonBlockingThreadPredicate(current -> current.or(MyMarker.class::isInstance))

Parameters
function:Function<Predicate<Thread>, Predicate<Thread>>

a function to immediately apply on the current instance of the predicate

Returns:BlockHound.Builder

this

testInstrumentationback to summary
private void testInstrumentation()
withback to summary
public BlockHound.Builder with(BlockHoundIntegration integration)

Applies the provided BlockHoundIntegration to the current builder

Parameters
integration:BlockHoundIntegration

an integration to apply

Returns:BlockHound.Builder

this

withback to summary
public BlockHound.Builder with(Instrumentation instrumentation)

Configure the Instrumentation to use. If not provided, ByteBuddyAgent#install() is used.

Parameters
instrumentation:Instrumentation

The instrumentation instance to use.

Returns:BlockHound.Builder

this