Completely Refactor

.JuliaFormatter.toml

@@ -0,0 +1 @@
+style = "blue"

.github/workflows/Documentation.yml

@@ -0,0 +1,32 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+    tags: '*'
+  pull_request:
+
+jobs:
+  build:
+    permissions:
+      contents: write
+      pull-requests: read
+      statuses: write
+      actions: write
+    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

.github/workflows/Testing.yaml

@@ -11,7 +11,6 @@ jobs:
     strategy:
       matrix:
         version:
-          - '1.7'
           - '1.10'
           - '1'
           - 'nightly'
@@ -26,12 +25,12 @@ jobs:
           - os: macOS-latest
             arch: x86
     steps:
-      - uses: actions/checkout@v2
-      - uses: julia-actions/setup-julia@v1
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
         with:
           version: ${{ matrix.version }}
           arch: ${{ matrix.arch }}
-      - uses: actions/cache@v1
+      - uses: actions/cache@v4
         env:
           cache-name: cache-artifacts
         with:

.gitignore

@@ -1,60 +1,4 @@
-# Prerequisites
-*.d
-
-# Object files
-*.o
-*.ko
-*.obj
-*.elf
-
-# Linker output
-*.ilk
-*.map
-*.exp
-
-# Precompiled Headers
-*.gch
-*.pch
-
-# Libraries
-*.lib
-*.a
-*.la
-*.lo
-
-# Shared objects (inc. Windows DLLs)
-*.dll
-*.so
-*.so.*
-*.dylib
-
-# Executables
-*.exe
-*.out
-*.app
-*.i*86
-*.x86_64
-*.hex
-
-# Debug files
-*.dSYM/
-*.su
-*.idb
-*.pdb
-
-# Kernel Module Compile Results
-*.mod*
-*.cmd
-.tmp_versions/
-modules.order
-Module.symvers
-Mkfile.old
-dkms.conf
-
 # Projects files
-Manifest.toml
-deps/build.log
-deps/deps.jl
-deps/usr/
-deps/tmp-build.jl
+Manifest*
 *.cov
+docs/build

NEWS.md

@@ -0,0 +1,8 @@
+- From v0.6.0, Libtask is implemented by recording all the computing
+  to a tape and copying that tape. Before that version, it is based on
+  a tricky hack on the Julia internals. You can check the commit
+  history of this repo to see the details.
+
+- From version 0.9.0, the old `TArray` and `TRef` types are completely removed, where
+  previously they were only deprecated. Additionally, the internals have been completely
+  overhauled, and the public interface more precisely defined. See the docs for more info.

Project.toml

@@ -3,22 +3,23 @@ uuid = "6f1fad26-d15e-5dc8-ae53-837a1d7b8c9f"
 license = "MIT"
 desc = "Tape based task copying in Turing"
 repo = "https://github.com/TuringLang/Libtask.jl.git"
-version = "0.8.8"
+version = "0.9.0"
 
 [deps]
-FunctionWrappers = "069b7b12-0de2-55c6-9aab-29f3d0a68a2e"
-LRUCache = "8ac3fa9e-de4c-5943-b1dc-09c6b5f20637"
-LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
-Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
+MistyClosures = "dbe65cb8-6be2-42dd-bbc5-4196aaced4f4"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [compat]
-FunctionWrappers = "1.1"
-LRUCache = "1.3"
-julia = "1.7"
+Aqua = "0.8.11"
+JuliaFormatter = "1.0.62"
+MistyClosures = "2.0.0"
+Test = "1"
+julia = "1.10.8"
 
 [extras]
-BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
+Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"
+JuliaFormatter = "98e50ef6-434e-11e9-1051-2b60c6c9e899"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Test", "BenchmarkTools"]
+test = ["Aqua", "JuliaFormatter", "Test"]

README.md

