From f8e7911a26188cf24243371ae49d2089e62b4bb7 Mon Sep 17 00:00:00 2001
From: Ladislav Thon <lthon@redhat.com>
Date: Tue, 1 Oct 2024 11:38:51 +0200
Subject: [PATCH] ArC: document InstanceHandle.close() behavior

---
 docs/src/main/asciidoc/cdi-reference.adoc     | 22 +++++++++++++++++++
 .../java/io/quarkus/arc/InstanceHandle.java   |  4 +++-
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/docs/src/main/asciidoc/cdi-reference.adoc b/docs/src/main/asciidoc/cdi-reference.adoc
index 67471a947175f..69d4c96b9525b 100644
--- a/docs/src/main/asciidoc/cdi-reference.adoc
+++ b/docs/src/main/asciidoc/cdi-reference.adoc
@@ -1331,6 +1331,28 @@ public void register(RegistrationContext context) {
 
 <1> The argument is the bindings source class.
 
+=== `Instance.Handle.close()` Behavior
+
+Per the CDI specification, the `Instance.Handle.close()` method always delegates to `destroy()`.
+In ArC, this is only true in the <<strict_mode>>.
+
+In the default mode, the `close()` method only delegates to `destroy()` when the bean is `@Dependent` (or when the instance handle does not represent a CDI contextual object).
+When the instance handle represents a bean of any other scope, the `close()` method does nothing; the bean is left as is and will be destroyed whenever its context is destroyed.
+
+This is to make the following code behave as one would naively expect:
+
+[source,java]
+----
+Instance<T> instance = ...;
+try (Instance.Handle<T> handle : instance.getHandle()) {
+   T value = handle.get();
+   ... use value ...
+}
+----
+
+The `@Dependent` beans are destroyed immediately, while other beans are not destroyed at all.
+This is important when multiple beans of different scopes might be returned by the `Instance`.
+
 [[reactive_pitfalls]]
 == Pitfalls with Reactive Programming
 
diff --git a/independent-projects/arc/runtime/src/main/java/io/quarkus/arc/InstanceHandle.java b/independent-projects/arc/runtime/src/main/java/io/quarkus/arc/InstanceHandle.java
index dbca61638c8d1..27e5794fbe6a3 100644
--- a/independent-projects/arc/runtime/src/main/java/io/quarkus/arc/InstanceHandle.java
+++ b/independent-projects/arc/runtime/src/main/java/io/quarkus/arc/InstanceHandle.java
@@ -61,10 +61,12 @@ default InjectableBean<T> getBean() {
     /**
      * Delegates to {@link #destroy()} if the handle does not represent a CDI contextual instance or if it represents a
      * {@link Dependent} CDI contextual instance.
+     * <p>
+     * Note that in the strict compatibility mode, this method delegates to {@link #destroy()} always,
+     * for compatibility with the CDI specification.
      */
     @Override
     default void close() {
-        // https://github.com/quarkusio/quarkus/issues/33665
         if (Arc.container().strictCompatibility()) {
             destroy();
             return;