RAII

.gitignore

@@ -1,4 +1,5 @@
 /build
+/cmake-build-debug
 /docs/_site
 /docs/_vendor
 /install
@@ -18,6 +19,13 @@
 /tests/dynlib
 /tests/dynlib.exe
 /tests/not_bc
+/tests/class2
+/tests/inline_c.exe
+/tests/objc
+/tests/objc2
+/tests/stdio.exe
+
+/.idea
 
 *.bc
 *.ll

lib/raii.md

@@ -0,0 +1,152 @@
+# RAII - Resource management
+Resource acquisition is initialization ([RAII](https://en.wikipedia.org/wiki/Resource_acquisition_is_initialization)) provides a deterministic means of safe resource management. It is generally associated with systems programming languages such as *c++* and *rust*.
+
+In the following I summarize the experimental implementation that you can find [here](https://github.com/renehiemstra/terra/tree/raii). The socalled [Big Three](https://en.wikipedia.org/wiki/Rule_of_three_(C%2B%2B_programming)) are supported:
+* object destruction
+* copy assignment
+* copy construction
+
+Terra does not support rvalue references (introduced e.g. in *c++11*), so the experimental RAII support is comparable to that of *C++03* or *rust*. 
+
+## Feature summary
+Compiler support for the following methods:
+```
+A.methods.__init(self : &A)
+A.methods.__dtor(self : &A)
+(A or B).methods.__copy(from : &A, to : &B)
+```
+These methods support the implementation of smart containers and smart pointers, like *std::string*, *std::vector* and *std::unique_ptr*, *std::shared_ptr*, *boost:offset_ptr* in C++.
+
+The design does not introduce any breaking changes. No new keywords are introduced. Heap resources are acquired and released using the regular *C stdlib* functions such as malloc and free, leaving memory allocation in the hands of the programmer.
+
+If implemented, these methods are inserted judiciously during the type checking phase, implemented in *terralib.lua*. All these metamethods can be implemented as macro's or as terra functions.
+
+## Compiler supported methods for RAII
+A managed type is one that implements at least `__dtor` and optionally `__init` and `__copy` or, by induction, has fields or subfields that are of a managed type. In the following I assume `struct A` is a managed type.
+
+To enable RAII, import the library */lib/terralibext.t* using
+```
+    require "terralibext"
+```
+The compiler only checks for `__init`, `__dtor` and `__copy` in case this libreary is loaded.
+
+### Object initialization
+`__init` is used to initialize managed variables:
+```
+    A.methods.__init(self : &A)
+```
+The compiler checks for an `__init` method in any variable definition statement, without explicit initializer, and emits the call right after the variable definition, e.g.
+```
+    var a : A
+    a:__init()    --generated by compiler
+```
+### Copy assignment
+`__copy` enables specialized copy-assignment and, combined with `__init`, copy construction. `__copy` takes two arguments, which can be different, as long as one of them is a managed type, e.g.
+```
+    A.metamethods.__copy(from : &A, to : &B)
+```
+and / or
+```
+    A.metamethods.__copy(from : &B, to : &A)
+```
+If `a : A` is a managed type, then the compiler will replace a regular assignment by a call to the implemented `__copy` method
+```
+    b = a   ---->   A.methods.__copy(a, b) 
+```
+or 
+```
+    a = b   ---->   A.methods.__copy(b, a)
+```
+`__copy` can be a (overloaded) terra function or a macro.
+
+The programmer is responsable for managing any heap resources associated with the arguments of the `__copy` method.
+
+### Copy construction
+In object construction, `__copy` is combined with `__init` to perform copy construction. For example,
+```
+    var b : B = a
+```
+is replaced by the following statements
+```
+    var b : B
+    b:__init()              --generated by compiler if `__init` is implemented
+    A.methods.__copy(a, b)  --generated by compiler
+```
+If the right `__copy` method is not implemented but a user defined `__cast` metamethod exists that can cast one of the arguments to the correct type, then the cast is performed and then the relevant copy method is applied.
+
+### Object destruction
+`__dtor` can be used to free heap memory
+```
+    A.methods.__dtor(self : &A)
+```
+The implementation adds a deferred call to `__dtor ` near the end of a scope, right before a potential return statement, for all variables local to the current scope that are not returned. Hence, `__dtor` is tied to the lifetime of the object. For example, for a block of code the compiler would generate
+```
+do
+    var x : A, y : A
+    ...
+    ...
+    defer x:__dtor()    --generated by compiler
+    defer y:__dtor()    --generated by compiler
+end
+```
+or in case of a terra function
+```
+terra foo(x : A)
+    var y : A, z : A
+    ...
+    ...
+    defer z:__dtor()    --generated by compiler
+    return y
+end
+```
+`__dtor` is also called before any regular assignment (if a __copy method is not implemented)  to free 'old' resources. So
+```
+    a = b
+```
+is replaced by
+```
+    a:__dtor()  --generated by compiler
+    a = b
+```
+## Compositional API's
+If a struct has fields or subfields that are managed types, but do not implement `__init`, `__copy` or `__dtor`, then the compiler will generate default methods that inductively call existing `__init`, `__copy` or `__dtor` methods for its fields and subfields. This enables compositional API's like `vector(vector(int))` or  `vector(string)`. This is implemented as an extension to *terralib.lua* in *lib/terralibext.t*.
+
+## Examples
+The following files have been added to the terra testsuite:
+* *raii.t* tests whether `__dtor`, `__init`, and `__copy` are evaluated correctly for simple datatypes.
+* *raii-copyctr-cast.t* tests the combination of `metamethods.__cast` and `__copy`.
+* *raii-unique_ptr.t* tests some functionality of a unique pointer type.
+* *raii-shared_ptr.t* tests some functionality of a shared pointer type.
+* *raii-offset_ptr.t* tests some functionality of an offset pointer implementation, found e.g. in *boost.cpp*.
+* *raii-compose.t* tests the compositional aspect.
+
+You can have a look there for some common code patterns.
+
+## Current limitations
+* The implementation is not aware of when an actual heap allocation is made and therefore assumes that a managed variable always carries a heap resource. It is up to the programmer to properly initialize pointer variables to nil to avoid calling 'free' on uninitialized pointers.
+* Tuple (copy) assignment (regular or using `__copy`) are prohibited by the compiler in case of managed variables. This is done to prevent memory leaks or unwanted deletions in assignments such as
+```
+    a, b = b, a
+```
+* Currently, there is no way to prevent unwanted calls to `__dtor` in cases such as the following. Consider
+```
+terra foo()
+    var b : A
+    return bar(b)
+end
+```
+which will get expanded to 
+```
+terra foo()
+    var b : A
+    defer b:__dtor()    --generated by compiler
+    return bar(b)
+end
+```
+If `bar` would return `b` then its associated heap resources would be released before they can be used in the outer scope.
+
+## Roadmap
+The current implementation already works in a range of important applications, as can be seen in the tests and the examples above. To remove the noted limitations and to enable graceful compile-time errors my plan is to:
+* support *affine types* (similar to *rust*) by checking, at compile time, that a managed variable is used (passed by value) not more than once. This essentially means that the variable is moved from (not copied) on every use. This is not restrictive, since in general you would pass managed objects by reference, not by value.
+* support borrow checking (similar to *rust*) by counting, at compile time, the number of references.
+* introduce a `__new` method that signals a heap allocation. This way the compiler is made aware of all heap allocations being made.

lib/terralibext.t

@@ -0,0 +1,221 @@
+--local io = terralib.includec("stdio.h")
+
+local function addmissinginit(T)
+
+    --flag that signals that a missing __init method needs to
+    --be generated
+    local generate = false
+
+    local runinit = macro(function(self)
+        local V = self:gettype()
+        --avoid generating code for empty array initializers
+        local function hasinit(U)
+            if U:isstruct() then return U.methods.__init
+            elseif U:isarray() then return hasinit(U.type)
+            else return false end
+        end
+        if V:isstruct() then
+            if not V.methods.__init then
+                addmissinginit(V)
+            end
+            local method = V.methods.__init
+            if method then
+                generate = true
+                return quote
+                    self:__init()
+                end
+            end
+        elseif V:isarray() and hasinit(V) then
+            return quote
+                var pa = &self
+                for i = 0,T.N do
+                    runinit((@pa)[i])
+                end
+            end
+        elseif V:ispointer() then
+            return quote
+                self = nil
+            end
+        end
+        return quote end
+    end)
+
+    local generateinit = macro(function(self)
+        local T = self:gettype()
+        local stmts = terralib.newlist()
+        local entries = T:getentries()
+        for i,e in ipairs(entries) do
+            if e.field then
+                local expr = `runinit(self.[e.field])
+                if expr and #expr.tree.statements > 0 then
+                    stmts:insert(expr)
+                end
+            end
+        end
+        return stmts
+    end)
+
+    if T:isstruct() and T.methods.__init == nil then
+        local method = terra(self : &T)
+            generateinit(@self)
+            --io.printf("generated __init()\n")
+        end
+        if generate then
+            T.methods.__init = method
+        else
+            --set T.methods.__init to false. This means that addmissinginit(T) will not
+            --attempt to generate 'T.methods.__init' twice
+            T.methods.__init = false
+        end
+    end
+end
+
+
+local function addmissingdtor(T)
+
+    --flag that signals that a missing __dtor method needs to
+    --be generated
+    local generate = false
+
+    local rundtor = macro(function(self)
+        local V = self:gettype()
+        --avoid generating code for empty array destructors
+        local function hasdtor(U)
+            if U:isstruct() then return U.methods.__dtor
+            elseif U:isarray() then return hasdtor(U.type)
+            else return false end
+        end
+        if V:isstruct() then
+            if not V.methods.__dtor then
+                addmissingdtor(V)
+            end
+            local method = V.methods.__dtor
+            if method then
+                generate = true
+                return quote
+                    self:__dtor()
+                end
+            end
+        elseif V:isarray() and hasdtor(V) then
+            return quote
+                var pa = &self
+                for i = 0,T.N do
+                    rundtor((@pa)[i])
+                end
+            end
+        end
+        return quote end
+    end)
+
+    local generatedtor = macro(function(self)
+        local T = self:gettype()
+        local stmts = terralib.newlist()
+        local entries = T:getentries()
+        for i,e in ipairs(entries) do
+            if e.field then
+                local expr = `rundtor(self.[e.field])
+                if expr and #expr.tree.statements > 0 then
+                    stmts:insert(expr)
+                end
+            end
+        end
+        return stmts
+    end)
+
+    if T:isstruct() and T.methods.__dtor==nil then
+        local method = terra(self : &T)
+            --io.printf("generated __dtor()\n")
+            generatedtor(@self)
+        end
+        if generate then
+            T.methods.__dtor = method
+        else
+            --set T.methods.__dtor to false. This means that addmissingdtor(T) will not
+            --attempt to generate 'T.methods.__dtor' twice
+            T.methods.__dtor = false
+        end
+    end
+end
+
+local function addmissingcopy(T)
+
+    --flag that signals that a missing __copy method needs to
+    --be generated
+    local generate = false
+
+    local runcopy = macro(function(from, to)
+        local U = from:gettype()
+        local V = to:gettype()
+        --avoid generating code for empty array initializers
+        local function hascopy(W)
+            if W:isstruct() then return W.methods.__copy
+            elseif W:isarray() then return hascopy(W.type)
+            else return false end
+        end
+        if V:isstruct() and U==V then
+            if not V.methods.__copy then
+                addmissingcopy(V)
+            end
+            local method = V.methods.__copy
+            if method then
+                generate = true
+                return quote
+                    method(&from, &to)
+                end
+            else
+                return quote
+                    to = from
+                end
+            end
+        elseif V:isarray() and hascopy(V) then
+            return quote
+                var pa = &self
+                for i = 0,V.N do
+                    runcopy((@pa)[i])
+                end
+            end
+        else
+            return quote
+                to = from
+            end
+        end
+        return quote end
+    end)
+
+    local generatecopy = macro(function(from, to)
+        local stmts = terralib.newlist()
+        local entries = T:getentries()
+        for i,e in ipairs(entries) do
+            local field = e.field
+            if field then
+                local expr = `runcopy(from.[field], to.[field])
+                if expr and #expr.tree.statements > 0 then
+                    stmts:insert(expr)
+                end
+            end
+        end
+        return stmts
+    end)
+
+    if T:isstruct() and T.methods.__copy==nil then
+        local method = terra(from : &T, to : &T)
+            generatecopy(@from, @to)
+            --io.printf("generated __copy()\n")
+        end
+        if generate then
+            T.methods.__copy = method
+        else
+            --set T.methods.__copy to false. This means that addmissingcopy(T) will not
+            --attempt to generate 'T.methods.__copy' twice
+            T.methods.__copy = false
+        end
+    end
+end
+
+terralib.ext = {
+    addmissing = {
+        __init = addmissinginit,
+        __dtor = addmissingdtor,
+        __copy = addmissingcopy
+    }
+}