added words about aot/runtime target mismatch

fogus · fogus · commit 0f340a906cad · 2025-06-16T12:27:31.000-04:00
diff --git a/doc/vthreads.md b/doc/vthreads.md
@@ -35,3 +35,4 @@ Users can also set the Java system property `clojure.core.async.vthreads` to con
 - `"target"` - Always target virtual threads when compiling `go` blocks and require them at runtime in `io-thread` blocks
 - `"avoid"` - Always use IOC when compiling `go` blocks (will work regardless), and do not use virtual threads for `io-thread` blocks
 
+There is one circumstance that needs special attention. That is, users can choose to AOT compile their applications/libraries and target virtual threads using the `"target"` flag. However, users may run that compiled code on a JVM without virtual threads support. By using "target" to compile code, you've fixed an expectation of that the runtime environment support virtual threads. When users run compiled code targeting virtual threads in a runtime environment without them then `go` blocks will not guarantee non-blocking semantics anymore. In this particular circumstance, core.async will throw an error when the compiled `"target"` expectation does not match the runtime capability.

Original file line number	Diff line number	Diff line change
@@ -35,3 +35,4 @@ Users can also set the Java system property `clojure.core.async.vthreads` to con
`35`	`35`	- `"target"` - Always target virtual threads when compiling `go` blocks and require them at runtime in `io-thread` blocks
`36`	`36`	- `"avoid"` - Always use IOC when compiling `go` blocks (will work regardless), and do not use virtual threads for `io-thread` blocks
`37`	`37`
	`38`	+There is one circumstance that needs special attention. That is, users can choose to AOT compile their applications/libraries and target virtual threads using the `"target"` flag. However, users may run that compiled code on a JVM without virtual threads support. By using "target" to compile code, you've fixed an expectation of that the runtime environment support virtual threads. When users run compiled code targeting virtual threads in a runtime environment without them then `go` blocks will not guarantee non-blocking semantics anymore. In this particular circumstance, core.async will throw an error when the compiled `"target"` expectation does not match the runtime capability.