Completely Refactor

.github/workflows/Documentation.yml

@@ -7,26 +7,14 @@ on:
     tags: '*'
   pull_request:
 
+permissions:
+  contents: write
+  pull-requests: write
+
 jobs:
-  build:
-    permissions:
-      contents: write
-      pull-requests: read
-      statuses: write
-      actions: write
+  docs:
     runs-on: ubuntu-latest
+
     steps:
-      - uses: actions/checkout@v4
-      - uses: julia-actions/setup-julia@v2
-        with:
-          version: '1'
-          arch: x64
-          include-all-prereleases: false
-      - name: Install dependencies
-        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.update(); Pkg.instantiate()'
-      - name: Build and deploy
-        env:
-          GKSwstype: nul # turn off GR's interactive plotting for notebooks
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # If authenticating with GitHub Actions token
-          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
-        run: julia --project=docs/ docs/make.jl
+      - name: Build and deploy Documenter.jl docs
+        uses: TuringLang/actions/DocsDocumenter@main

docs/src/internals.md

@@ -17,4 +17,5 @@ Libtask.build_callable
 Libtask.LazyCallable
 Libtask.DynamicCallable
 Libtask.callable_ret_type
+Libtask.fresh_copy
 ```

src/copyable_task.jl

@@ -222,13 +222,50 @@ julia> consume(t)
 
 # Implementation Notes
 
-Under the hood, a `TapedTask` is implemented in terms of a `MistyClosure.` Each SSA value in
-the original IR is replaced with a `Base.RefValue` of the same type. Each statement writes
-to / reads from these SSAs. These refs are stored in the data that the `MistyClosure` closes
-over, meaning that they persist between calls to `consume`. These refs are copied when a
-copy of a `TapedTask` is made -- since they define the entire state of a task, making a
-completely independent copy of them ensures that a completely independent copy of the task
-is made.
+Under the hood, we implement a `TapedTask` by obtaining the `IRCode` associated to the
+original function, transforming it so that it implements the semantics required by the
+`produce` / `consume` interface, and placing it inside a `MistyClosure` to make it possible
+to execute.
+
+There are two main considerations when transforming the `IRCode`. The first is to ensure
+that the "state" of a `TapedTask` can be copied, so that a `TapedTask` can be copied, and
+resumed later. The complete state of a `TapedTask` is given by its arguments, and the value
+associated to each ssa (these are initially undefined).
+To make it possible to copy the state of the ssa values, we place a `Base.RefValue{T}`s into
+the captures of the `MistyClosure` which implements the `TapedTask`, one for each ssa in the
+IR (`T` is the type inferred for that ssa). A call is replaced by reading in values of ssas
+from these refs, applying the original operation, and writing the result to the ref
+associated to the instruction. For example, if the original snippet of `IRCode` is something
+like
+```julia
+%5 = f(%3, _1)
+```
+the transformed IR would be something like
+```julia
+%5 = ref_for_%3[]
+%6 = f(%5, _1)
+     ref_for_%5[] = %6
+```
+Setting things up in this manner ensures that an independent copy is made by simply copying
+all of the refs. A `deepcopy` is required for correctness as, while the refs to not alias
+one another (by construction), their contents might. For example, two refs may contain the
+same `Array`, and in general the behaviour of a function depends on this relationship.
+
+The second component of the transformation is implementing the `produce` mechanism, and the
+ability to resume computation from where we produced. Roughly speaking, the `IRCode` must be
+modified to ensure that whenever a `produce` call in encountered, the `MistyClosure` returns
+the argument to `produce`, and that subsequent calls resume computation immediately after
+the `produce` statement. This resumption is achieved by setting the value of a counter
+prior to returning following a `produce` statement -- a sequence of comparisons against this
+counter, and [`GotoIfNot`](https://docs.julialang.org/en/v1/devdocs/ast/#Lowered-form)
+statement are inserted at the top of the IR. These are used to jump to the point in the code
+from which computation should resume. These are set up such that, when the `TapedTask` is
+first run, computation start froms the first statement. Observe that this is also
+facilitated by the ref mechanism discussed above, as it ensures that the state persists
+between calls to a `MistyClosure`.
+
+The above gives the broad outline of how `TapedTask`s are implemented. We refer interested
+readers to the code, which is extensively commented to explain implementation details.
 """
 function TapedTask(taped_globals::Any, fargs...; kwargs...)
     all_args = isempty(kwargs) ? fargs : (Core.kwcall, getfield(kwargs, :data), fargs...)
@@ -237,6 +274,22 @@ function TapedTask(taped_globals::Any, fargs...; kwargs...)
     return TapedTask(taped_globals, all_args, mc, count_ref)
 end
 
+"""
+    fresh_copy(mc::T) where {T<:MistyClosure}
+
+Creates an independent copy of `mc` by (carefully) replacing the `Ref`s it
+contains it its `captures`. The resuting `MistyClosure` is safe to run.
+
+This is achieved by replacing most `Ref`s with new `Ref`s of the same (el)type,
+but with nothing stored in them -- values will be stored in them when the
+new `MistyClosure` is called. The only exception are `DynamicCallable`s and
+`LazyCallable`s -- these are constructed when the `MistyClosure`s IR is derived,
+so fresh instances of them are placed in the associated `Ref`.
+
+The position counter is reset to `-1` (indicating that execution should proceed
+from the start of the IR, rather than eg. jumping to a line following a
+`produce` statement.
+"""
 function fresh_copy(mc::T) where {T<:MistyClosure}
     new_captures = map(mc.oc.captures) do r
         if eltype(r) <: DynamicCallable
@@ -407,6 +460,15 @@ const TypeInfo = Tuple{Vector{Any},Dict{ID,Type}}
     _typeof(x)
 
 Central definition of typeof, which is specific to the use-required in this package.
+Largely the same as `Base._stable_typeof`, differing only in a handful of
+situations, for example:
+```jldoctest
+julia> Base._stable_typeof((Float64,))
+Tuple{DataType}
+
+julia> Libtask._typeof((Float64,))
+Tuple{Type{Float64}}
+```
 """
 _typeof(x) = Base._stable_typeof(x)
 _typeof(x::Tuple) = Tuple{map(_typeof, x)...}
@@ -865,6 +927,11 @@ function derive_copyable_task_ir(ir::BBCode)::Tuple{BBCode,Tuple,Vector{Any}}
                 # At present, we're not able to properly infer the values which might
                 # potentially be produced by a call-which-might-produce. Consequently, we
                 # have to assume they can produce anything.
+                #
+                # This `Any` only affects the return type of the function being derived
+                # here. Importantly, it does not affect the type stability of subsequent
+                # statements in this function. As a result, the impact ought to be
+                # reasoanbly limited.
                 push!(possible_produce_types, Any)
 
                 # Create a new basic block from the existing statements, since all new