Skip to content

Commit 6a58124

Browse files
FerreolSgdalle
andauthored
docs: warn that preparation is not thread-safe (#801)
* docs: add a message about preparation being not thread safe in documentation * Apply suggestions from code review * Update DifferentiationInterface/src/docstrings.jl --------- Co-authored-by: Guillaume Dalle <22795598+gdalle@users.noreply.github.com>
1 parent ef77d13 commit 6a58124

File tree

2 files changed

+4
-0
lines changed

2 files changed

+4
-0
lines changed

DifferentiationInterface/docs/src/explanation/operators.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,7 @@ op(f, prep, backend, x, [t]) # fast because it skips preparation
117117

118118
!!! warning
119119
The `prep` object is the last argument before `backend` and it is always mutated, regardless of the bang `!` in the operator name.
120+
As a consequence, preparation is **not thread-safe** and sharing `prep` objects between threads may lead to unexpected behavior. If you need to run differentiation concurrently, prepare separate `prep` objects for each thread.
120121

121122
### Reusing preparation
122123

DifferentiationInterface/src/docstrings.jl

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,9 @@ function docstring_prepare(operator; samepoint=false, inplace=false)
2626
Otherwise, preparation becomes invalid and you need to run it again.
2727
In some settings, invalid preparations may still give correct results (e.g. for backends that require no preparation), but this is not a semantic guarantee and should not be relied upon.
2828
29+
!!! danger
30+
The preparation result `prep` is **not thread-safe**. Sharing it between threads may lead to unexpected behavior. If you need to run differentiation concurrently, prepare separate `prep` objects for each thread.
31+
2932
When `strict=Val(true)` (the default), type checking is enforced between preparation and execution (but size checking is left to the user).
3033
While your code may work for different types by setting `strict=Val(false)`, this is not guaranteed by the API and can break without warning.
3134
"""

0 commit comments

Comments
 (0)