@@ -2,98 +2,8 @@
 
 [![Libtask Testing](https://github.com/TuringLang/Libtask.jl/workflows/Libtask%20Testing/badge.svg)](https://github.com/TuringLang/Libtask.jl/actions?branch=main)
 
-Tape based task copying in Turing
 
-## Getting Started
+Resumable and copyable functions in Julia, with optional function-specific globals.
+See the docs for example usage.
 
-Stack allocated objects are always deep copied:
-
-```julia
-using Libtask
-
-function f()
-  t = 0
-  for _ in 1:10
-    produce(t)
-    t = 1 + t
-  end
-end
-
-ttask = TapedTask(f)
-
-@show consume(ttask) # 0
-@show consume(ttask) # 1
-
-a = copy(ttask)
-@show consume(a) # 2
-@show consume(a) # 3
-
-@show consume(ttask) # 2
-@show consume(ttask) # 3
-```
-
-Heap-allocated Array and Ref objects are deep copied by default:
-
-```julia
-using Libtask
-
-function f()
-  t = [0 1 2]
-  for _ in 1:10
-    produce(t[1])
-    t[1] = 1 + t[1]
-  end
-end
-
-ttask = TapedTask(f)
-
-@show consume(ttask) # 0
-@show consume(ttask) # 1
-
-a = copy(ttask)
-@show consume(a) # 2
-@show consume(a) # 3
-
-@show consume(ttask) # 2
-@show consume(ttask) # 3
-```
-
-Other heap-allocated objects (e.g., `Dict`) are shallow copied, by default:
-
-```julia
-using Libtask
-
-function f()
-  t = Dict(1=>10, 2=>20)
-  while true
-    produce(t[1])
-    t[1] = 1 + t[1]
-  end
-end
-
-ttask = TapedTask(f)
-
-@show consume(ttask) # 10
-@show consume(ttask) # 11
-
-a = copy(ttask)
-@show consume(a) # 12
-@show consume(a) # 13
-
-@show consume(ttask) # 14
-@show consume(ttask) # 15
-```
-
-Notes:
-
-- The [Turing](https://github.com/TuringLang/Turing.jl) probabilistic
-  programming language uses this task copying feature in an efficient
-  implementation of the [particle
-  filtering](https://en.wikipedia.org/wiki/Particle_filter) sampling
-  algorithm for arbitrary order [Markov
-  processes](https://en.wikipedia.org/wiki/Markov_model#Hidden_Markov_model).
-
-- From v0.6.0, Libtask is implemented by recording all the computing
-  to a tape and copying that tape. Before that version, it is based on
-  a tricky hack on the Julia internals. You can check the commit
-  history of this repo to see the details.
+Used in the [Turing](https://github.com/TuringLang/Turing.jl) probabilistic programming language to implement various particle-based inference methods, for example those in [AdvancedPS.jl](https://github.com/TuringLang/AdvancedPS.jl/).

docs/Project.toml

@@ -0,0 +1,3 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Libtask = "6f1fad26-d15e-5dc8-ae53-837a1d7b8c9f"

docs/make.jl

@@ -0,0 +1,9 @@
+using Documenter, Libtask
+
+DocMeta.setdocmeta!(Libtask, :DocTestSetup, :(using Libtask); recursive=true)
+
+makedocs(;
+    sitename="Libtask", doctest=true, pages=["index.md", "internals.md"], modules=[Libtask]
+)
+
+deploydocs(; repo="github.com/TuringLang/Libtask.jl.git", push_preview=true)

docs/src/index.md

@@ -0,0 +1,24 @@
+# Libtask
+
+Libtask is best explained by the docstring for [`TapedTask`](@ref):
+```@docs; canonical=true
+Libtask.TapedTask
+```
+
+The functions discussed the above docstring (in addition to [`TapedTask`](@ref) itself) form the
+public interface of Libtask.jl.
+They divide neatly into two kinds of functions: those which are used to manipulate
+[`TapedTask`](@ref)s, and those which are intended to be used _inside_ a
+[`TapedTask`](@ref).
+First, manipulation of [`TapedTask`](@ref)s:
+```@docs; canonical=true
+Libtask.consume
+Base.copy(::Libtask.TapedTask)
+Libtask.set_taped_globals!
+```
+
+Functions for use inside a [`TapedTask`](@ref)s are:
+```@docs; canonical=true
+Libtask.produce
+Libtask.get_taped_globals
+```

docs/src/internals.md

@@ -0,0 +1,17 @@
+# Internals
+
+```@docs; canonical=true
+Libtask.produce_value
+Libtask.is_produce_stmt
+Libtask.might_produce
+Libtask.stmt_might_produce
+Libtask.LazyCallable
+Libtask.inc_args
+Libtask.get_type
+Libtask._typeof
+Libtask.replace_captures
+Libtask.BasicBlockCode
+Libtask.opaque_closure
+Libtask.misty_closure
+Libtask.optimise_ir!
+```

perf/Project.toml

@@ -8,7 +8,7 @@ Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 Turing = "fce5fe82-541a-59a6-adf8-730c64b5f9a0"
 
 [compat]
-julia = "1.3"
+julia = "1.10.8"
 
 [targets]
 test = ["Test", "BenchmarkTools"]