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.

NEWS.md

@@ -966,6 +966,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
 ---------------------------
 
@@ -1217,3 +1219,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

@@ -1573,6 +1573,9 @@ end
 
 @deprecate object_id objectid
 
+@deprecate gc GC.gc
+@deprecate gc_enable GC.enable
+
 # issue #9053
 if Sys.iswindows()
 function Filesystem.tempname(uunique::UInt32)

base/exports.jl

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

base/gcutils.jl

@@ -38,18 +38,28 @@ Immediately run finalizers registered for object `x`.
 finalize(@nospecialize(o)) = ccall(:jl_finalize_th, Cvoid, (Ptr{Cvoid}, Any,),
                                    Core.getptls(), o)
 
+module 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

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

doc/src/manual/faq.md

@@ -10,7 +10,7 @@ session (technically, in module `Main`), it is always present.
 If memory usage is your concern, you can always replace objects with ones that consume less memory.
  For example, if `A` is a gigabyte-sized array that you no longer need, you can free the memory
 with `A = nothing`.  The memory will be released the next time the garbage collector runs; you can force
-this to happen with [`gc()`](@ref). Moreover, an attempt to use `A` will likely result in an error, because most methods are not defined on type `Nothing`.
+this to happen with [`gc()`](@ref Base.GC.gc). Moreover, an attempt to use `A` will likely result in an error, because most methods are not defined on type `Nothing`.
 
 ### How can I modify the declaration of a type in my session?
 

stdlib/FileWatching/test/runtests.jl

@@ -144,7 +144,7 @@ end
 end
 let a = Ref(0)
     make_unrooted_timer(a)
-    gc()
+    GC.gc()
     @test a[] == 1
 end
 
@@ -161,8 +161,8 @@ function test_12992()
     close(pfw)
     pfw = PollingFileWatcher(@__FILE__, 0.01)
     close(pfw)
-    gc()
-    gc()
+    GC.gc()
+    GC.gc()
 end
 
 # Make sure multiple close is fine
@@ -176,8 +176,8 @@ function test2_12992()
     pfw = PollingFileWatcher(@__FILE__, 0.01)
     close(pfw)
     close(pfw)
-    gc()
-    gc()
+    GC.gc()
+    GC.gc()
 end
 
 test_12992()

stdlib/Mmap/test/runtests.jl

@@ -6,20 +6,20 @@ file = tempname()
 write(file, "Hello World\n")
 t = b"Hello World"
 @test Mmap.mmap(file, Array{UInt8,3}, (11,1,1)) == reshape(t,(11,1,1))
-gc(); gc()
+GC.gc(); GC.gc()
 @test Mmap.mmap(file, Array{UInt8,3}, (1,11,1)) == reshape(t,(1,11,1))
-gc(); gc()
+GC.gc(); GC.gc()
 @test Mmap.mmap(file, Array{UInt8,3}, (1,1,11)) == reshape(t,(1,1,11))
-gc(); gc()
+GC.gc(); GC.gc()
 @test Mmap.mmap(file, Array{UInt8,3}, (11,0,1)) == Array{UInt8}(uninitialized, (0,0,0))
 @test Mmap.mmap(file, Vector{UInt8}, (11,)) == t
-gc(); gc()
+GC.gc(); GC.gc()
 @test Mmap.mmap(file, Array{UInt8,2}, (1,11)) == t'
-gc(); gc()
+GC.gc(); GC.gc()
 @test Mmap.mmap(file, Array{UInt8,2}, (0,12)) == Array{UInt8}(uninitialized, (0,0))
 m = Mmap.mmap(file, Array{UInt8,3}, (1,2,1))
 @test m == reshape(b"He",(1,2,1))
-finalize(m); m=nothing; gc()
+finalize(m); m=nothing; GC.gc()
 
 # constructors
 @test length(@inferred Mmap.mmap(file)) == 12
@@ -45,7 +45,7 @@ s = open(file)
 @test length(@inferred Mmap.mmap(s, Vector{Int8}, 12, 0; shared=false)) == 12
 close(s)
 @test_throws ErrorException Mmap.mmap(file, Vector{Ref}) # must be bit-type
-gc(); gc()
+GC.gc(); GC.gc()
 
 s = open(f->f,file,"w")
 @test Mmap.mmap(file) == Vector{UInt8}() # requested len=0 on empty file
@@ -54,7 +54,7 @@ s = open(file, "r+")
 m = Mmap.mmap(s,Vector{UInt8},12)
 m[:] = b"Hello World\n"
 Mmap.sync!(m)
-close(s); finalize(m); m=nothing; gc()
+close(s); finalize(m); m=nothing; GC.gc()
 @test open(x->read(x, String),file) == "Hello World\n"
 
 s = open(file, "r")
