Skip to content

Commit 9a8599a

Browse files
simeonschaubaviatesk
authored andcommitted
add docs for getglobal and setglobal! (#48409)
closes #45480 Co-authored-by: Shuhei Kadowaki <[email protected]> (cherry picked from commit 0231c22)
1 parent 86fc8b6 commit 9a8599a

File tree

2 files changed

+78
-0
lines changed

2 files changed

+78
-0
lines changed

base/docs/basedocs.jl

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2205,6 +2205,82 @@ instruction, otherwise it'll use a loop.
22052205
"""
22062206
replacefield!
22072207

2208+
"""
2209+
getglobal(module::Module, name::Symbol, [order::Symbol=:monotonic])
2210+
2211+
Retrieve the value of the binding `name` from the module `module`. Optionally, an
2212+
atomic ordering can be defined for the operation, otherwise it defaults to
2213+
monotonic.
2214+
2215+
While accessing module bindings using [`getfield`](@ref) is still supported to
2216+
maintain compatibility, using `getglobal` should always be preferred since
2217+
`getglobal` allows for control over atomic ordering (`getfield` is always
2218+
monotonic) and better signifies the code's intent both to the user as well as the
2219+
compiler.
2220+
2221+
Most users should not have to call this function directly -- The
2222+
[`getproperty`](@ref Base.getproperty) function or corresponding syntax (i.e.
2223+
`module.name`) should be preferred in all but few very specific use cases.
2224+
2225+
!!! compat "Julia 1.9"
2226+
This function requires Julia 1.9 or later.
2227+
2228+
See also [`getproperty`](@ref Base.getproperty) and [`setglobal!`](@ref).
2229+
2230+
# Examples
2231+
```jldoctest
2232+
julia> a = 1
2233+
1
2234+
2235+
julia> module M
2236+
a = 2
2237+
end;
2238+
2239+
julia> getglobal(@__MODULE__, :a)
2240+
1
2241+
2242+
julia> getglobal(M, :a)
2243+
2
2244+
```
2245+
"""
2246+
getglobal
2247+
2248+
"""
2249+
setglobal!(module::Module, name::Symbol, x, [order::Symbol=:monotonic])
2250+
2251+
Set or change the value of the binding `name` in the module `module` to `x`. No
2252+
type conversion is performed, so if a type has already been declared for the
2253+
binding, `x` must be of appropriate type or an error is thrown.
2254+
2255+
Additionally, an atomic ordering can be specified for this operation, otherwise it
2256+
defaults to monotonic.
2257+
2258+
Users will typically access this functionality through the
2259+
[`setproperty!`](@ref Base.setproperty!) function or corresponding syntax
2260+
(i.e. `module.name = x`) instead, so this is intended only for very specific use
2261+
cases.
2262+
2263+
!!! compat "Julia 1.9"
2264+
This function requires Julia 1.9 or later.
2265+
2266+
See also [`setproperty!`](@ref Base.setproperty!) and [`getglobal`](@ref)
2267+
2268+
# Examples
2269+
```jldoctest
2270+
julia> module M end;
2271+
2272+
julia> M.a # same as `getglobal(M, :a)`
2273+
ERROR: UndefVarError: `a` not defined
2274+
2275+
julia> setglobal!(M, :a, 1)
2276+
1
2277+
2278+
julia> M.a
2279+
1
2280+
```
2281+
"""
2282+
setglobal!
2283+
22082284
"""
22092285
typeof(x)
22102286

doc/src/base/base.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,8 @@ Base.hasproperty
143143
Core.getfield
144144
Core.setfield!
145145
Core.isdefined
146+
Core.getglobal
147+
Core.setglobal!
146148
Base.@isdefined
147149
Base.convert
148150
Base.promote

0 commit comments

Comments
 (0)