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

Move gc and gc_enable to their own module

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

base/iostream.jl

@@ -373,7 +373,7 @@ end
 function readbytes_all!(s::IOStream, b::Array{UInt8}, nb)
     olb = lb = length(b)
     nr = 0
-    @gc_preserve b while nr < nb
+    GC.@preserve b while nr < nb
         if lb < nr+1
             lb = max(65536, (nr+1) * 2)
             resize!(b, lb)
@@ -393,7 +393,7 @@ function readbytes_some!(s::IOStream, b::Array{UInt8}, nb)
     if nb > lb
         resize!(b, nb)
     end
-    nr = @gc_preserve b Int(ccall(:ios_read, Csize_t, (Ptr{Cvoid}, Ptr{Cvoid}, Csize_t),
+    nr = GC.@preserve b Int(ccall(:ios_read, Csize_t, (Ptr{Cvoid}, Ptr{Cvoid}, Csize_t),
                                   s.ios, pointer(b), nb))
     if lb > olb && lb > nr
         resize!(b, nr)

base/libc.jl

@@ -251,7 +251,7 @@ function gethostname()
         ccall(:gethostname, Int32, (Ptr{UInt8}, UInt), hn, length(hn))
     end
     systemerror("gethostname", err != 0)
-    return Base.@gc_preserve hn unsafe_string(pointer(hn))
+    return GC.@preserve hn unsafe_string(pointer(hn))
 end
 
 ## system error handling ##
@@ -307,7 +307,7 @@ if Sys.iswindows()
         p = lpMsgBuf[]
         len == 0 && return ""
         buf = Vector{UInt16}(uninitialized, len)
-        Base.@gc_preserve buf unsafe_copyto!(pointer(buf), p, len)
+        GC.@preserve buf unsafe_copyto!(pointer(buf), p, len)
         ccall(:LocalFree, stdcall, Ptr{Cvoid}, (Ptr{Cvoid},), p)
         return transcode(String, buf)
     end

base/libgit2/blame.jl

@@ -32,7 +32,7 @@ function Base.getindex(blame::GitBlame, i::Integer)
     if !(1 <= i <= counthunks(blame))
         throw(BoundsError(blame, (i,)))
     end
-    Base.@gc_preserve blame begin
+    GC.@preserve blame begin
         hunk_ptr = ccall((:git_blame_get_hunk_byindex, :libgit2),
                           Ptr{BlameHunk},
                           (Ptr{Cvoid}, Csize_t), blame.ptr, i-1)

base/libgit2/commit.jl

@@ -9,7 +9,7 @@ leading newlines removed). If `raw` is `true`, the message is not stripped
 of any such newlines.
 """
 function message(c::GitCommit, raw::Bool=false)
-    Base.@gc_preserve c begin
+    GC.@preserve c begin
         local msg_ptr::Cstring
         msg_ptr = raw ? ccall((:git_commit_message_raw, :libgit2), Cstring, (Ptr{Cvoid},), c.ptr) :
                         ccall((:git_commit_message, :libgit2), Cstring, (Ptr{Cvoid},), c.ptr)
@@ -28,7 +28,7 @@ Return the `Signature` of the author of the commit `c`. The author is
 the person who made changes to the relevant file(s). See also [`committer`](@ref).
 """
 function author(c::GitCommit)
-    Base.@gc_preserve c begin
+    GC.@preserve c begin
         ptr = ccall((:git_commit_author, :libgit2), Ptr{SignatureStruct}, (Ptr{Cvoid},), c.ptr)
         @assert ptr != C_NULL
         sig = Signature(ptr)
@@ -45,7 +45,7 @@ need not be the same as the `author`, for example, if the `author` emailed a pat
 a `committer` who committed it.
 """
 function committer(c::GitCommit)
-    Base.@gc_preserve c begin
+    GC.@preserve c begin
         ptr = ccall((:git_commit_committer, :libgit2), Ptr{SignatureStruct}, (Ptr{Cvoid},), c.ptr)
         sig = Signature(ptr)
     end

base/libgit2/index.jl

@@ -168,7 +168,7 @@ function Base.count(idx::GitIndex)
 end
 
 function Base.getindex(idx::GitIndex, i::Integer)
-    Base.@gc_preserve idx begin
+    GC.@preserve idx begin
         ie_ptr = ccall((:git_index_get_byindex, :libgit2),
                        Ptr{IndexEntry},
                        (Ptr{Cvoid}, Csize_t), idx.ptr, i-1)

base/libgit2/libgit2.jl

@@ -525,7 +525,7 @@ function clone(repo_url::AbstractString, repo_path::AbstractString;
                payload::Union{CredentialPayload, AbstractCredential, CachedCredentials, Nothing}=CredentialPayload())
     # setup clone options
     lbranch = Base.cconvert(Cstring, branch)
-    @Base.gc_preserve lbranch begin
+    GC.@preserve lbranch begin
         p = reset!(deprecate_nullable_creds(:clone, "repo_url, repo_path", payload))
         fetch_opts = FetchOptions(callbacks = RemoteCallbacks(credentials=credentials_cb(), payload=p))
         clone_opts = CloneOptions(

base/libgit2/merge.jl

@@ -44,7 +44,7 @@ function GitAnnotated(repo::GitRepo, comittish::AbstractString)
 end
 
 function GitHash(ann::GitAnnotated)
-    Base.@gc_preserve ann begin
+    GC.@preserve ann begin
         oid = unsafe_load(ccall((:git_annotated_commit_id, :libgit2), Ptr{GitHash}, (Ptr{Cvoid},), ann.ptr))
     end
     return oid

base/libgit2/oid.jl

@@ -106,7 +106,7 @@ Get the identifier (`GitHash`) of the object referred to by the direct reference
 function GitHash(ref::GitReference)
     isempty(ref) && return GitHash()
     reftype(ref) != Consts.REF_OID && return GitHash()
-    Base.@gc_preserve ref begin
+    GC.@preserve ref begin
         oid_ptr = ccall((:git_reference_target, :libgit2), Ptr{UInt8}, (Ptr{Cvoid},), ref.ptr)
         oid_ptr == C_NULL && return GitHash()
         oid = GitHash(oid_ptr)

base/libgit2/rebase.jl

@@ -32,7 +32,7 @@ function Base.getindex(rb::GitRebase, i::Integer)
     if !(1 <= i <= count(rb))
         throw(BoundsError(rb, (i,)))
     end
-    Base.@gc_preserve rb begin
+    GC.@preserve rb begin
         rb_op_ptr = ccall((:git_rebase_operation_byindex, :libgit2),
                           Ptr{RebaseOperation},
                           (Ptr{Cvoid}, Csize_t), rb.ptr, i-1)
@@ -43,7 +43,7 @@ end
 
 function Base.next(rb::GitRebase)
     rb_op_ptr_ptr = Ref{Ptr{RebaseOperation}}(C_NULL)
-    Base.@gc_preserve rb begin
+    GC.@preserve rb begin
         try
             @check ccall((:git_rebase_next, :libgit2), Cint,
                           (Ptr{Ptr{RebaseOperation}}, Ptr{Cvoid}),

base/libgit2/reference.jl

@@ -62,7 +62,7 @@ julia> LibGit2.shortname(branch_ref)
 """
 function shortname(ref::GitReference)
     isempty(ref) && return ""
-    Base.@gc_preserve ref begin
+    GC.@preserve ref begin
         name_ptr = ccall((:git_reference_shorthand, :libgit2), Cstring, (Ptr{Cvoid},), ref.ptr)
         name_ptr == C_NULL && return ""
         name = unsafe_string(name_ptr)
@@ -92,7 +92,7 @@ reference, return an empty string.
 function fullname(ref::GitReference)
     isempty(ref) && return ""
     reftype(ref) == Consts.REF_OID && return ""
-    Base.@gc_preserve ref begin
+    GC.@preserve ref begin
         rname = ccall((:git_reference_symbolic_target, :libgit2), Cstring, (Ptr{Cvoid},), ref.ptr)
         rname == C_NULL && return ""
         name = unsafe_string(rname)
@@ -107,7 +107,7 @@ Return the full name of `ref`.
 """
 function name(ref::GitReference)
     isempty(ref) && return ""
-    Base.@gc_preserve ref begin
+    GC.@preserve ref begin
         name_ptr = ccall((:git_reference_name, :libgit2), Cstring, (Ptr{Cvoid},), ref.ptr)
         name_ptr == C_NULL && return ""
         name = unsafe_string(name_ptr)
@@ -118,7 +118,7 @@ end
 function branch(ref::GitReference)
     isempty(ref) && return ""
     str_ptr_ptr = Ref{Cstring}()
-    Base.@gc_preserve ref begin
+    GC.@preserve ref begin
         @check ccall((:git_branch_name, :libgit2), Cint,
                       (Ptr{Cstring}, Ptr{Cvoid},), str_ptr_ptr, ref.ptr)
         str = unsafe_string(str_ptr_ptr[])