Can we export, document, and emphasize the at-lock macro?

[NHDaly]

For more context: https://discourse.julialang.org/t/poor-performance-of-lock-l-do-closures-caused-by-poor-performance-of-capturing-closures/42067/13

Base already provides a @lock l expr macro, which (as outlined in the above discourse thread) is often more performant than the related function form lock(f, l).

julia/base/lock.jl

Lines 178 to 188 in 6c9bc51

	macro lock(l, expr)
	quote
	temp = $(esc(l))
	lock(temp)
	try
	$(esc(expr))
	finally
	unlock(temp)
	end
	end
	end

But this macro is not very discoverable, for at least these reasons, and is not widely used:

1. It's not currently exported, so not very discoverable:

   julia> @lock ReentrantLock() 2
   ERROR: LoadError: UndefVarError: @lock not defined
   in expression starting at REPL[1]:1

2. It's not mentioned in any of the docstrings for locks, so again not very discoverable
3. It doesn't have its own docstring, so not very discoverable
4. It seems like this should be preferred over the existing lock(f, lock). Can we deprecate that in favor of this?

---

Can we export it, add docstrings for it, and maybe reference it from the other docstrings?

And/or maybe even emphasize that you should probably prefer this over the function form?

[NHDaly]

This is all coming from us spending a few days digging into poor performance in some central pieces of our codebase, only to find we were using the function form of lock(f, l) all over the place, with nontrivial cost! :'(

[xgdgsc]

So this is still not documented?