disable_polyester_threads

Project.toml

@@ -1,7 +1,7 @@
 name = "Polyester"
 uuid = "f517fe37-dbe3-4b94-8317-1923a5111588"
 authors = ["Chris Elrod <elrodc@gmail.com> and contributors"]
-version = "0.6.13"
+version = "0.6.14"
 
 [deps]
 ArrayInterface = "4fba245c-0d91-5ea0-9b3e-6abc04ee57a9"
@@ -21,7 +21,7 @@ BitTwiddlingConvenienceFunctions = "0.1"
 CPUSummary = "0.1.2 - 0.1.8, 0.1.11"
 IfElse = "0.1"
 ManualMemory = "0.1.3"
-PolyesterWeave = "0.1"
+PolyesterWeave = "0.1.7"
 Requires = "1"
 Static = "0.7"
 StrideArraysCore = "0.3.11"

README.md

@@ -413,6 +413,8 @@ Note that `@batch` defaults to using up to one thread per physical core, instead
 is because [LoopVectorization.jl](https://github.com/JuliaSIMD/LoopVectorization.jl) currently only uses up to 1 thread per physical core, and switching the number of
 threads incurs some overhead. See the docstring on `@batch` (i.e., `?@batch` in a Julia REPL) for some more discussion.
 
+## Local per-thread storage
+
 You also can define local storage for each thread, providing a vector containing each of the local storages at the end.
 
 ```julia
@@ -446,4 +448,165 @@ julia> let
  end
 
 Float16[83.0, 90.0, 27.0, 65.0]
-```
+```
+
+## Disabling Polyester threads
+
+When running many repetitions of a Polyester-multithreaded function (e.g. in an embarrassingly parallel problem that repeatedly executes a small already Polyester-multithreaded function), it can be beneficial to disable Polyester (the inner multithreaded loop) and multithread only at the outer level (e.g. with `Base.Threads`). This can be done with the `disable_polyester_threads` context manager. In the expandable section below you can see examples with benchmarks.
+
+It is best to call `disable_polyester_threads` only once, before any `@thread` uses happen, to avoid overhead. E.g. best to do it as:
+```julia
+disable_polyester_threads() do
+ @threads for i in 1:n
+ f()
+ end
+end
+```
+instead of doing it in the following unnecessarily slow manner:
+```julia
+@threads for i in 1:n # DO NOT DO THIS
+ disable_polyester_threads() do # IT HAS UNNECESSARY OVERHEAD
+ f()
+ end
+end
+```
+
+
+<details>
+<summary>Benchmarks of nested multi-threading with Polyester</summary>
+
+```julia
+# Big inner problem, repeated only a few times
+
+y = rand(10000000,4);
+x = rand(size(y)...);
+
+@btime inner($x,$y,1) # 73.319 ms (0 allocations: 0 bytes)
+@btime inner_polyester($x,$y,1) # 8.936 ms (0 allocations: 0 bytes)
+@btime inner_thread($x,$y,1) # 11.206 ms (49 allocations: 4.56 KiB)
+
+@btime sequential_sequential($x,$y) # 274.926 ms (0 allocations: 0 bytes)
+@btime sequential_polyester($x,$y) # 36.963 ms (0 allocations: 0 bytes)
+@btime sequential_thread($x,$y) # 49.373 ms (196 allocations: 18.25 KiB)
+
+@btime threads_of_polyester($x,$y) # 78.828 ms (58 allocations: 4.84 KiB)
+# the following is a purposefully suboptimal way to disable threads
+@btime threads_of_polyester_inner_disable($x,$y) # 70.182 ms (47 allocations: 4.50 KiB)
+# the following is a good way to disable threads (the disable call happening once in the outer scope)
+@btime Polyester.disable_polyester_threads() do; threads_of_polyester($x,$y) end; # 71.141 ms (47 allocations: 4.50 KiB)
+@btime threads_of_sequential($x,$y) # 70.857 ms (46 allocations: 4.47 KiB)
+@btime threads_of_thread($x,$y) # 45.116 ms (219 allocations: 22.00 KiB)
+
+# Small inner problem, repeated many times
+
+y = rand(1000,1000);
+x = rand(size(y)...);
+
+@btime inner($x,$y,1) # 7.028 μs (0 allocations: 0 bytes)
+@btime inner_polyester($x,$y,1) # 1.917 μs (0 allocations: 0 bytes)
+@btime inner_thread($x,$y,1) # 7.544 μs (45 allocations: 4.44 KiB)
+
+@btime sequential_sequential($x,$y) # 6.790 ms (0 allocations: 0 bytes)
+@btime sequential_polyester($x,$y) # 2.070 ms (0 allocations: 0 bytes)
+@btime sequential_thread($x,$y) # 9.296 ms (49002 allocations: 4.46 MiB)
+
+@btime threads_of_polyester($x,$y) # 2.090 ms (42 allocations: 4.34 KiB)
+# the following is a purposefully suboptimal way to disable threads
+@btime threads_of_polyester_inner_disable($x,$y) # 1.065 ms (42 allocations: 4.34 KiB)
+# the following is a good way to disable threads (the disable call happening once in the outer scope)
+@btime Polyester.disable_polyester_threads() do; threads_of_polyester($x,$y) end; # 997.918 μs (49 allocations: 4.56 KiB)
+@btime threads_of_sequential($x,$y) # 1.057 ms (48 allocations: 4.53 KiB)
+@btime threads_of_thread($x,$y) # 4.105 ms (42059 allocations: 4.25 MiB)
+
+# The tested functions
+# All of these would be better implemented by just using @tturbo,
+# but these suboptimal implementations serve as good test case for
+# Polyster-vs-Base thread scheduling.
+
+function inner(x,y,j)
+ for i ∈ axes(x,1)
+ y[i,j] = sin(x[i,j])
+ end
+end
+
+function inner_polyester(x,y,j)
+ @batch for i ∈ axes(x,1)
+ y[i,j] = sin(x[i,j])
+ end
+end
+
+function inner_thread(x,y,j)
+ @threads for i ∈ axes(x,1)
+ y[i,j] = sin(x[i,j])
+ end
+end
+
+function sequential_sequential(x,y)
+ for j ∈ axes(x,2)
+ inner(x,y,j)
+ end
+end
+
+function sequential_polyester(x,y)
+ for j ∈ axes(x,2)
+ inner_polyester(x,y,j)
+ end
+end
+
+function sequential_thread(x,y)
+ for j ∈ axes(x,2)
+ inner_thread(x,y,j)
+ end
+end
+
+function threads_of_polyester(x,y)
+ @threads for j ∈ axes(x,2)
+ inner_polyester(x,y,j)
+ end
+end
+
+function threads_of_polyester_inner_disable(x,y)
+ # XXX This is a bad way to disable Polyester threads as
+ # it causes unnecessary overhead for each @threads thread.
+ # See the benchmarks above for a better way.
+ @threads for j ∈ axes(x,2)
+ Polyester.disable_polyester_threads() do
+ inner_polyester(x,y,j)
+ end
+ end
+end
+
+function threads_of_thread(x,y)
+ @threads for j ∈ axes(x,2)
+ inner_thread(x,y,j)
+ end
+end
+
+function threads_of_thread(x,y)
+ @threads for j ∈ axes(x,2)
+ inner_thread(x,y,j)
+ end
+end
+
+function threads_of_sequential(x,y)
+ @threads for j ∈ axes(x,2)
+ inner(x,y,j)
+ end
+end
+```
+Benchmarks executed on:
+```
+Julia Version 1.9.0-DEV.998
+Commit e1739aa42a1 (2022-07-18 10:27 UTC)
+Platform Info:
+ OS: Linux (x86_64-linux-gnu)
+ CPU: 16 × AMD Ryzen 7 1700 Eight-Core Processor
+ WORD_SIZE: 64
+ LIBM: libopenlibm
+ LLVM: libLLVM-14.0.5 (ORCJIT, znver1)
+ Threads: 8 on 16 virtual cores
+Environment:
+ JULIA_EDITOR = code
+ JULIA_NUM_THREADS = 8
+```
+</details>

src/Polyester.jl

@@ -8,10 +8,11 @@ using ManualMemory: Reference
 using Static
 using Requires
 using PolyesterWeave:
- request_threads, free_threads!, mask, UnsignedIteratorEarlyStop, assume
+ request_threads, free_threads!, mask, UnsignedIteratorEarlyStop, assume,
+ disable_polyester_threads
 using CPUSummary: num_threads, num_cores
 
-export batch, @batch, num_threads
+export batch, @batch, num_threads, disable_polyester_threads
 
 
 include("batch.jl")

test/runtests.jl

@@ -2,6 +2,7 @@ println(
  "Starting tests with $(Threads.nthreads()) threads out of `Sys.CPU_THREADS = $(Sys.CPU_THREADS)`...",
 )
 using Polyester, Aqua, ForwardDiff
+using Base.Threads: @threads
 using Test
 
 function bsin!(y, x, r = eachindex(y, x))
@@ -395,10 +396,10 @@ end
  # issue 78 (lack of support for keyword arguments using only variable names without `=`)
 
  f(a; b=10.0, c=100.0) = a + b + c
- 
+
  buf = [0, 0]
  b = 0.0
- 
+
  Threads.nthreads() == 1 && println("the issue arises only on multithreading runs")
 
  @batch for i in 1:2
@@ -408,6 +409,95 @@ end
  @test buf == [1, 2]
 end
 
+@testset "disable_polyester_threads" begin
+ function inner(x,y,j)
+ for i ∈ axes(x,1)
+ y[i,j] = sin(x[i,j])
+ end
+ end
+
+ function inner_polyester(x,y,j)
+ @batch for i ∈ axes(x,1)
+ y[i,j] = sin(x[i,j])
+ end
+ end
+
+ function inner_thread(x,y,j)
+ @threads for i ∈ axes(x,1)
+ y[i,j] = sin(x[i,j])
+ end
+ end
+
+ function sequential_sequential(x,y)
+ for j ∈ axes(x,2)
+ inner(x,y,j)
+ end
+ end
+
+ function sequential_polyester(x,y)
+ for j ∈ axes(x,2)
+ inner_polyester(x,y,j)
+ end
+ end
+
+ function sequential_thread(x,y)
+ for j ∈ axes(x,2)
+ inner_thread(x,y,j)
+ end
+ end
+
+ function threads_of_polyester(x,y)
+ @threads for j ∈ axes(x,2)
+ inner_polyester(x,y,j)
+ end
+ end
+
+ function threads_of_polyester_inner_disable(x,y)
+ @threads for j ∈ axes(x,2)
+ Polyester.disable_polyester_threads() do
+ inner_polyester(x,y,j)
+ end
+ end
+ end
+
+ function threads_of_thread(x,y)
+ @threads for j ∈ axes(x,2)
+ inner_thread(x,y,j)
+ end
+ end
+
+ function threads_of_sequential(x,y)
+ @threads for j ∈ axes(x,2)
+ inner(x,y,j)
+ end
+ end
+
+ y = rand(10,10); # (size of inner problem, size of outer problem)
+ x = rand(size(y)...);
+ inner(x,y,1)
+ good_y = copy(y)
+ inner_polyester(x,y,1)
+ @assert good_y == y
+ inner_thread(x,y,1)
+ @assert good_y == y
+ sequential_sequential(x,y)
+ good_y = copy(y)
+ sequential_polyester(x,y)
+ @assert good_y == y
+ sequential_thread(x,y)
+ @assert good_y == y
+ threads_of_polyester(x,y)
+ @assert good_y == y
+ threads_of_polyester_inner_disable(x,y)
+ @assert good_y == y
+ disable_polyester_threads() do; threads_of_polyester(x,y) end
+ @assert good_y == y
+ threads_of_sequential(x,y)
+ @assert good_y == y
+ threads_of_thread(x,y)
+ @assert good_y == y
+end
+
 if VERSION ≥ v"1.6"
  println("Package tests complete. Running `Aqua` checks.")
  Aqua.test_all(Polyester)