@@ -71,39 +71,39 @@ close(s)
 for i = 0x01:0x0c
     @test length(Mmap.mmap(file, Vector{UInt8}, i)) == Int(i)
 end
-gc(); gc()
+GC.gc(); GC.gc()
 
 sz = filesize(file)
 s = open(file, "r+")
 m = Mmap.mmap(s, Vector{UInt8}, sz+1)
 @test length(m) == sz+1 # test growing
 @test m[end] == 0x00
-close(s); finalize(m); m=nothing; gc()
+close(s); finalize(m); m=nothing; GC.gc()
 sz = filesize(file)
 s = open(file, "r+")
 m = Mmap.mmap(s, Vector{UInt8}, 1, sz)
 @test length(m) == 1
 @test m[1] == 0x00
-close(s); finalize(m); m=nothing; gc()
+close(s); finalize(m); m=nothing; GC.gc()
 sz = filesize(file)
 # test where offset is actually > than size of file; file is grown with zeroed bytes
 s = open(file, "r+")
 m = Mmap.mmap(s, Vector{UInt8}, 1, sz+1)
 @test length(m) == 1
 @test m[1] == 0x00
-close(s); finalize(m); m=nothing; gc()
+close(s); finalize(m); m=nothing; GC.gc()
 
 s = open(file, "r")
 m = Mmap.mmap(s)
 @test_throws ReadOnlyMemoryError m[5] = UInt8('x') # tries to setindex! on read-only array
-finalize(m); m=nothing; gc()
+finalize(m); m=nothing; GC.gc()
 
 write(file, "Hello World\n")
 
 s = open(file, "r")
 m = Mmap.mmap(s)
 close(s)
-finalize(m); m=nothing; gc()
+finalize(m); m=nothing; GC.gc()
 m = Mmap.mmap(file)
 s = open(file, "r+")
 c = Mmap.mmap(s)
@@ -114,18 +114,18 @@ close(s)
 @test m[1] == UInt8('J')
 @test d[1] == UInt8('J')
 finalize(m); finalize(c); finalize(d)
-m=nothing; c=nothing; d=nothing; gc()
+m=nothing; c=nothing; d=nothing; GC.gc()
 
 write(file, "Hello World\n")
 
 s = open(file, "r")
 @test isreadonly(s) == true
 c = Mmap.mmap(s, Vector{UInt8}, (11,))
 @test c == b"Hello World"
-finalize(c); c=nothing; gc()
+finalize(c); c=nothing; GC.gc()
 c = Mmap.mmap(s, Vector{UInt8}, (UInt16(11),))
 @test c == b"Hello World"
-finalize(c); c=nothing; gc()
+finalize(c); c=nothing; GC.gc()
 @test_throws ArgumentError Mmap.mmap(s, Vector{UInt8}, (Int16(-11),))
 @test_throws ArgumentError Mmap.mmap(s, Vector{UInt8}, (typemax(UInt),))
 close(s)
@@ -139,22 +139,22 @@ s = open(file, "r")
 str = readline(s)
 close(s)
 @test startswith(str, "Hellx World")
-finalize(c); c=nothing; gc()
+finalize(c); c=nothing; GC.gc()
 
 c = Mmap.mmap(file)
 @test c == b"Hellx World\n"
-finalize(c); c=nothing; gc()
+finalize(c); c=nothing; GC.gc()
 c = Mmap.mmap(file, Vector{UInt8}, 3)
 @test c == b"Hel"
-finalize(c); c=nothing; gc()
+finalize(c); c=nothing; GC.gc()
 s = open(file, "r")
 c = Mmap.mmap(s, Vector{UInt8}, 6)
 @test c == b"Hellx "
 close(s)
-finalize(c); c=nothing; gc()
+finalize(c); c=nothing; GC.gc()
 c = Mmap.mmap(file, Vector{UInt8}, 5, 6)
 @test c == b"World"
-finalize(c); c=nothing; gc()
+finalize(c); c=nothing; GC.gc()
 
 s = open(file, "w")
 write(s, "Hello World\n")
@@ -167,7 +167,7 @@ for i = 1:12
     @test m[i] == tdata[i]
 end
 @test_throws BoundsError m[13]
-finalize(m); m=nothing; gc()
+finalize(m); m=nothing; GC.gc()
 
 m = Mmap.mmap(file,Vector{UInt8},6)
 @test m[1] == b"H"[1]
@@ -177,13 +177,13 @@ m = Mmap.mmap(file,Vector{UInt8},6)
 @test m[5] == b"o"[1]
 @test m[6] == b" "[1]
 @test_throws BoundsError m[7]
-finalize(m); m=nothing; gc()
+finalize(m); m=nothing; GC.gc()
 
 m = Mmap.mmap(file,Vector{UInt8},2,6)
 @test m[1] == b"W"[1]
 @test m[2] == b"o"[1]
 @test_throws BoundsError m[3]
