Skip to content

Commit e16ea92

Browse files
docs: Add Quickstart datadeps documentation (#495)
Co-authored-by: Julian Samaroo <[email protected]>
1 parent 9bd2961 commit e16ea92

File tree

1 file changed

+52
-0
lines changed

1 file changed

+52
-0
lines changed

docs/src/index.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -315,3 +315,55 @@ To get back an `Array` from a `DArray`, just call `collect`:
315315
DA = rand(Blocks(32, 32), 256, 128)
316316
collect(DA) # returns a `Matrix{Float64}`
317317
```
318+
319+
## Quickstart: Datadeps
320+
321+
Datadeps is a feature in Dagger.jl that facilitates parallelism control within designated regions, allowing tasks to write to their arguments while ensuring dependencies are respected.
322+
For more details: [Datadeps (Data Dependencies)](@ref)
323+
324+
### Syntax
325+
326+
The Dagger.spawn_datadeps() function is used to create a "datadeps region" where tasks are executed with parallelism controlled by specified dependencies:
327+
328+
```julia
329+
Dagger.spawn_datadeps() do
330+
Dagger.@spawn func!(Out(var_name_x), In(var_name_y))
331+
end
332+
```
333+
334+
### Argument Annotation
335+
336+
- `In(X)`: Indicates that the variable `X` is only read by the task (an "input").
337+
- `Out(X)`: Indicates that the variable `X` is only written to by the task (an "output").
338+
- `InOut(X)`: Indicates that the variable `X` is both read from and written to by the task (an "input" and "output" simultaneously).
339+
340+
### Example with Datadeps
341+
342+
```julia
343+
X = [4,5,6,7,1,2,3,9,8]
344+
C = zeros(10)
345+
346+
Dagger.spawn_datadeps() do
347+
Dagger.@spawn sort!(InOut(X))
348+
Dagger.@spawn copyto!(Out(C), In(X))
349+
end
350+
351+
# C = [1,2,3,4,5,6,7,8,9]
352+
```
353+
354+
In this example, the `sort!` function operates on array `X`, while the `copyto!` task reads from array `X` and reads from array `C`. By specifying dependencies using argument annotations, the tasks are executed in a controlled parallel manner, resulting in a sorted `C` array.
355+
356+
### Example without Datadeps
357+
358+
```julia
359+
X = [4,5,6,7,1,2,3,9,8]
360+
C = zeros(10)
361+
Dagger.@spawn sort!(X)
362+
Dagger.@spawn copyto!(C, X)
363+
364+
365+
# C = [4,5,6,7,1,2,3,9,8]
366+
```
367+
368+
In contrast to the previous example, here, the tasks are executed without argument annotations. As a result, there is a possibility of the `copyto!` task being executed before the `sort!` task, leading to unexpected results in the output array `C`.
369+

0 commit comments

Comments
 (0)