add some docs about finalizers

Author: vchuravy

docs/src/faq.md

@@ -744,4 +744,38 @@ autodiff(Forward, f_val, Duplicated(Val(1.0), Val(1.0)))
 ERROR: Type of ghost or constant type Duplicated{Val{1.0}} is marked as differentiable.
 ```
 
+## Finalizers
+
+Julia supports attaching finalizers to objects (see the listing below for an example) 
+
+```julia
+mutable struct Obj
+    x::Float64
+    function Obj(x)
+        o = new(x)
+        finalizer(o) do o
+            # do someting with o
+        end
+        return o
+    end
+end
+```
+
+When Enzyme encounters a code like:
+
+```julia
+function f(x)
+    o = Obj(x)
+    # computations over o
+    return o.x
+end
+
+autodiff(Forward, f, Duplicated(1.0, 1.0))
+```
+
+Enzyme has to allocate a shadow object for `o` and in the process encounters the finalizer being attached to the primal object.
+Now the question is what should Enzyme do with the finalizer for the shadow objects? One option would be to simply ignore it,
+but finalizers are often used for resource management (like manually allocating memory) and thus we would leak resources that are attached
+to the shadow object. Instead, we define finalizers to be inactive (contain no instructions that are relevant with respect to AD),
+yet we must attach them to the shadow object to release resources attached to them. 
 

test/finalizers.jl

@@ -24,13 +24,17 @@ function compute(x::Float64)
     return compute(c)
 end
 
-compute(1.0)
-GC.gc()
-@test length(FREE_LIST) == 1
-empty!(FREE_LIST)
+@testset "primal" begin
+    x = compute(1.0)
+    @test x == 1.0
+    GC.gc()
+    @test length(FREE_LIST) == 1
+    empty!(FREE_LIST)
+end
 
 @testset "forward" begin
     dx, x = autodiff(ForwardWithPrimal, compute, Duplicated(1.0, 2.0))
+    @test x == 1.0
     @test dx == 4.0
     GC.gc()
     @test length(FREE_LIST) == 2
@@ -45,26 +49,30 @@ end
 
 @testset "batched forward" begin
     dx, x = autodiff(ForwardWithPrimal, compute, BatchDuplicated(1.0, (1.0, 2.0)))
-    @test dx == 4.0
+    @test x == 1.0
+    @test dx[1] == 2.0
+    @test dx[2] == 4.0
     GC.gc()
     @test length(FREE_LIST) == 3
     empty!(FREE_LIST)
 
     dx, = autodiff(Forward, compute, BatchDuplicated(1.0, (1.0, 2.0)))
-    @test dx == 4.0
+    @test dx[1] == 2.0
+    @test dx[2] == 4.0
     GC.gc()
     @test length(FREE_LIST) == 3
     empty!(FREE_LIST)
 end
 
 @testset "reverse" begin
     ((dx,), x) = autodiff(ReverseWithPrimal, compute, Active(1.0))
+    @test x == 1.0
     @test dx == 2.0
     GC.gc()
     @test length(FREE_LIST) == 2
     empty!(FREE_LIST)
 
-    ((dx,), x) = autodiff(Reverse, compute, Active(1.0))
+    ((dx,),) = autodiff(Reverse, compute, Active(1.0))
     @test dx == 2.0
     GC.gc()
     @test length(FREE_LIST) == 2