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.
JuliaLang · Jan 18, 2018 · aae96d0 · aae96d0
1 parent 86ca591
commit aae96d0
Show file tree

Hide file tree

Showing 21 changed files with 63 additions and 32 deletions.
diff --git a/NEWS.md b/NEWS.md
@@ -957,6 +957,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
 ---------------------------
 
@@ -1208,3 +1210,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
diff --git a/base/deprecated.jl b/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)

diff --git a/base/exports.jl b/base/exports.jl
@@ -903,10 +903,9 @@ export
     include_dependency,
 
 # RTS internals
+    GC,
     finalizer,
     finalize,
-    gc,
-    gc_enable,
     precompile,
 
 # misc

diff --git a/base/gcutils.jl b/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
diff --git a/doc/src/base/base.md b/doc/src/base/base.md
@@ -332,8 +332,8 @@ Base.@functionloc
 ## Internals
 
 ```@docs
-Base.gc
-Base.gc_enable
+Base.GC.gc
+Base.GC.enable
 Meta.lower
 Meta.@lower
 Meta.parse(::AbstractString, ::Int)

diff --git a/doc/src/manual/faq.md b/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?
 

diff --git a/stdlib/FileWatching/test/runtests.jl b/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

diff --git a/stdlib/Mmap/test/runtests.jl b/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")

diff --git a/stdlib/SharedArrays/test/runtests.jl b/stdlib/SharedArrays/test/runtests.jl
@@ -1,12 +1,12 @@
 # This file is a part of Julia. License is MIT: https://julialang.org/license
 
-using Test, Distributed, SharedArrays, Random
+using Test, Distributed, SharedArrays, Random, Base.GC
 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))]

diff --git a/stdlib/SparseArrays/test/sparse.jl b/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

diff --git a/stdlib/SuiteSparse/test/cholmod.jl b/stdlib/SuiteSparse/test/cholmod.jl
@@ -3,6 +3,7 @@
 using SuiteSparse.CHOLMOD
 using DelimitedFiles
 using Test
+using Base.GC
 
 # CHOLMOD tests
 srand(123)

diff --git a/test/ccall.jl b/test/ccall.jl
@@ -2,6 +2,7 @@
 
 import Base.copy, Base.==
 using Random
+using Base.GC
 
 import Libdl
 

diff --git a/test/channels.jl b/test/channels.jl
@@ -1,6 +1,7 @@
 # This file is a part of Julia. License is MIT: https://julialang.org/license
 
 using Random
+using Base.GC
 
 # Test various constructors
 let c = Channel(1)
@@ -232,13 +233,13 @@ end
 # test for yield/wait/event failures
 @noinline garbage_finalizer(f) = finalizer(f, "gar" * "bage")
 let t, run = Ref(0)
-    gc_enable(false)
+    GC.enable(false)
     # test for finalizers trying to yield leading to failed attempts to context switch
     garbage_finalizer((x) -> (run[] += 1; sleep(1)))
     garbage_finalizer((x) -> (run[] += 1; yield()))
     garbage_finalizer((x) -> (run[] += 1; yieldto(@task () -> ())))
     t = @task begin
-        gc_enable(true)
+        GC.enable(true)
         gc()
     end
     oldstderr = STDERR

diff --git a/test/codegen.jl b/test/codegen.jl
@@ -3,6 +3,7 @@
 # tests for codegen and optimizations
 
 using Random
+using Base.GC
 
 const opt_level = Base.JLOptions().opt_level
 const coverage = (Base.JLOptions().code_coverage > 0) || (Base.JLOptions().malloc_log > 0)

diff --git a/test/core.jl b/test/core.jl
@@ -2,11 +2,12 @@
 
 # test core language features
 
+using Base.GC
 using Random
+using SparseArrays
 
 const Bottom = Union{}
 
-using SparseArrays
 
 # For curmod_*
 include("testenv.jl")
@@ -4026,16 +4027,16 @@ end
 end
 # disable GC to make sure no collection/promotion happens
 # when we are constructing the objects
-let gc_enabled13995 = gc_enable(false)
+let gc_enabled13995 = GC.enable(false)
     finalized13995 = [false, false, false, false]
     create_dead_object13995(finalized13995)
-    gc_enable(true)
+    GC.enable(true)
     # obj is unreachable and young, a single young gc should collect it
     # and trigger all the finalizers.
     gc(false)
-    gc_enable(false)
+    GC.enable(false)
     @test finalized13995 == [true, true, true, true]
-    gc_enable(gc_enabled13995)
+    GC.enable(gc_enabled13995)
 end
 
 # issue #15283
@@ -4830,7 +4831,7 @@ end
 # issue #17255, take `deferred_alloc` into account
 # when calculating total allocation size.
 @noinline function f17255(n)
-    gc_enable(false)
+    GC.enable(false)
     b0 = Base.gc_bytes()
     local a
     for i in 1:n
@@ -4844,7 +4845,7 @@ end
     return true, a
 end
 @test f17255(10000)[1]
-gc_enable(true)
+GC.enable(true)
 
 # issue #18710
 bad_tvars() where {T} = 1

diff --git a/test/misc.jl b/test/misc.jl
@@ -1,5 +1,7 @@
 # This file is a part of Julia. License is MIT: https://julialang.org/license
 
+using Base.GC
+
 # Tests that do not really go anywhere else
 
 # test assert() method
@@ -83,12 +85,12 @@ let # test the process title functions, issue #9957
     @test Sys.get_process_title() == oldtitle
 end
 
-# test gc_enable/disable
-@test gc_enable(true)
-@test gc_enable(false)
-@test gc_enable(false) == false
-@test gc_enable(true) == false
-@test gc_enable(true)
+# test GC.enable/disable
+@test GC.enable(true)
+@test GC.enable(false)
+@test GC.enable(false) == false
+@test GC.enable(true) == false
+@test GC.enable(true)
 
 # test methodswith
 # `methodswith` relies on exported symbols
@@ -646,4 +648,4 @@ end
 module A
     export missing
     varinfo(A)
-end
+end
diff --git a/test/netload/memtest.jl b/test/netload/memtest.jl
@@ -1,5 +1,7 @@
 # This file is a part of Julia. License is MIT: https://julialang.org/license
 
+using Base.GC
+
 struct RUsage
     ru_utime_sec::Clong         #  user CPU time used
     ru_utime_usec::Clong        #  user CPU time used

diff --git a/test/perf/kernel/perf.jl b/test/perf/kernel/perf.jl
@@ -1,5 +1,7 @@
 # This file is a part of Julia. License is MIT: https://julialang.org/license
 
+using Base.GC
+
 include("../perfutil.jl")
 
 abstract type List{T} end

diff --git a/test/perf/perfutil.jl b/test/perf/perfutil.jl
@@ -1,6 +1,6 @@
 # This file is a part of Julia. License is MIT: https://julialang.org/license
 
-using Printf, Random
+using Printf, Random, Base.GC
 
 const mintrials = 5
 const mintime = 2000.0

diff --git a/test/perf/sort/perf.jl b/test/perf/sort/perf.jl
@@ -1,5 +1,6 @@
 # This file is a part of Julia. License is MIT: https://julialang.org/license
 
+using Base.GC
 import Base.Sort: QuickSort, MergeSort, InsertionSort
 
 Pkg.add("SortingAlgorithms")

diff --git a/test/threads.jl b/test/threads.jl
@@ -2,6 +2,7 @@
 
 using Test
 using Base.Threads
+using Base.GC
 
 # threading constructs