Merge pull request #38771 from SpaceFox/38721_virtualthreadunit

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)