From 5551d45c37ad68081f94cac8a4d4ec00224a9541 Mon Sep 17 00:00:00 2001
From: Ladislav Thon <lthon@redhat.com>
Date: Tue, 14 May 2024 13:17:14 +0200
Subject: [PATCH] ArC: initial documentation of CDI pitfalls with reactive
 programming

---
 docs/src/main/asciidoc/cdi-reference.adoc | 40 +++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/docs/src/main/asciidoc/cdi-reference.adoc b/docs/src/main/asciidoc/cdi-reference.adoc
index b05bd50da4e29..2257c1ebbfdff 100644
--- a/docs/src/main/asciidoc/cdi-reference.adoc
+++ b/docs/src/main/asciidoc/cdi-reference.adoc
@@ -1069,6 +1069,46 @@ public class NoopAsyncObserverExceptionHandler implements AsyncObserverException
 }
 ----
 
+[[reactive_pitfalls]]
+== CDI Pitfalls with Reactive Programming
+
+CDI is a purely synchronous framework.
+Its notion of asynchrony is very limited and based solely on thread pools and thread offloading.
+Therefore, there is a number of pitfalls when using CDI together with reactive programming.
+
+=== Detecting When Blocking Is Allowed
+
+The `BlockingOperationControl.isBlockingAllowed()` method allows detecting when blocking is allowed.
+When it is not, and you need to perform a blocking operation, you have to offload it to another thread.
+The easiest way is to use the `Vertx.executeBlocking()` method:
+
+[source,java]
+----
+import io.quarkus.runtime.BlockingOperationControl;
+
+@ApplicationScoped
+public class MyBean {
+    @Inject
+    Vertx vertx;
+
+    @PostConstruct
+    void init() {
+        if (BlockingOperationControl.isBlockingAllowed()) {
+            somethingThatBlocks();
+        } else {
+            vertx.executeBlocking(() -> {
+                somethingThatBlocks();
+                return null;
+            });
+        }
+    }
+
+    void somethingThatBlocks() {
+        ...
+    }
+}
+----
+
 [[build_time_apis]]
 == Build Time Extensions