Add Task documentation, remove unnecessary compute_intensity(task) function

.gitea/workflows/julia-package-ci.yml

@@ -179,9 +179,9 @@ jobs:
           name: web-doc
           path: docs/build/
 
-      - name: Webhook Trigger
-        uses: https://github.com/zzzze/webhook-trigger@master
-        continue-on-error: true
-        with:
-          data: "{\"event\":\"action_completed\", \"download_url\":\"deckardcain.local:8099/something\"}"
-          webhook_url: ${{ secrets.WEBHOOK_URL }}
+      #- name: Webhook Trigger
+      #  uses: https://github.com/zzzze/webhook-trigger@master
+      #  continue-on-error: true
+      #  with:
+      #    data: "{\"event\":\"action_completed\", \"download_url\":\"deckardcain.local:8099/something\"}"
+      #    webhook_url: ${{ secrets.WEBHOOK_URL }}

src/task/compare.jl

@@ -1,11 +1,26 @@
+"""
+    ==(t1::AbstractTask, t2::AbstractTask)
+
+Fallback implementation of equality comparison between two abstract tasks. Always returns false. For equal specific types of t1 and t2, a more specific comparison is called instead, doing an actual comparison.
+"""
 function ==(t1::AbstractTask, t2::AbstractTask)
     return false
 end
 
+"""
+    ==(t1::AbstractComputeTask, t2::AbstractComputeTask)
+
+Equality comparison between two compute tasks.
+"""
 function ==(t1::AbstractComputeTask, t2::AbstractComputeTask)
     return typeof(t1) == typeof(t2)
 end
 
+"""
+    ==(t1::AbstractDataTask, t2::AbstractDataTask)
+
+Equality comparison between two data tasks.
+"""
 function ==(t1::AbstractDataTask, t2::AbstractDataTask)
     return data(t1) == data(t2)
 end

src/task/print.jl

@@ -1,3 +1,8 @@
+"""
+    show(io::IO, t::FusedComputeTask)
+    
+Print a string representation of the fused compute task to io.
+"""
 function show(io::IO, t::FusedComputeTask)
     (T1, T2) = get_types(t)
     return print(io, "ComputeFuse(", T1(), ", ", T2(), ")")

src/task/properties.jl

@@ -1,22 +1,64 @@
+"""
+    compute(t::AbstractTask; data...)
+
+Fallback implementation of the compute function of a compute task, throwing an error.
+"""
 function compute(t::AbstractTask; data...)
     return error("Need to implement compute()")
 end
 
+"""
+    compute_effort(t::AbstractTask)
+
+Fallback implementation of the compute effort of a task, throwing an error.
+"""
 function compute_effort(t::AbstractTask)
     # default implementation using compute
     return error("Need to implement compute_effort()")
 end
 
+"""
+    data(t::AbstractTask)
+
+Fallback implementation of the data of a task, throwing an error.
+"""
 function data(t::AbstractTask)
     return error("Need to implement data()")
 end
 
+"""
+    compute_effort(t::AbstractDataTask)
+
+Return the compute effort of a data task, always zero, regardless of the specific task.
+"""
 compute_effort(t::AbstractDataTask) = 0
+
+"""
+    compute(t::AbstractDataTask; data...)
+
+The compute function of a data task, always the identity function, regardless of the specific task.
+"""
 compute(t::AbstractDataTask; data...) = data
+
+"""
+    data(t::AbstractDataTask)
+
+Return the data of a data task. Given by the task's `.data` field.
+"""
 data(t::AbstractDataTask) = getfield(t, :data)
 
+"""
+    data(t::AbstractComputeTask)
+
+Return the data of a compute task, always zero, regardless of the specific task.
+"""
 data(t::AbstractComputeTask) = 0
 
+"""
+    compute_effort(t::FusedComputeTask)
+
+Return the compute effort of a fused compute task. 
+"""
 function compute_effort(t::FusedComputeTask)
     (T1, T2) = collect(typeof(t).parameters)
     return compute_effort(T1()) + compute_effort(T2())
@@ -24,10 +66,3 @@ end
 
 # actual compute functions for the tasks can stay undefined for now
 # compute(t::ComputeTaskU, data::Any) = mycomputation(data)
-
-function compute_intensity(t::AbstractTask)::UInt64
-    if data(t) == 0
-        return typemax(UInt64)
-    end
-    return compute_effort(t) / data(t)
-end

src/task/type.jl

@@ -1,13 +1,52 @@
+"""
+    AbstractTask
+
+The shared base type for any task.
+"""
 abstract type AbstractTask end
 
+"""
+    AbstractComputeTask <: AbstractTask
+
+The shared base type for any compute task.
+"""
 abstract type AbstractComputeTask <: AbstractTask end
+
+"""
+    AbstractDataTask <: AbstractTask
+
+The shared base type for any data task.
+"""
 abstract type AbstractDataTask <: AbstractTask end
 
+"""
+    FusedComputeTask{T1 <: AbstractComputeTask, T2 <: AbstractComputeTask} <: AbstractComputeTask
+
+A fused compute task made up of the computation of first `T1` and then `T2`.
+
+Also see: [`get_types`](@ref).
+"""
 struct FusedComputeTask{T1 <: AbstractComputeTask, T2 <: AbstractComputeTask} <:
        AbstractComputeTask end
 
+"""
+    get_types(::FusedComputeTask{T1, T2})
+
+Return a tuple of a the fused compute task's components' types.
+"""
 get_types(::FusedComputeTask{T1, T2}) where {T1, T2} = (T1, T2)
 
+"""
+    copy(t::AbstractDataTask)
+
+Fallback implementation of the copy of an abstract data task, throwing an error.
+"""
 copy(t::AbstractDataTask) =
     error("Need to implement copying for your data tasks!")
+
+"""
+    copy(t::AbstractComputeTask)
+
+Return a copy of the given compute task.
+"""
 copy(t::AbstractComputeTask) = typeof(t)()

test/unit_tests_tasks.jl

@@ -28,15 +28,6 @@
     @test MetagraphOptimization.data(Data10) == 10
     @test MetagraphOptimization.data(Data20) == 20
 
-    @test MetagraphOptimization.compute_intensity(S1) == typemax(UInt64)
-    @test MetagraphOptimization.compute_intensity(S2) == typemax(UInt64)
-    @test MetagraphOptimization.compute_intensity(U) == typemax(UInt64)
-    @test MetagraphOptimization.compute_intensity(V) == typemax(UInt64)
-    @test MetagraphOptimization.compute_intensity(P) == typemax(UInt64)
-    @test MetagraphOptimization.compute_intensity(Sum) == typemax(UInt64)
-    @test MetagraphOptimization.compute_intensity(Data10) == 0
-    @test MetagraphOptimization.compute_intensity(Data20) == 0
-
     @test S1 != S2
     @test Data10 != Data20