Skip to content

Commit

Permalink
Document WeakRef
Browse files Browse the repository at this point in the history
Fixes #26745. Based on suggestion by @stevengj (#26745 (comment)).
  • Loading branch information
simonbyrne committed Feb 6, 2023
1 parent 8860d95 commit de3ca59
Show file tree
Hide file tree
Showing 3 changed files with 34 additions and 0 deletions.
31 changes: 31 additions & 0 deletions base/gcutils.jl
Original file line number Diff line number Diff line change
@@ -1,5 +1,36 @@
# This file is a part of Julia. License is MIT: https://julialang.org/license


"""
WeakRef(x)
`w = WeakRef(x)` constructs a [weak reference](https://en.wikipedia.org/wiki/Weak_reference)
to the Julia value `x`: although `w` contains a reference to `x`, it does not prevent `x` from being
garbage collected. `w.value` is either `x` (if `x` has not been garbage-collected yet) or `nothing`
(if `x` has been garbage-collected).
```jldoctest
julia> x = "a string"
"a string"
julia> w = WeakRef(x)
WeakRef("a string")
julia> GC.gc()
julia> w # a reference is maintained via `x`
WeakRef("a string")
julia> x = nothing # clear reference
julia> GC.gc()
julia> w
WeakRef(nothing)
```
"""
WeakRef

==(w::WeakRef, v::WeakRef) = isequal(w.value, v.value)
==(w::WeakRef, v) = isequal(w.value, v)
==(w, v::WeakRef) = isequal(w, v.value)
Expand Down
2 changes: 2 additions & 0 deletions base/weakkeydict.jl
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ referenced in a hash table.
See [`Dict`](@ref) for further help. Note, unlike [`Dict`](@ref),
`WeakKeyDict` does not convert keys on insertion, as this would imply the key
object was unreferenced anywhere before insertion.
See also [`WeakRef`](@ref).
"""
mutable struct WeakKeyDict{K,V} <: AbstractDict{K,V}
ht::Dict{WeakRef,V}
Expand Down
1 change: 1 addition & 0 deletions doc/src/base/base.md
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,7 @@ Base.promote
Base.oftype
Base.widen
Base.identity
Base.WeakRef
```

## Properties of Types
Expand Down

0 comments on commit de3ca59

Please sign in to comment.