From 0ddba1572f70e39505c291e6ca682cbc75123de1 Mon Sep 17 00:00:00 2001
From: Tim Holy <tim.holy@gmail.com>
Date: Sun, 24 Oct 2021 21:04:41 -0500
Subject: [PATCH] Restore `@force_compile` docs & test (#42785)

* Revert "Revert "Fix docs for `Experimental.@force_compile` (#42760)" (#42784)"

This reverts commit dad40711c1bc27b24b01d9ac883929d145149b99.

* Truncate test harness from stacktrace
---
 base/experimental.jl | 23 ++++++++++++-----------
 test/core.jl         | 18 ++++++++++++++++++
 2 files changed, 30 insertions(+), 11 deletions(-)

diff --git a/base/experimental.jl b/base/experimental.jl
index 2833737f332e3..f5f81ee40b85e 100644
--- a/base/experimental.jl
+++ b/base/experimental.jl
@@ -170,17 +170,18 @@ Force compilation of the block or function (Julia's built-in interpreter is bloc
 # Examples
 
 ```
-module WithPrecompiles
-#=
-    code definitions
-=#
-
-if Sys.iswindows()
-    Experimental.@compile
-    compile_me()  # `compile_me` will be compiled before execution
-end
-
-end
+julia> occursin("interpreter", string(stacktrace(begin
+           # with forced compilation
+           Base.Experimental.@force_compile
+           backtrace()
+       end, true)))
+false
+
+julia> occursin("interpreter", string(stacktrace(begin
+           # without forced compilation
+           backtrace()
+       end, true)))
+true
 ```
 """
 macro force_compile() Expr(:meta, :force_compile) end
diff --git a/test/core.jl b/test/core.jl
index 5c3196431c6ab..07d90378a35be 100644
--- a/test/core.jl
+++ b/test/core.jl
@@ -7589,3 +7589,21 @@ end
 
 # avoid impossible normalization (don't try to form Tuple{Complex{String}} here)
 @test Tuple{Complex{T} where String<:T<:String} == Tuple{Complex{T} where String<:T<:String}
+
+# control over compilation/interpreter
+@testset "Experimental.@force_compile" begin
+    function trim_after_eval(str::AbstractString)
+        rng = findfirst("eval(", str)
+        @test !isempty(rng)
+        return str[1:first(rng)-1]
+    end
+    btc = eval(quote
+        Base.Experimental.@force_compile
+        backtrace()
+    end)
+    bti = eval(quote
+        backtrace()
+    end)
+    @test !occursin(r"(interpreter|do_call)", trim_after_eval(string(stacktrace(btc, true))))
+    @test  occursin(r"(interpreter|do_call)", trim_after_eval(string(stacktrace(bti, true))))
+end