Merge pull request #25616 from JuliaLang/aa/stop-exporting-gc-stuff

Move gc and gc_enable to their own module

Author: JeffBezanson

NEWS.md

@@ -966,6 +966,10 @@ 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]).
+
+  * `Base.@gc_preserve` has been deprecated in favor of `GC.@preserve` ([#25616]).
+
 Command-line option changes
 ---------------------------
 
@@ -1217,3 +1221,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/compiler/optimize.jl

@@ -3091,7 +3091,7 @@ function split_struct_alloc!(ctx::AllocOptContext, info, key)
     #     Requires all conditions for `getfield`.
     #     Additionally require all defs to be mutable.
     #
-    # * preserved objects (`@gc_preserve` and `ccall` roots)
+    # * preserved objects (`GC.@preserve` and `ccall` roots)
     #
     #     No `setfield!` should be called for mutable defs on the NULL sites.
     #     This is because it's currently unclear how conditional undefined root slots

base/deepcopy.jl

@@ -46,7 +46,7 @@ function deepcopy_internal(x::String, stackdict::IdDict)
     if haskey(stackdict, x)
         return stackdict[x]
     end
-    y = @gc_preserve x unsafe_string(pointer(x), sizeof(x))
+    y = GC.@preserve x unsafe_string(pointer(x), sizeof(x))
     stackdict[x] = y
     return y
 end

base/deprecated.jl

@@ -1573,6 +1573,10 @@ end
 
 @deprecate object_id objectid
 
+@deprecate gc GC.gc
+@deprecate gc_enable GC.enable
+@eval @deprecate $(Symbol("@gc_preserve")) GC.$(Symbol("@preserve")) false
+
 # issue #9053
 if Sys.iswindows()
 function Filesystem.tempname(uunique::UInt32)

base/env.jl

@@ -97,7 +97,7 @@ if Sys.iswindows()
         blk = block[2]
         len = ccall(:wcslen, UInt, (Ptr{UInt16},), pos)
         buf = Vector{UInt16}(uninitialized, len)
-        @gc_preserve buf unsafe_copyto!(pointer(buf), pos, len)
+        GC.@preserve buf unsafe_copyto!(pointer(buf), pos, len)
         env = transcode(String, buf)
         m = match(r"^(=?[^=]+)=(.*)$"s, env)
         if m === nothing

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,51 @@ 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
+
+"""
+    GC.@preserve x1 x2 ... xn expr
+
+Temporarily protect the given objects from being garbage collected, even if they would
+otherwise be unreferenced.
+
+The last argument is the expression during which the object(s) will be preserved.
+The previous arguments are the objects to preserve.
+"""
+macro preserve(args...)
+    syms = args[1:end-1]
+    for x in syms
+        isa(x, Symbol) || error("Preserved variable must be a symbol")
+    end
+    s, r = gensym(), gensym()
+    esc(quote
+        $s = $(Expr(:gc_preserve_begin, syms...))
+        $r = $(args[end])
+        $(Expr(:gc_preserve_end, s))
+        $r
+    end)
+end
+
+end # module GC

base/gmp.jl

@@ -253,7 +253,7 @@ function tryparse_internal(::Type{BigInt}, s::AbstractString, startpos::Int, end
     if Base.containsnul(bstr)
         err = -1 # embedded NUL char (not handled correctly by GMP)
     else
-        err = Base.@gc_preserve bstr MPZ.set_str!(z, pointer(bstr)+(i-start(bstr)), base)
+        err = GC.@preserve bstr MPZ.set_str!(z, pointer(bstr)+(i-start(bstr)), base)
     end
     if err != 0
         raise && throw(ArgumentError("invalid BigInt: $(repr(bstr))"))
@@ -613,7 +613,7 @@ function base(b::Integer, n::BigInt, pad::Integer=1)
     nd1 = ndigits(n, b)
     nd  = max(nd1, pad)
     sv  = Base.StringVector(nd + isneg(n))
-    Base.@gc_preserve sv MPZ.get_str!(pointer(sv) + nd - nd1, b, n)
+    GC.@preserve sv MPZ.get_str!(pointer(sv) + nd - nd1, b, n)
     @inbounds for i = (1:nd-nd1) .+ isneg(n)
         sv[i] = '0' % UInt8
     end

base/io.jl

@@ -404,7 +404,7 @@ readlines(s=STDIN; chomp::Bool=true) = collect(eachline(s, chomp=chomp))
 ## byte-order mark, ntoh & hton ##
 
 let a = UInt32[0x01020304]
-    endian_bom = @gc_preserve a unsafe_load(convert(Ptr{UInt8}, pointer(a)))
+    endian_bom = GC.@preserve a unsafe_load(convert(Ptr{UInt8}, pointer(a)))
     global ntoh, hton, ltoh, htol
     if endian_bom == 0x01
         ntoh(x) = x
@@ -517,7 +517,7 @@ end
 
 function write(s::IO, a::Array)
     if isbits(eltype(a))
-        return @gc_preserve a unsafe_write(s, pointer(a), sizeof(a))
+        return GC.@preserve a unsafe_write(s, pointer(a), sizeof(a))
     else
         depwarn("Calling `write` on non-isbits arrays is deprecated. Use a loop or `serialize` instead.", :write)
         nb = 0
@@ -534,7 +534,7 @@ function write(s::IO, a::SubArray{T,N,<:Array}) where {T,N}
     end
     elsz = sizeof(T)
     colsz = size(a,1) * elsz
-    @gc_preserve a if stride(a,1) != 1
+    GC.@preserve a if stride(a,1) != 1
         for idxs in CartesianIndices(size(a))
             unsafe_write(s, pointer(a, idxs.I), elsz)
         end
@@ -585,13 +585,13 @@ read(s::IO, ::Type{Bool}) = (read(s, UInt8) != 0)
 read(s::IO, ::Type{Ptr{T}}) where {T} = convert(Ptr{T}, read(s, UInt))
 
 function read!(s::IO, a::Array{UInt8})
-    @gc_preserve a unsafe_read(s, pointer(a), sizeof(a))
+    GC.@preserve a unsafe_read(s, pointer(a), sizeof(a))
     return a
 end
 
 function read!(s::IO, a::Array{T}) where T
     if isbits(T)
-        @gc_preserve a unsafe_read(s, pointer(a), sizeof(a))
+        GC.@preserve a unsafe_read(s, pointer(a), sizeof(a))
     else
         for i in eachindex(a)
             a[i] = read(s, T)

base/iobuffer.jl

@@ -149,7 +149,7 @@ function unsafe_read(from::GenericIOBuffer, p::Ptr{UInt8}, nb::UInt)
     from.readable || throw(ArgumentError("read failed, IOBuffer is not readable"))
     avail = nb_available(from)
     adv = min(avail, nb)
-    @gc_preserve from unsafe_copyto!(p, pointer(from.data, from.ptr), adv)
+    GC.@preserve from unsafe_copyto!(p, pointer(from.data, from.ptr), adv)
     from.ptr += adv
     if nb > avail
         throw(EOFError())
@@ -164,7 +164,7 @@ function read_sub(from::GenericIOBuffer, a::AbstractArray{T}, offs, nel) where T
     end
     if isbits(T) && isa(a,Array)
         nb = UInt(nel * sizeof(T))
-        @gc_preserve a unsafe_read(from, pointer(a, offs), nb)
+        GC.@preserve a unsafe_read(from, pointer(a, offs), nb)
     else
         for i = offs:offs+nel-1
             a[i] = read(to, T)
@@ -395,7 +395,7 @@ function write_sub(to::GenericIOBuffer, a::AbstractArray{UInt8}, offs, nel)
     if offs+nel-1 > length(a) || offs < 1 || nel < 0
         throw(BoundsError())
     end
-    @gc_preserve a unsafe_write(to, pointer(a, offs), UInt(nel))
+    GC.@preserve a unsafe_write(to, pointer(a, offs), UInt(nel))
 end
 
 @inline function write(to::GenericIOBuffer, a::UInt8)
@@ -428,7 +428,7 @@ read(io::GenericIOBuffer, nb::Integer) = read!(io,StringVector(min(nb, nb_availa
 
 function findfirst(delim::EqualTo{UInt8}, buf::IOBuffer)
     p = pointer(buf.data, buf.ptr)
-    q = @gc_preserve buf ccall(:memchr,Ptr{UInt8},(Ptr{UInt8},Int32,Csize_t),p,delim.x,nb_available(buf))
+    q = GC.@preserve buf ccall(:memchr,Ptr{UInt8},(Ptr{UInt8},Int32,Csize_t),p,delim.x,nb_available(buf))
     q == C_NULL && return nothing
     return Int(q-p+1)
 end
@@ -474,7 +474,7 @@ function _crc32c(io::IOBuffer, nb::Integer, crc::UInt32=0x00000000)
     io.readable || throw(ArgumentError("read failed, IOBuffer is not readable"))
     n = min(nb, nb_available(io))
     n == 0 && return crc
-    crc = @gc_preserve io unsafe_crc32c(pointer(io.data, io.ptr), n, crc)
+    crc = GC.@preserve io unsafe_crc32c(pointer(io.data, io.ptr), n, crc)
     io.ptr += n
     return crc
 end