|
| 1 | +# This file is a part of Julia. License is MIT: https://julialang.org/license |
| 2 | + |
| 3 | +module ScopedValues |
| 4 | + |
| 5 | +export ScopedValue, with, @with |
| 6 | + |
| 7 | +""" |
| 8 | + ScopedValue(x) |
| 9 | +
|
| 10 | +Create a container that propagates values across dynamic scopes. |
| 11 | +Use [`with`](@ref) to create and enter a new dynamic scope. |
| 12 | +
|
| 13 | +Values can only be set when entering a new dynamic scope, |
| 14 | +and the value referred to will be constant during the |
| 15 | +execution of a dynamic scope. |
| 16 | +
|
| 17 | +Dynamic scopes are propagated across tasks. |
| 18 | +
|
| 19 | +# Examples |
| 20 | +
|
| 21 | +```jldoctest |
| 22 | +julia> const sval = ScopedValue(1); |
| 23 | +
|
| 24 | +julia> sval[] |
| 25 | +1 |
| 26 | +
|
| 27 | +julia> with(sval => 2) do |
| 28 | + sval[] |
| 29 | + end |
| 30 | +2 |
| 31 | +
|
| 32 | +julia> sval[] |
| 33 | +1 |
| 34 | +``` |
| 35 | +
|
| 36 | +!!! compat "Julia 1.11" |
| 37 | + Scoped values were introduced in Julia 1.11. In Julia 1.8+ a compatible |
| 38 | + implementation is available from the package ScopedValues.jl. |
| 39 | +""" |
| 40 | +mutable struct ScopedValue{T} |
| 41 | + const has_default::Bool |
| 42 | + const default::T |
| 43 | + ScopedValue{T}() where T = new(false) |
| 44 | + ScopedValue{T}(val) where T = new{T}(true, val) |
| 45 | + ScopedValue(val::T) where T = new{T}(true, val) |
| 46 | +end |
| 47 | + |
| 48 | +Base.eltype(::ScopedValue{T}) where {T} = T |
| 49 | + |
| 50 | +""" |
| 51 | + isassigned(val::ScopedValue) |
| 52 | +
|
| 53 | +Test if the ScopedValue has a default value. |
| 54 | +""" |
| 55 | +Base.isassigned(val::ScopedValue) = val.has_default |
| 56 | + |
| 57 | +const ScopeStorage = Base.PersistentDict{ScopedValue, Any} |
| 58 | + |
| 59 | +mutable struct Scope |
| 60 | + values::ScopeStorage |
| 61 | +end |
| 62 | + |
| 63 | +function Scope(parent::Union{Nothing, Scope}, key::ScopedValue{T}, value) where T |
| 64 | + val = convert(T, value) |
| 65 | + if parent === nothing |
| 66 | + return Scope(ScopeStorage(key=>val)) |
| 67 | + end |
| 68 | + return Scope(ScopeStorage(parent.values, key=>val)) |
| 69 | +end |
| 70 | + |
| 71 | +function Scope(scope, pairs::Pair{<:ScopedValue}...) |
| 72 | + for pair in pairs |
| 73 | + scope = Scope(scope, pair...) |
| 74 | + end |
| 75 | + return scope::Scope |
| 76 | +end |
| 77 | +Scope(::Nothing) = nothing |
| 78 | + |
| 79 | +""" |
| 80 | + current_scope()::Union{Nothing, Scope} |
| 81 | +
|
| 82 | +Return the current dynamic scope. |
| 83 | +""" |
| 84 | +current_scope() = current_task().scope::Union{Nothing, Scope} |
| 85 | + |
| 86 | +function Base.show(io::IO, scope::Scope) |
| 87 | + print(io, Scope, "(") |
| 88 | + first = true |
| 89 | + for (key, value) in scope.values |
| 90 | + if first |
| 91 | + first = false |
| 92 | + else |
| 93 | + print(io, ", ") |
| 94 | + end |
| 95 | + print(io, typeof(key), "@") |
| 96 | + show(io, Base.objectid(key)) |
| 97 | + print(io, " => ") |
| 98 | + show(IOContext(io, :typeinfo => eltype(key)), value) |
| 99 | + end |
| 100 | + print(io, ")") |
| 101 | +end |
| 102 | + |
| 103 | +struct NoValue end |
| 104 | +const novalue = NoValue() |
| 105 | + |
| 106 | +""" |
| 107 | + get(val::ScopedValue{T})::Union{Nothing, Some{T}} |
| 108 | +
|
| 109 | +If the scoped value isn't set and doesn't have a default value, |
| 110 | +return `nothing`. Otherwise returns `Some{T}` with the current |
| 111 | +value. |
| 112 | +""" |
| 113 | +function get(val::ScopedValue{T}) where {T} |
| 114 | + # Inline current_scope to avoid doing the type assertion twice. |
| 115 | + scope = current_task().scope |
| 116 | + if scope === nothing |
| 117 | + isassigned(val) && return Some(val.default) |
| 118 | + return nothing |
| 119 | + end |
| 120 | + scope = scope::Scope |
| 121 | + if isassigned(val) |
| 122 | + return Some(Base.get(scope.values, val, val.default)::T) |
| 123 | + else |
| 124 | + v = Base.get(scope.values, val, novalue) |
| 125 | + v === novalue || return Some(v::T) |
| 126 | + end |
| 127 | + return nothing |
| 128 | +end |
| 129 | + |
| 130 | +function Base.getindex(val::ScopedValue{T})::T where T |
| 131 | + maybe = get(val) |
| 132 | + maybe === nothing && throw(KeyError(val)) |
| 133 | + return something(maybe)::T |
| 134 | +end |
| 135 | + |
| 136 | +function Base.show(io::IO, val::ScopedValue) |
| 137 | + print(io, ScopedValue) |
| 138 | + print(io, '{', eltype(val), '}') |
| 139 | + print(io, '(') |
| 140 | + v = get(val) |
| 141 | + if v === nothing |
| 142 | + print(io, "undefined") |
| 143 | + else |
| 144 | + show(IOContext(io, :typeinfo => eltype(val)), something(v)) |
| 145 | + end |
| 146 | + print(io, ')') |
| 147 | +end |
| 148 | + |
| 149 | +""" |
| 150 | + with(f, (var::ScopedValue{T} => val::T)...) |
| 151 | +
|
| 152 | +Execute `f` in a new scope with `var` set to `val`. |
| 153 | +""" |
| 154 | +function with(f, pair::Pair{<:ScopedValue}, rest::Pair{<:ScopedValue}...) |
| 155 | + @nospecialize |
| 156 | + ct = Base.current_task() |
| 157 | + current_scope = ct.scope::Union{Nothing, Scope} |
| 158 | + ct.scope = Scope(current_scope, pair, rest...) |
| 159 | + try |
| 160 | + return f() |
| 161 | + finally |
| 162 | + ct.scope = current_scope |
| 163 | + end |
| 164 | +end |
| 165 | + |
| 166 | +with(@nospecialize(f)) = f() |
| 167 | + |
| 168 | +""" |
| 169 | + @with vars... expr |
| 170 | +
|
| 171 | +Macro version of `with(f, vars...)` but with `expr` instead of `f` function. |
| 172 | +This is similar to using [`with`](@ref) with a `do` block, but avoids creating |
| 173 | +a closure. |
| 174 | +""" |
| 175 | +macro with(exprs...) |
| 176 | + if length(exprs) > 1 |
| 177 | + ex = last(exprs) |
| 178 | + exprs = exprs[1:end-1] |
| 179 | + elseif length(exprs) == 1 |
| 180 | + ex = only(exprs) |
| 181 | + exprs = () |
| 182 | + else |
| 183 | + error("@with expects at least one argument") |
| 184 | + end |
| 185 | + for expr in exprs |
| 186 | + if expr.head !== :call || first(expr.args) !== :(=>) |
| 187 | + error("@with expects arguments of the form `A => 2` got $expr") |
| 188 | + end |
| 189 | + end |
| 190 | + exprs = map(esc, exprs) |
| 191 | + quote |
| 192 | + ct = $(Base.current_task)() |
| 193 | + current_scope = ct.scope::$(Union{Nothing, Scope}) |
| 194 | + ct.scope = $(Scope)(current_scope, $(exprs...)) |
| 195 | + $(Expr(:tryfinally, esc(ex), :(ct.scope = current_scope))) |
| 196 | + end |
| 197 | +end |
| 198 | + |
| 199 | +end # module ScopedValues |
0 commit comments