Multi-Threading
A macro to parallelize a for-loop to run with multiple threads. This spawns nthreads()
number of threads, splits the iteration space amongst them, and iterates in parallel. A barrier is placed at the end of the loop which waits for all the threads to finish execution, and the loop returns.
Base.Threads.@spawn
— Macro
Threads.@spawn expr
Create and run a on any available thread. To wait for the task to finish, call wait
on the result of this macro, or call to wait and then obtain its return value.
Note
This feature is currently considered experimental.
Julia 1.3
This macro is available as of Julia 1.3.
— Function
Threads.threadid()
Get the ID number of the current thread of execution. The master thread has ID 1
.
— Function
Threads.nthreads()
Get the number of threads available to the Julia process. This is the inclusive upper bound on threadid()
.
— Type
Threads.Condition([lock])
A thread-safe version of Base.Condition
.
Julia 1.2
This functionality requires at least Julia 1.2.
Base.Event
— Type
Event()
Create a level-triggered event source. Tasks that call on an Event
are suspended and queued until notify
is called on the Event
. After notify
is called, the Event
remains in a signaled state and tasks will no longer block when waiting for it.
Julia 1.1
This functionality requires at least Julia 1.1.
See also .
Warning
The API for atomic operations has not yet been finalized and is likely to change.
Base.Threads.Atomic
— Type
Threads.Atomic{T}
Holds a reference to an object of type T
, ensuring that it is only accessed atomically, i.e. in a thread-safe manner.
Only certain “simple” types can be used atomically, namely the primitive boolean, integer, and float-point types. These are Bool
, Int8
…Int128
, UInt8
…UInt128
, and Float16
…Float64
.
New atomic objects can be created from a non-atomic values; if none is specified, the atomic object is initialized with zero.
Atomic objects can be accessed using the []
notation:
Examples
julia> x = Threads.Atomic{Int}(3)
Base.Threads.Atomic{Int64}(3)
julia> x[] = 1
1
julia> x[]
1
Atomic operations use an atomic_
prefix, such as , atomic_xchg!
, etc.
Threads.atomic_cas!(x::Atomic{T}, cmp::T, newval::T) where T
Atomically compare-and-set x
Atomically compares the value in x
with cmp
. If equal, write newval
to x
. Otherwise, leaves x
unmodified. Returns the old value in x
. By comparing the returned value to cmp
(via ===
) one knows whether x
was modified and now holds the new value newval
.
For further details, see LLVM’s cmpxchg
instruction.
This function can be used to implement transactional semantics. Before the transaction, one records the value in x
. After the transaction, the new value is stored only if x
has not been modified in the mean time.
Examples
julia> x = Threads.Atomic{Int}(3)
Base.Threads.Atomic{Int64}(3)
julia> Threads.atomic_cas!(x, 4, 2);
julia> x
Base.Threads.Atomic{Int64}(3)
julia> Threads.atomic_cas!(x, 3, 2);
julia> x
Base.Threads.Atomic{Int64}(2)
— Function
Atomically exchange the value in x
Atomically exchanges the value in x
with newval
. Returns the old value.
For further details, see LLVM’s atomicrmw xchg
instruction.
Examples
julia> x = Threads.Atomic{Int}(3)
Base.Threads.Atomic{Int64}(3)
julia> Threads.atomic_xchg!(x, 2)
3
julia> x[]
2
— Function
Threads.atomic_add!(x::Atomic{T}, val::T) where T <: ArithmeticTypes
Atomically add val
to x
Performs x[] += val
atomically. Returns the old value. Not defined for Atomic{Bool}
.
For further details, see LLVM’s atomicrmw add
instruction.
Examples
julia> x = Threads.Atomic{Int}(3)
Base.Threads.Atomic{Int64}(3)
julia> Threads.atomic_add!(x, 2)
3
julia> x[]
5
— Function
Threads.atomic_sub!(x::Atomic{T}, val::T) where T <: ArithmeticTypes
Atomically subtract val
from x
Performs x[] -= val
atomically. Returns the old value. Not defined for Atomic{Bool}
.
For further details, see LLVM’s atomicrmw sub
instruction.
Examples
julia> x = Threads.Atomic{Int}(3)
Base.Threads.Atomic{Int64}(3)
julia> Threads.atomic_sub!(x, 2)
3
julia> x[]
1
— Function
Threads.atomic_and!(x::Atomic{T}, val::T) where T
Atomically bitwise-and x
with val
Performs x[] &= val
atomically. Returns the old value.
For further details, see LLVM’s atomicrmw and
instruction.
Examples
julia> x = Threads.Atomic{Int}(3)
Base.Threads.Atomic{Int64}(3)
julia> Threads.atomic_and!(x, 2)
3
julia> x[]
2
— Function
Threads.atomic_nand!(x::Atomic{T}, val::T) where T
Atomically bitwise-nand (not-and) x
with val
Performs x[] = ~(x[] & val)
atomically. Returns the old value.
For further details, see LLVM’s atomicrmw nand
instruction.
Examples
julia> x = Threads.Atomic{Int}(3)
Base.Threads.Atomic{Int64}(3)
julia> Threads.atomic_nand!(x, 2)
3
-3
Atomically bitwise-or x
with val
Performs x[] |= val
atomically. Returns the old value.
For further details, see LLVM’s atomicrmw or
instruction.
Examples
julia> x = Threads.Atomic{Int}(5)
Base.Threads.Atomic{Int64}(5)
julia> Threads.atomic_or!(x, 7)
5
julia> x[]
7
Base.Threads.atomic_xor!
— Function
Threads.atomic_xor!(x::Atomic{T}, val::T) where T
Atomically bitwise-xor (exclusive-or) x
with val
Performs x[] $= val
atomically. Returns the old value.
For further details, see LLVM’s atomicrmw xor
instruction.
Examples
julia> x = Threads.Atomic{Int}(5)
Base.Threads.Atomic{Int64}(5)
julia> Threads.atomic_xor!(x, 7)
5
julia> x[]
2
Base.Threads.atomic_max!
— Function
Threads.atomic_max!(x::Atomic{T}, val::T) where T
Atomically store the maximum of x
and val
in x
Performs x[] = max(x[], val)
atomically. Returns the old value.
For further details, see LLVM’s atomicrmw max
instruction.
Examples
julia> x = Threads.Atomic{Int}(5)
Base.Threads.Atomic{Int64}(5)
julia> Threads.atomic_max!(x, 7)
5
julia> x[]
7
Base.Threads.atomic_min!
— Function
Threads.atomic_min!(x::Atomic{T}, val::T) where T
Atomically store the minimum of x
and val
in x
Performs x[] = min(x[], val)
atomically. Returns the old value.
For further details, see LLVM’s atomicrmw min
instruction.
Examples
julia> x = Threads.Atomic{Int}(7)
Base.Threads.Atomic{Int64}(7)
julia> Threads.atomic_min!(x, 5)
7
julia> x[]
5
Base.Threads.atomic_fence
— Function
Insert a sequential-consistency memory fence
Inserts a memory fence with sequentially-consistent ordering semantics. There are algorithms where this is needed, i.e. where an acquire/release ordering is insufficient.
This is likely a very expensive operation. Given that all other atomic operations in Julia already have acquire/release semantics, explicit fences should not be necessary in most cases.
For further details, see LLVM’s fence
instruction.
Base.@threadcall
— Macro
@threadcall((cfunc, clib), rettype, (argtypes...), argvals...)
The @threadcall
macro is called in the same way as but does the work in a different thread. This is useful when you want to call a blocking C function without causing the main julia
thread to become blocked. Concurrency is limited by size of the libuv thread pool, which defaults to 4 threads but can be increased by setting the UV_THREADPOOL_SIZE
environment variable and restarting the julia
process.
Note that the called function should never call back into Julia.
These building blocks are used to create the regular synchronization objects.
— Type
Create a non-reentrant lock. Recursive use will result in a deadlock. Each must be matched with an .