Make using OhMyThreads: ... explicit in documentation (#90)

* make using ... explicit in docstrings

* make using ... more clear in docs

CHANGELOG.md

@@ -12,6 +12,7 @@ Version 0.5.0
 - ![Enhancement][badge-enhancement] `SerialScheduler` and `DynamicScheduler` now support the keyword argument `ntasks` as an alias for `nchunks`.
 - ![Enhancement][badge-enhancement] Made `@tasks` use `OhMyThreads.WithTaskLocals` automatically as an optimization.
 - ![Enhancement][badge-enhancement] Uses of `@local` within `@tasks` no-longer require users to declare the type of the task local value, it can be inferred automatically if a type is not provided.
+- ![Enhancement][badge-enhancement] Made `using OhMyThreads: ...` more explicit in examples in the documentation and docstrings.
 - ![BREAKING][badge-breaking] The `DynamicScheduler` (default) and the `StaticScheduler` now support a `chunksize` argument to specify the desired size of chunks instead of the number of chunks (`nchunks`). Note that `chunksize` and `nchunks` are mutually exclusive. (This is unlikely to break existing code but technically could because the type parameter has changed from `Bool` to `ChunkingMode`.)
 - ![Breaking][badge-breaking] `DynamicScheduler` and `StaticScheduler` don't support `nchunks=0` or `chunksize=0` any longer. Instead, chunking can now be turned off via an explicit new keyword argument `chunking=false`.
 - ![BREAKING][badge-breaking] Within a `@tasks` block, task-local values must from now on be defined via `@local` instead of `@init` (renamed).

docs/src/translation.md

@@ -9,18 +9,23 @@ This page tries to give a general overview of how to translate patterns written
 
 ```julia
 # Base.Threads
+using Base.Threads: @threads
+
 @threads for i in 1:10
     println(i)
 end
 ```
 
 ```julia
 # OhMyThreads
+using OhMyThreads: @tasks
+
 @tasks for i in 1:10
     println(i)
 end
 
 # or
+using OhMyThreads: tforeach
 
 tforeach(1:10) do i
     println(i)
@@ -31,19 +36,24 @@ end
 
 ```julia
 # Base.Threads
+using Base.Threads: @threads
+
 @threads :static for i in 1:10
     println(i)
 end
 ```
 
 ```julia
 # OhMyThreads
+using OhMyThreads: @tasks
+
 @tasks for i in 1:10
     @set scheduler=:static
     println(i)
 end
 
 # or
+using OhMyThreads: tforeach
 
 tforeach(1:10; scheduler=:static) do i
     println(i)
@@ -54,23 +64,35 @@ end
 
 ```julia
 # Base.Threads
+using Base.Threads: @spawn
+
 @sync for i in 1:10
     @spawn println(i)
 end
 ```
 
 ```julia
 # OhMyThreads
+using OhMyThreads: @tasks
+
 @tasks for i in 1:10
     @set chunking=false
     println(i)
 end
 
 # or
+using OhMyThreads: tforeach
 
 tforeach(1:10; chunking=false) do i
     println(i)
 end
+
+# or
+using OhMyThreads: @spawn
+
+@sync for i in 1:10
+    @spawn println(i)
+end
 ```
 
 ## Reduction
@@ -79,6 +101,8 @@ No built-in feature in Base.Threads.
 
 ```julia
 # Base.Threads: basic manual implementation
+using Base.Threads: @spawn
+
 data = rand(10)
 chunks_itr = Iterators.partition(data, length(data) ÷ nthreads())
 tasks = map(chunks_itr) do chunk
@@ -89,13 +113,15 @@ reduce(+, fetch.(tasks))
 
 ```julia
 # OhMyThreads
+using OhMyThreads: @tasks
 data = rand(10)
 
 @tasks for x in data
     @set reducer=+
 end
 
 # or
+using OhMyThreads: treduce
 
 treduce(+, data)
 ```
@@ -107,27 +133,32 @@ treduce(+, data)
 
 ```julia
 # Base.Threads
+using Base.Threads: @threads
 data = rand(10)
+
 @threads for i in 1:10
     data[i] = calc(i)
 end
 ```
 
 ```julia
 # OhMyThreads
+using OhMyThreads: @tasks
 data = rand(10)
 
 @tasks for i in 1:10
     data[i] = calc(i)
 end
 
 # or
+using OhMyThreads: tforeach
 
 tforeach(data) do i
     data[i] = calc(i)
 end
 
 # or
+using OhMyThreads: tmap!
 
 tmap!(data, data) do i # this kind of aliasing is fine
     calc(i)
@@ -141,6 +172,8 @@ end
 
 ```julia
 # Base.Threads
+using Base.Threads: @threads
+
 data = Vector{Float64}(undef, 10)
 @threads for i in 1:10
     data[i] = calc(i)
@@ -149,16 +182,20 @@ end
 
 ```julia
 # OhMyThreads
+using OhMyThreads: @tasks
+
 data = @tasks for i in 1:10
     @set collect=true
     calc(i)
 end
 
 # or
+using OhMyThreads: tmap
 
 data = tmap(i->calc(i), 1:10)
 
 # or
+using OhMyThreads: tcollect
 
 data = tcollect(calc(i) for i in 1:10)
 ```

src/functions.jl

@@ -16,6 +16,8 @@ will get undefined results.
 ## Example:
 
 ```
+using OhMyThreads: tmapreduce
+
 tmapreduce(√, +, [1, 2, 3, 4, 5])
 ```
 
@@ -60,6 +62,8 @@ will get undefined results.
 ## Example:
 
 ```
+using OhMyThreads: treducemap
+
 treducemap(+, √, [1, 2, 3, 4, 5])
 ```
 
@@ -102,6 +106,8 @@ will get undefined results.
 ## Example:
 
 ```
+using OhMyThreads: treduce
+
 treduce(+, [1, 2, 3, 4, 5])
 ```
 
@@ -143,6 +149,8 @@ end
 ## Example:
 
 ```
+using OhMyThreads: tforeach
+
 tforeach(1:10) do i
     println(i^2)
 end
@@ -178,6 +186,8 @@ returned container, and will generally incur fewer allocations than the version
 ## Example:
 
 ```
+using OhMyThreads: tmap
+
 tmap(sin, 1:10)
 ```
 
@@ -227,6 +237,8 @@ returned container, and will generally incur fewer allocations than the version
 ## Example:
 
 ```
+using OhMyThreads: tcollect
+
 tcollect(sin(i) for i in 1:10)
 ```
 

src/macros.jl

@@ -15,6 +15,10 @@ See also: [`@set`](@ref), [`@local`](@ref)
 
 ## Examples
 
+```julia
+using OhMyThreads: @tasks
+```
+
 ```julia
 @tasks for i in 1:3
     println(i)
@@ -109,9 +113,14 @@ end
     ## Examples
 
     ```julia
+    using OhMyThreads: @tasks
     using OhMyThreads.Tools: taskid
+
     @tasks for i in 1:10
-        @set scheduler=DynamicScheduler(; nchunks=2)
+        @set begin
+            scheduler=:dynamic
+            ntasks=2
+        end
         @local x = zeros(3) # TLV
 
         x .+= 1

src/tools.jl

@@ -3,6 +3,8 @@ module Tools
 using Base.Threads: nthreads
 
 """
+    nthtid(n)
+
 Returns the thread id of the `n`th Julia thread in the `:default` threadpool.
 """
 @inline function nthtid(n)
@@ -18,7 +20,7 @@ end
 """
     taskid() :: UInt
 
-Return a `UInt` identifier for the current running [Task](https://docs.julialang.org/en/v1/base/parallel/#Core.Task). This identifier will be unique so long as references to the task it came from still exist. 
+Return a `UInt` identifier for the current running [Task](https://docs.julialang.org/en/v1/base/parallel/#Core.Task). This identifier will be unique so long as references to the task it came from still exist.
 """
 taskid() = objectid(current_task())