Add docstring to ConcurrencyViolationError (#53733)

This should cover the current usecases of this error. --------- Co-authored-by: Sukera <[email protected]> Co-authored-by: Jameson Nash <[email protected]>
JuliaLang · Jun 10, 2024 · ce38f08 · ce38f08
1 parent b722104
commit ce38f08
Show file tree

Hide file tree

Showing 3 changed files with 19 additions and 0 deletions.
diff --git a/base/docs/basedocs.jl b/base/docs/basedocs.jl
@@ -3736,6 +3736,20 @@ The current differences are:
 """
 Core.finalizer
 
+"""
+    ConcurrencyViolationError(msg) <: Exception
+
+An error thrown when a detectable violation of concurrent semantics has occurred.
+
+A non-exhaustive list of examples of when this is used include:
+
+ * Throwing when a deadlock has been detected (e.g. `wait(current_task())`)
+ * Known-unsafe behavior is attempted (e.g. `yield(current_task)`)
+ * A known non-threadsafe datastructure is attempted to be modified from multiple concurrent tasks
+ * A lock is being unlocked that wasn't locked by this task
+"""
+ConcurrencyViolationError
+
 Base.include(BaseDocs, "intrinsicsdocs.jl")
 
 end
diff --git a/doc/src/base/parallel.md b/doc/src/base/parallel.md
@@ -13,6 +13,7 @@ Base.istaskfailed
 Base.task_local_storage(::Any)
 Base.task_local_storage(::Any, ::Any)
 Base.task_local_storage(::Function, ::Any, ::Any)
+Core.ConcurrencyViolationError
 ```
 
 ## Scheduling

diff --git a/doc/src/manual/multi-threading.md b/doc/src/manual/multi-threading.md
@@ -192,6 +192,7 @@ julia> a
 Note that [`Threads.@threads`](@ref) does not have an optional reduction parameter like [`@distributed`](@ref).
 
 ### Using `@threads` without data-races
+
 The concept of a data-race is elaborated on in ["Communication and data races between threads"](@ref man-communication-and-data-races). For now, just known that a data race can result in incorrect results and dangerous errors.
 
 Lets say we want to make the function `sum_single` below multithreaded.
@@ -257,6 +258,9 @@ depending on the characteristics of the operations.
 Although Julia's threads can communicate through shared memory, it is notoriously difficult to write correct and data-race free multi-threaded code. Julia's
 [`Channel`](@ref)s are thread-safe and may be used to communicate safely. There are also sections below that explain how to use [locks](@ref man-using-locks) and [atomics](@ref man-atomic-operations) to avoid data-races.
 
+In certain cases, Julia is able to detect a detect safety violations, in particular in regards to deadlocks or other known-unsafe operations such as yielding
+to the currently running task. In these cases, a [`ConcurrencyViolationError`](@ref) is thrown.
+
 ### Data-race freedom
 
 You are entirely responsible for ensuring that your program is data-race free,