Update documentation for wait, locked & co

Author: nHackel

docs/src/API/api.md

@@ -8,6 +8,10 @@ AbstractImageReconstruction.AbstractImageReconstructionAlgorithm
 AbstractImageReconstruction.reconstruct
 Base.put!(::AbstractImageReconstructionAlgorithm, ::Any)
 Base.take!(::AbstractImageReconstructionAlgorithm)
+Base.lock(::AbstractImageReconstructionAlgorithm)
+Base.unlock(::AbstractImageReconstructionAlgorithm)
+Base.isready(::AbstractImageReconstructionAlgorithm)
+Base.wait(::AbstractImageReconstructionAlgorithm)
 AbstractImageReconstruction.AbstractImageReconstructionParameters
 AbstractImageReconstruction.process
 AbstractImageReconstruction.parameter

docs/src/literate/example/2_direct.jl

@@ -53,12 +53,20 @@ end
 # And they implement a method to retrieve the used parameters:
 AbstractImageReconstruction.parameter(algo::DirectRadonAlgorithm) = algo.parameter
 
-# And implement the `put!` and `take!` functions, mimicking the behavior of a FIFO channel:
+# Algorithms are assumed to be stateful. To ensure thread safety, we need to implement the `lock` and `unlock` functions. We will use the `output` channel as a lock:
+Base.lock(algo::DirectRadonAlgorithm) = lock(algo.output)
+Base.unlock(algo::DirectRadonAlgorithm) = unlock(algo.output)
+
+# And implement the `put!` and `take!` functions, mimicking the behavior of a FIFO channel for reconstructions:
 Base.take!(algo::DirectRadonAlgorithm) = Base.take!(algo.output)
-function Base.put!(algo::DirectRadonAlgorithm, data::AbstractArray{T, 4}) where {T}
-  lock(algo.output) do
+function Base.put!(algo::DirectRadonAlgorithm, data::AbstractArray{T, 4}) where {T} 
+  lock(algo) do
     put!(algo.output, process(algo, algo.parameter, data))
   end
 end
 
 # The way the behaviour is implemented here, the algorithm does not buffer any inputs and instead blocks until the currenct reconstruction is done. Outputs are stored until they are retrieved.
+
+# With `wait` and `isready` we can check if the algorithm is currently processing data or if it is ready to accept new inputs:
+Base.wait(algo::DirectRadonAlgorithm) = wait(algo.output)
+Base.isready(algo::DirectRadonAlgorithm) = isready(algo.output)

docs/src/literate/example/4_iterative.jl

@@ -73,11 +73,15 @@ end
 # Our algorithm is not type stable. To fix this, we would need to know the element type of the sinograms during construction. Which is possible with a different parameterization of the algorithm. We will not do this here.
 # Often times the performance impact of this is negligible as the critical sections are in the preprocessing or the iterative solver, especially since we still dispatch on the operator.
 
-# To finish up the implementation we need to implement the `put!`, `take!` and `parameters` functions:
+# To finish up the implementation we need to implement the remaining runtime related functions:
 Base.take!(algo::IterativeRadonAlgorithm) = Base.take!(algo.output)
 function Base.put!(algo::IterativeRadonAlgorithm, data::AbstractArray{T, 4}) where {T}
   lock(algo.output) do
     put!(algo.output, process(algo, algo.parameter, data))
   end
 end
+Base.lock(algo::IterativeRadonAlgorithm) = lock(algo.output)
+Base.unlock(algo::IterativeRadonAlgorithm) = unlock(algo.output)
+Base.isready(algo::IterativeRadonAlgorithm) = isready(algo.output)
+Base.wait(algo::IterativeRadonAlgorithm) = wait(algo.output)
 AbstractImageReconstruction.parameter(algo::IterativeRadonAlgorithm) = algo.parameter

docs/src/literate/example/example_include_data.jl

@@ -31,4 +31,5 @@ angles, shape, sinograms, images = isDataDefined ? (angles, shape, sinograms, im
     sinograms[:, :, :, i] = Array(RadonKA.radon(images[:, :, :, i], angles)) 
   end 
   return angles, shape, sinograms, images
-end;
+end
+nothing