From 7a06a23ee2d3f2d2df4e6a57a9e3c65fdee26486 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 | 41 +++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/docs/src/main/asciidoc/cdi-reference.adoc b/docs/src/main/asciidoc/cdi-reference.adoc
index b05bd50da4e29..29f1938ead089 100644
--- a/docs/src/main/asciidoc/cdi-reference.adoc
+++ b/docs/src/main/asciidoc/cdi-reference.adoc
@@ -1069,6 +1069,47 @@ public class NoopAsyncObserverExceptionHandler implements AsyncObserverException
 }
 ----
 
+[[reactive_pitfalls]]
+== 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 `io.quarkus.runtime.BlockingOperationControl#isBlockingAllowed()` method can be used to detect whether blocking is allowed on the current thread.
+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() {
+        // use the file system or JDBC, call a REST service, etc.
+        Thread.sleep(5000);
+    }
+}
+----
+
 [[build_time_apis]]
 == Build Time Extensions