@lock export from Base, closes #36441 (#39588)

NEWS.md

@@ -85,6 +85,7 @@ Standard library changes
   @test isequal(complex(one(T)) / complex(T(Inf), T(-Inf)), complex(zero(T), zero(T))) broken=(T == Float64)
   ```
   ([#39322])
+* `@lock` is now exported from Base ([#39588]).
 
 #### Package Manager
 

base/exports.jl

@@ -675,6 +675,7 @@ export
     istaskstarted,
     istaskfailed,
     lock,
+    @lock,
     notify,
     ReentrantLock,
     schedule,

base/lock.jl

@@ -201,6 +201,22 @@ function trylock(f, l::AbstractLock)
     return false
 end
 
+"""
+    @lock l expr
+
+Macro version of `lock(f, l::AbstractLock)` but with `expr` instead of `f` function.
+Expands to:
+```julia
+lock(l)
+try
+    expr
+finally
+    unlock(l)
+end
+```
+This is similar to using [`lock`](@ref) with a `do` block, but avoids creating a closure
+and thus can improve the performance.
+"""
 macro lock(l, expr)
     quote
         temp = $(esc(l))
@@ -213,6 +229,13 @@ macro lock(l, expr)
     end
 end
 
+"""
+    @lock_nofail l expr
+
+Equivalent to `@lock l expr` for cases in which we can guarantee that the function
+will not throw any error. In this case, avoiding try-catch can improve the performance.
+See [`@lock`](@ref).
+"""
 macro lock_nofail(l, expr)
     quote
         temp = $(esc(l))