From e0a4cff1115967964809bd4a528d7c4eb2c7109d Mon Sep 17 00:00:00 2001
From: Carsten Bauer <crstnbr@gmail.com>
Date: Fri, 2 Feb 2024 13:54:14 +0100
Subject: [PATCH] translation page for docs

---
 docs/make.jl            |   2 +
 docs/src/translation.md | 119 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 121 insertions(+)
 create mode 100644 docs/src/translation.md

diff --git a/docs/make.jl b/docs/make.jl
index 12c8760e..94024cfb 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -12,6 +12,8 @@ makedocs(;
     doctest = false,
     pages = [
         "OhMyThreads" => "index.md",
+        # "Getting Started" => "examples/getting_started.md",
+        "Translation" => "translation.md",
          "Examples" => [
              "Parallel Monte Carlo" => "examples/mc/mc.md",
              "Julia Set" => "examples/juliaset/juliaset.md",
diff --git a/docs/src/translation.md b/docs/src/translation.md
new file mode 100644
index 00000000..67a30364
--- /dev/null
+++ b/docs/src/translation.md
@@ -0,0 +1,119 @@
+# Translation
+
+## Basic
+
+### `@threads`
+
+```julia
+# Base.Threads
+@threads for i in 1:10
+    println(i)
+end
+```
+
+```julia
+# OhMyThreads
+tforeach(1:10) do i
+    println(i)
+end
+```
+
+#### `:static` scheduling
+
+```julia
+# Base.Threads
+@threads :static for i in 1:10
+    println(i)
+end
+```
+
+```julia
+# OhMyThreads
+tforeach(1:10; schedule=:static) do i
+    println(i)
+end
+```
+
+### `@spawn`
+
+```julia
+# Base.Threads
+@sync for i in 1:10
+    @spawn println(i)
+end
+```
+
+```julia
+# OhMyThreads
+tforeach(1:10; nchunks=10) do i
+    println(i)
+end
+```
+
+## Reduction
+
+No built-in feature in Base.Threads.
+
+```julia
+# Base.Threads: basic manual implementation
+data = rand(10)
+chunks_itr = Iterators.partition(data, length(data) ÷ nthreads())
+tasks = map(chunks_itr) do chunk
+    @spawn reduce(+, chunk)
+end
+reduce(+, fetch.(tasks))
+```
+
+```julia
+# OhMyThreads
+data = rand(10)
+treduce(+, data)
+```
+
+## Mutation
+
+TODO: Remark why one has to be careful here (e.g. false sharing).
+
+```julia
+# Base.Threads
+data = rand(10)
+@threads for i in 1:10
+    data[i] = calc(i)
+end
+```
+
+```julia
+# OhMyThreads: Variant 1
+data = rand(10)
+tforeach(data) do i
+    data[i] = calc(i)
+end
+```
+
+```julia
+# OhMyThreads: Variant 2
+data = rand(10)
+tmap!(data, data) do i # TODO: comment on aliasing
+    calc(i)
+end
+```
+
+## Parallel initialization
+
+```julia
+# Base.Threads
+data = Vector{Float64}(undef, 10)
+@threads for i in 1:10
+    data[i] = calc(i)
+end
+```
+
+```julia
+# OhMyThreads: Variant 1
+data = tmap(i->calc(i), 1:10)
+```
+
+```julia
+# OhMyThreads: Variant 2
+data = tcollect(calc(i) for i in 1:10)
+```
\ No newline at end of file