Skip to content

Commit

Permalink
Unexport with, at_with, and ScopedValue from Base
Browse files Browse the repository at this point in the history
  • Loading branch information
vchuravy committed Jan 23, 2024
1 parent e6bf976 commit 7bc8593
Show file tree
Hide file tree
Showing 3 changed files with 21 additions and 7 deletions.
5 changes: 0 additions & 5 deletions base/exports.jl
Original file line number Diff line number Diff line change
Expand Up @@ -651,11 +651,6 @@ export
sprint,
summary,

# ScopedValue
with,
@with,
ScopedValue,

# logging
@debug,
@info,
Expand Down
21 changes: 20 additions & 1 deletion doc/src/base/scopedvalues.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ concurrently.
implementation is available from the package ScopedValues.jl.

In its simplest form you can create a [`ScopedValue`](@ref) with a
default value and then use [`with`](@ref Base.with) or [`@with`](@ref) to
default value and then use [`with`](@ref with) or [`@with`](@ref) to
enter a new dynamic scope.

The new scope will inherit all values from the parent scope
Expand Down Expand Up @@ -54,6 +54,8 @@ f() # 1
Now using a `ScopedValue` we can use **dynamic** scoping.

```julia
using Base.ScopedValues

x = ScopedValue(1)
f() = @show x[]
with(x=>5) do
Expand All @@ -70,6 +72,8 @@ and you can set the value of multiple `ScopedValue`s with one call to `with`.


```julia
using Base.ScopedValues

const scoped_val = ScopedValue(1)
const scoped_val2 = ScopedValue(0)

Expand All @@ -94,6 +98,8 @@ Since `with` requires a closure or a function and creates another call-frame,
it can sometimes be beneficial to use the macro form.

```julia
using Base.ScopedValues

const STATE = ScopedValue{State}()
with_state(f, state::State) = @with(STATE => state, f())
```
Expand All @@ -106,7 +112,9 @@ The parent task and the two child tasks observe independent values of the
same scoped value at the same time.

```julia
using Base.ScopedValues
import Base.Threads: @spawn

const scoped_val = ScopedValue(1)
@sync begin
with(scoped_val => 2)
Expand All @@ -128,7 +136,9 @@ values. You might want to explicitly [unshare mutable state](@ref unshare_mutabl
when entering a new dynamic scope.

```julia
using Base.ScopedValues
import Base.Threads: @spawn

const sval_dict = ScopedValue(Dict())

# Example of using a mutable value wrongly
Expand Down Expand Up @@ -161,6 +171,8 @@ are not well suited for this kind of propagation; our only alternative would hav
been to thread a value through the entire call-chain.

```julia
using Base.ScopedValues

const LEVEL = ScopedValue(:GUEST)

function serve(request, response)
Expand Down Expand Up @@ -189,7 +201,9 @@ end
### [Unshare mutable state](@id unshare_mutable_state)

```julia
using Base.ScopedValues
import Base.Threads: @spawn

const sval_dict = ScopedValue(Dict())

# If you want to add new values to the dict, instead of replacing
Expand All @@ -210,6 +224,7 @@ be in (lexical) scope. This means most often you likely want to use scoped value
as constant globals.

```julia
using Base.ScopedValues
const sval = ScopedValue(1)
```

Expand All @@ -218,7 +233,9 @@ Indeed one can think of scoped values as hidden function arguments.
This does not preclude their use as non-globals.

```julia
using Base.ScopedValues
import Base.Threads: @spawn

function main()
role = ScopedValue(:client)

Expand All @@ -241,6 +258,8 @@ If you find yourself creating many `ScopedValue`'s for one given module,
it may be better to use a dedicated struct to hold them.

```julia
using Base.ScopedValues

Base.@kwdef struct Configuration
color::Bool = false
verbose::Bool = false
Expand Down
2 changes: 1 addition & 1 deletion test/scopedvalues.jl
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# This file is a part of Julia. License is MIT: https://julialang.org/license
import Base: ScopedValues
using Base.ScopedValues

@testset "errors" begin
@test ScopedValue{Float64}(1)[] == 1.0
Expand Down

0 comments on commit 7bc8593

Please sign in to comment.