-
-
Notifications
You must be signed in to change notification settings - Fork 5.6k
Mention Base.Lockable in "multi-threading.md" #58107
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
KronosTheLate
wants to merge
9
commits into
JuliaLang:master
Choose a base branch
from
KronosTheLate:KronosTheLate/mention_lockable
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from 1 commit
Commits
Show all changes
9 commits
Select commit
Hold shift + click to select a range
b494d78
Mention Base.Lockable in "multi-threading.md"
KronosTheLate fc1d649
Update doc/src/manual/multi-threading.md
inkydragon 638cd29
Merge branch 'master' into KronosTheLate/mention_lockable
KronosTheLate 7485520
Merge branch 'JuliaLang:master' into KronosTheLate/mention_lockable
KronosTheLate 56a85e2
Rewrite Using Base.Lockable to associate a lock and a value
KronosTheLate 93ae8ba
Update doc/src/manual/multi-threading.md
KronosTheLate 6b6ccab
Update doc/src/manual/multi-threading.md
KronosTheLate 5a95ecb
Update doc/src/manual/multi-threading.md
KronosTheLate b5479cc
Commit suggestion
KronosTheLate File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -301,7 +301,9 @@ | |
``` | ||
|
||
### [Using locks to avoid data-races](@id man-using-locks) | ||
An important tool to avoid data-races, and thereby write thread-safe code, is the concept of a "lock". A lock can be locked and unlocked. If a thread has locked a lock, and not unlocked it, it is said to "hold" the lock. If there is only one lock, and we write code the requires holding the lock to access some data, we can ensure that multiple threads will never access the same data simultaneously. Note that the link between a lock and a variable is made by the programmer, and not the program. | ||
An important tool to avoid data-races, and thereby write thread-safe code, is the concept of a "lock". A lock can be locked and unlocked. If a thread has locked a lock, and not unlocked it, it is said to "hold" the lock. If there is only one lock, and we write code the requires holding the lock to access some data, we can ensure that multiple threads will never access the same data simultaneously. | ||
|
||
Note that the link between a lock and a variable is made by the programmer, and not the program. A helper-type [`Base.Lockable`](@ref) exists that helps you associate a lock and a value. This is often more safe than keeping track yourself, and is detailed under [Using Base.Lockable to associate a lock and a value](@ref man-lockable). | ||
|
||
For example, we can create a lock `my_lock`, and lock it while we mutate a variable `my_variable`. This is done most simply with the `@lock` macro: | ||
|
||
|
@@ -337,6 +339,32 @@ | |
All three options are equivalent. Note how the final version requires an explicit `try`-block to ensure that the lock is always unlocked, whereas the first two version do this internally. One should always use the lock pattern above when changing data (such as assigning | ||
to a global or closure variable) accessed by other threads. Failing to do this could have unforeseen and serious consequences. | ||
|
||
#### [Using Base.Lockable to associate a lock and a value](@id man-lockable) | ||
As mentioned in the previous section, the helper-type [`Base.Lockable`](@ref) can be used to programmatically ensure the association between a lock and a value. This is generally recommended, as it is both less prone to error and more readable for others compared to having the association only by convention. | ||
|
||
|
||
```julia-repl | ||
julia> my_array = []; # Simple empty array | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Some comments about this code block:
I'd take some inspiration of how the section below is written, ideally the text before the code should be enough to understand the code. |
||
|
||
julia> my_locked_array = Base.Lockable(my_array); # The lock type defaults toReentrantLock(), which is fine in most cases | ||
|
||
julia> lock(identity, my_locked_array) # The first argument is a function that is applied to the "unlocked" array, so `identity` is good for inspecting the associated value in a thread-safe manner | ||
Any[] | ||
|
||
julia> lock(my_locked_array) do x # The functional version of lock` along with the do-syntax` is a convenient way to work with a Lockable object | ||
push!(x, 1) | ||
end; | ||
|
||
julia> lock(identity, my_locked_array) # The array is now mutated, without any risk of data-races | ||
1-element Vector{Any}: | ||
1 | ||
|
||
julia> my_array # The original array is identical to the one contained in my_locked_array`` | ||
1-element Vector{Any}: | ||
1 | ||
|
||
``` | ||
|
||
### [Atomic Operations](@id man-atomic-operations) | ||
|
||
Julia supports accessing and modifying values *atomically*, that is, in a thread-safe way to avoid | ||
|
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.