From 2b3e0717e47fa2ed9e33b315b7cc7bbfa4bf3f14 Mon Sep 17 00:00:00 2001
From: SpaceFox <ujueseo.yeou@gmail.com>
Date: Wed, 14 Feb 2024 00:14:03 +0100
Subject: [PATCH] Adds an implementation note about @VirtualThreadUnit
 limitations

Closes #38721
---
 .../test/junit5/virtual/VirtualThreadUnit.java    | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/independent-projects/junit5-virtual-threads/src/main/java/io/quarkus/test/junit5/virtual/VirtualThreadUnit.java b/independent-projects/junit5-virtual-threads/src/main/java/io/quarkus/test/junit5/virtual/VirtualThreadUnit.java
index b37efa15ef7fc..4af392208fdb4 100644
--- a/independent-projects/junit5-virtual-threads/src/main/java/io/quarkus/test/junit5/virtual/VirtualThreadUnit.java
+++ b/independent-projects/junit5-virtual-threads/src/main/java/io/quarkus/test/junit5/virtual/VirtualThreadUnit.java
@@ -11,6 +11,21 @@
 
 /**
  * Extends the test case to detect pinned carrier thread.
+ * <br/>
+ * <br/>
+ * <b>Implementation notes:</b> current implementation uses JFR under the hood, with two consequences:
+ * <ol>
+ * <li>This test won’t work on JVM without JFR support, e.g. OpenJ9.</li>
+ * <li>Each test that uses this annotation is several seconds longer than versions without it.</li>
+ * </ol>
+ * This annotation uses JFR recording to detect pinning and analyze when a specific event is fired.
+ * Unfortunately, to ensure no events are missed, the test must ensure the JFR recording is on and off.
+ * It fires a mock event and wait until it read it.
+ * Due to JFR recording API limitations, it takes a lot of time to do these loops as there are many file reads.
+ * This adds several seconds to start and to stop to each test with pinned carrier thread detection enabled; and this
+ * additional work is mandatory to avoid missing event.
+ * <br/>
+ * This behaviour is not part of API and may change in future version.
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)