Deprecate gc and gc_enable in favor of GC.gc and GC.enable

We document that these functions should not generally be used, and yet
they're exported from Base. This moves the two functions into their own
submodule, Base.GC, and deprecates the exported functions.

Author: ararslan

NEWS.md

@@ -954,6 +954,8 @@ Deprecated or removed
 
   * `ObjectIdDict` has been deprecated in favor of `IdDict{Any,Any}` ([#25210]).
 
+  * `gc` and `gc_enable` have been deprecated in favor of `GC.gc` and `GC.enable` ([#25616]).
+
 Command-line option changes
 ---------------------------
 
@@ -1205,3 +1207,4 @@ Command-line option changes
 [#25424]: https://github.com/JuliaLang/julia/issues/25424
 [#25532]: https://github.com/JuliaLang/julia/issues/25532
 [#25545]: https://github.com/JuliaLang/julia/issues/25545
+[#25616]: https://github.com/JuliaLang/julia/issues/25616

base/deprecated.jl

@@ -2794,6 +2794,9 @@ end
 @deprecate findn(x::AbstractMatrix) (I = findall(!iszero, x); (getindex.(I, 1), getindex.(I, 2)))
 @deprecate findn(x::AbstractArray{T, N}) where {T, N} (I = findall(!iszero, x); ntuple(i -> getindex.(I, i), N))
 
+@deprecate gc GC.gc
+@deprecate gc_enable GC.enable
+
 # issue #9053
 if Sys.iswindows()
 function Filesystem.tempname(uunique::UInt32)

base/exports.jl

@@ -902,10 +902,9 @@ export
     include_dependency,
 
 # RTS internals
+    GC,
     finalizer,
     finalize,
-    gc,
-    gc_enable,
     precompile,
 
 # misc

base/gcutils.jl

@@ -38,18 +38,30 @@ Immediately run finalizers registered for object `x`.
 finalize(@nospecialize(o)) = ccall(:jl_finalize_th, Cvoid, (Ptr{Cvoid}, Any,),
                                    Core.getptls(), o)
 
+module GC
+
+export gc
+
 """
-    gc()
+    GC.gc()
+
+Perform garbage collection.
 
-Perform garbage collection. This should not generally be used.
+!!! warning
+    Excessive use will likely lead to poor performance.
 """
 gc(full::Bool=true) = ccall(:jl_gc_collect, Cvoid, (Int32,), full)
 
 """
-    gc_enable(on::Bool)
+    GC.enable(on::Bool)
 
 Control whether garbage collection is enabled using a boolean argument (`true` for enabled,
-`false` for disabled). Return previous GC state. Disabling garbage collection should be
-used only with extreme caution, as it can cause memory use to grow without bound.
+`false` for disabled). Return previous GC state.
+
+!!! warning
+    Disabling garbage collection should be used only with caution, as it can cause memory
+    use to grow without bound.
 """
-gc_enable(on::Bool) = ccall(:jl_gc_enable, Int32, (Int32,), on) != 0
+enable(on::Bool) = ccall(:jl_gc_enable, Int32, (Int32,), on) != 0
+
+end # module GC

doc/src/base/base.md

@@ -331,8 +331,8 @@ Base.@functionloc
 ## Internals
 
 ```@docs
-Base.gc
-Base.gc_enable
+Base.GC.gc
+Base.GC.enable
 Meta.lower
 Meta.@lower
 Meta.parse(::AbstractString, ::Int)

stdlib/FileWatching/test/runtests.jl

@@ -1,6 +1,6 @@
 # This file is a part of Julia. License is MIT: https://julialang.org/license
 
-using Test, FileWatching
+using Test, FileWatching, Base.GC
 
 # This script does the following
 # Sets up n unix pipes

stdlib/Mmap/test/runtests.jl

@@ -1,6 +1,6 @@
 # This file is a part of Julia. License is MIT: https://julialang.org/license
 
-using Test, Mmap, Random
+using Test, Mmap, Random, Base.GC
 
 file = tempname()
 write(file, "Hello World\n")

stdlib/SharedArrays/test/runtests.jl

@@ -6,7 +6,7 @@ include(joinpath(Sys.BINDIR, "..", "share", "julia", "test", "testenv.jl"))
 addprocs_with_testenv(4)
 @test nprocs() == 5
 
-@everywhere using Test, SharedArrays
+@everywhere using Test, SharedArrays, Base.GC
 
 id_me = myid()
 id_other = filter(x -> x != id_me, procs())[rand(1:(nprocs()-1))]

stdlib/SparseArrays/test/sparse.jl

@@ -2,6 +2,7 @@
 
 using Base.LinAlg: mul!, ldiv!, rdiv!
 using Base.Printf: @printf
+using Base.GC
 using Random
 
 @testset "issparse" begin

stdlib/SuiteSparse/test/cholmod.jl

@@ -3,6 +3,7 @@
 using SuiteSparse.CHOLMOD
 using DelimitedFiles
 using Test
+using Base.GC
 
 # CHOLMOD tests
 srand(123)