-finalize(m); m = nothing; gc()
+finalize(m); m = nothing; GC.gc()
 
 s = open(file, "w")
 write(s, [0xffffffffffffffff,
@@ -214,7 +214,7 @@ b = Mmap.mmap(s, BitArray, (17,19))
 close(s)
 finalize(b); finalize(b0)
 b = nothing; b0 = nothing
-gc()
+GC.gc()
 
 open(file,"w") do f
     write(f,UInt64(1))
@@ -225,7 +225,7 @@ s = open(file, "r+")
 m = Mmap.mmap(s, BitArray, (72,))
 @test Base._check_bitarray_consistency(m)
 @test length(m) == 72
-close(s); finalize(m); m = nothing; gc()
+close(s); finalize(m); m = nothing; GC.gc()
 rm(file)
 
 # Mmap.mmap with an offset
@@ -249,7 +249,7 @@ A4 = Mmap.mmap(s, Matrix{Int}, (m,150), convert(Int64, (2+150*m)*sizeof(Int)))
 close(s)
 finalize(A2); finalize(A3); finalize(A4)
 A2 = A3 = A4 = nothing
-gc()
+GC.gc()
 rm(fname)
 
 # Mmap.Anonymous
@@ -289,17 +289,17 @@ n = similar(m, (2,2))
 n = similar(m, 12)
 @test length(n) == 12
 @test size(n) == (12,)
-finalize(m); m = nothing; gc()
+finalize(m); m = nothing; GC.gc()
 
 # test #14885
 file = tempname()
 touch(file)
 open(file, "r+") do s
     A = Mmap.mmap(s, Vector{UInt8}, (10,), 0)
     Mmap.sync!(A)
-    finalize(A); A = nothing; gc()
+    finalize(A); A = nothing; GC.gc()
     A = Mmap.mmap(s, Vector{UInt8}, (10,), 1)
     Mmap.sync!(A)
-    finalize(A); A = nothing; gc()
+    finalize(A); A = nothing; GC.gc()
 end
 rm(file)

stdlib/SharedArrays/test/runtests.jl

@@ -145,9 +145,9 @@ finalize(S)
 
 # call gc 3 times to avoid unlink: operation not permitted (EPERM) on Windows
 S = nothing
-@everywhere gc()
-@everywhere gc()
-@everywhere gc()
+@everywhere GC.gc()
+@everywhere GC.gc()
+@everywhere GC.gc()
 rm(fn); rm(fn2); rm(fn3)
 
 ### Utility functions
@@ -288,7 +288,7 @@ let
     id = a1.id
     aorig = nothing
     a1 = remotecall_fetch(fill!, id_other, a1, 1.0)
-    gc(); gc()
+    GC.gc(); GC.gc()
     a1 = remotecall_fetch(fill!, id_other, a1, 1.0)
     @test haskey(SharedArrays.sa_refs, id)
     finalize(a1)

stdlib/SparseArrays/test/sparse.jl

@@ -1214,7 +1214,7 @@ end
             times = Float64[0,0,0]
             best = [typemax(Float64), 0]
             for searchtype in [0, 1, 2]
-                gc()
+                GC.gc()
                 tres = @timed test_getindex_algs(S, I, J, searchtype)
                 res[searchtype+1] = tres[1]
                 times[searchtype+1] = tres[2]
@@ -1270,9 +1270,9 @@ end
     for I in IA
         Isorted = sort(I)
         for S in SA
-            gc()
+            GC.gc()
             ru = @timed S[I, J]
-            gc()
+            GC.gc()
             rs = @timed S[Isorted, Jsorted]
             if debug
                 @printf(" %7d | %7d | %7d | %4.2e | %4.2e | %4.2e | %4.2e |\n", round(Int,nnz(S)/S.n), length(I), length(J), rs[2], ru[2], rs[3], ru[3])

stdlib/SuiteSparse/test/cholmod.jl

@@ -625,7 +625,7 @@ end
     A = Float64[10 1 1 1; 1 10 0 0; 1 0 10 0; 1 0 0 10]
     @test sparse(cholfact(sparse(A))) ≈ A
 end
-gc()
+GC.gc()
 
 @testset "Issue 11747 - Wrong show method defined for FactorComponent" begin
     v = cholfact(sparse(Float64[ 10 1 1 1; 1 10 0 0; 1 0 10 0; 1 0 0 10])).L

test/ccall.jl

@@ -1295,7 +1295,7 @@ struct Bits22734 <: Abstract22734
     y::Float64
 end
 function cb22734(ptr::Ptr{Cvoid})
-    gc()
+    GC.gc()
     obj = unsafe_pointer_to_objref(ptr)::Bits22734
     obj.x + obj.y
 end