resource_alias tests and brief README

Author: QuantumSegfault

crates/d/README.md

@@ -12,6 +12,36 @@ $ wit-bindgen d [OPTIONS] <WIT>
 
 See the output of `wit-bindgen help d` for available options.
 
--------
+## Output Structure
 
-TODO: Flesh out fuller docs (ownership, more usage, examples, etc.)
+Running `wit-bindgen d` on a WIT world will produce a full package structure mirroring the organization of the WIT world and the interfaces it uses. The default output directory and root package are both `wit`.
+
+`wit.common` holds some definitions used across the generated bindings (for e.g. `result`, `option`, `list`, etc.).
+
+The generated file for the world will by default, `public import` all relavent definitions. More selective imports can be made by importing the appropriate modules corresponding to particular interfaces.
+
+The module for the world `foo:bar/world` will be placed in `wit/foo/bar/world/package.d`. Anonymous interface import and exports for the world will emitted in `wit/foo/bar/world/{imports|exports}`.
+
+Top-level interfaces will be output similarly to worlds. `foo:bar/interface` gets split across multiple modules in `wit/foo/bar/interface/*.d`. Type definitions that are agnostic to import or export (any records, tuples, lists, etc. that do not contain resource handles) will go in `/common.d`. Function imports and import-specific types go in `/imports.d`, and exports go in `/exports.d`
+
+## Memory/Resource Management
+
+Currently, all imports take in parameters as "borrowing" and return memory "owning", with some caveats due to resource handles.
+
+Memory is managed on the C `malloc` heap. This assumption can be used in some cases to reduce copies when unecessary.
+
+When giving parameters to imports, any `list` or `string` memory is NOT freed, and the caller retains ownership/responibility for it. However, the ownership rules of WIT mean that any owning resource handles are invalidated. The bindings will not automatically "consume" these for you, and you will have to zero them out (default init) yourself after the call to prevent double-free.
+
+When receiving parameters to exports, `list` and `string` memory is automatically freed. You must copy this memory elsewhere to retain it past the end of the call. Resource handles are not dropped however, and BOTH owning and borrowing handles (e.g. `Res` and `Res.Borrow`) must be dropped. To drop a handle, use `witDrop`.
+
+When receiving values from imports, you are in charge of freeing the memory and dropping resource handles after you are finished with it/them. `witFree` deeply frees all such memory, and `witDrop` is also deep.
+
+When return values from exports, all memory must be on the WIT/C heap, so it can be reliably `free`d by the bindings. `witClone` deeply copies all `list`s and `string`s.
+
+`scope(exit)` is a valuable tool in helping keep track of this.
+
+In the future, changes may be made to help make this more automatic.
+
+## Examples
+
+It is recommended to peruse `tests/runtime` to find concrete examples of how to use the bindings.

tests/runtime/resource_alias/runner.d

@@ -0,0 +1,36 @@
+import wit.test.resource_alias.runner;
+
+import wit.test.resource_alias.e1.imports : a1 = a, Foo1 = Foo, X;
+import wit.test.resource_alias.e2.imports : a2 = a, Foo2 = Foo;
+
+import wit.common;
+
+@witExport("$root", "run")
+void run() {
+    auto fooE1 = Foo1(
+        x: X.makeNew(42)
+    );
+
+    // consumed later
+
+    a1(fooE1);
+
+    auto fooE2 = Foo2(
+        x: X.makeNew(7)
+    );
+    // consumed later
+
+    auto barE2 = Foo1(
+        x: X.makeNew(8)
+    );
+    // consumed later
+
+    auto y = X.makeNew(8);
+    scope(exit) y.witDrop;
+
+    a2(fooE2, barE2, y);
+}
+
+alias Exports = wit.test.resource_alias.runner.Exports!(
+    run
+);

tests/runtime/resource_alias/test.d

@@ -0,0 +1,45 @@
+import wit.test.resource_alias.test;
+
+import wit.test.resource_alias.e1.exports : Foo1 = Foo, X;
+import wit.test.resource_alias.e2.exports : Foo2 = Foo, Bar, Y;
+
+import wit.common;
+
+@witExport("test:resource-alias/e1", "x")
+struct XImpl {
+    uint val;
+
+    @witExport("test:resource-alias/e1", "[constructor]x")
+    static X constructor(uint v) {
+        return X.makeNew((out typeof(this) self) {
+            self.val = v;
+        });
+    }
+}
+
+@witExport("test:resource-alias/e1", "a")
+WitList!X a1(ref scope Foo1 f) {
+    // `f.x` consumed by return
+
+    immutable X[1] ret = [f.x];
+
+    return ret.witList.witClone;
+}
+
+@witExport("test:resource-alias/e2", "a")
+WitList!Y a2(ref scope Foo2 f, ref scope Bar g, Y.Borrow h) {
+    // `f.x` consumed by return
+    // `f.g` consumed by return
+    //scope(exit) h.witDrop;
+
+    immutable X[2] ret = [f.x, g.x];
+
+    return ret.witList.witClone;
+}
+
+
+alias Exports = wit.test.resource_alias.test.Exports!(
+    XImpl,
+    a1,
+    a2
+);

tests/runtime/resource_alias_redux/runner.d

@@ -0,0 +1,78 @@
+import wit.test.resource_alias_redux.runner;
+
+import wit.test.resource_alias_redux.runner.imports.the_test : Thing1 = Thing;
+import wit.test.resource_alias_redux.resource_alias1.imports : Foo1 = Foo, Thing2 = Thing;
+import wit.test.resource_alias_redux.resource_alias2.imports : Foo2 = Foo;
+
+import wit.common;
+
+@witExport("$root", "run")
+void run() {
+    auto thing1 = Thing.makeNew("Ni Hao".witList);
+    scope(exit) thing1.witDrop;
+
+    {
+        Thing1[1] things = [thing1];
+        auto result = test(things.witList);
+        thing1 = Thing1.init; // consumed
+        scope(exit) result.witFree;
+        assert(result.length == 1);
+
+        {
+            auto str = result[0].get;
+            scope(exit) str.witFree;
+
+            assert(str == "Ni Hao GuestThing GuestThing.get");
+        }
+    }
+
+
+    auto thing2 = Thing2.makeNew("Ciao".witList);
+    scope(exit) thing2.witDrop;
+
+    {
+        auto result = a(Foo1(thing: thing2));
+        thing2 = Thing2.init; // consumed
+        scope(exit) result.witFree;
+        assert(result.length == 1);
+
+        {
+            auto str = result[0].get;
+            scope(exit) str.witFree;
+
+            assert(str == "Ciao GuestThing GuestThing.get");
+        }
+    }
+
+
+    auto thing3 = Thing2.makeNew("Ciao".witList);
+    scope(exit) thing3.witDrop;
+    auto thing4 = Thing2.makeNew("Aloha".witList);
+    scope(exit) thing4.witDrop;
+
+    {
+        auto result = b(Foo2(thing: thing3), Bar(thing: thing4));
+        thing3 = Thing2.init; // consumed
+        thing4 = Thing2.init; // consumed
+        scope(exit) result.witFree;
+        assert(result.length == 2);
+
+        {
+            auto str = result[0].get;
+            scope(exit) str.witFree;
+
+            assert(str == "Ciao GuestThing GuestThing.get");
+        }
+
+        {
+            auto str = result[1].get;
+            scope(exit) str.witFree;
+
+            assert(str == "Aloha GuestThing GuestThing.get");
+        }
+    }
+}
+
+alias Exports = wit.test.resource_alias_redux.runner.Exports!(
+    run
+);

tests/runtime/resource_alias_redux/test.d

@@ -0,0 +1,75 @@
+import wit.test.resource_alias_redux.test;
+
+import wit.test.resource_alias_redux.test.exports.the_test : Thing1 = Thing;
+import wit.test.resource_alias_redux.resource_alias1.exports : Foo1 = Foo, Thing2 = Thing;
+import wit.test.resource_alias_redux.resource_alias2.exports : Foo2 = Foo;
+import wit.common;
+
+extern(C) void* malloc(size_t size);
+extern(C) void free(void* ptr);
+
+char[] concat(in char[] a, in char[] b) {
+    auto ptr = cast(char*)malloc(a.length + b.length);
+    assert((a.length + b.length) == 0 || ptr);
+
+    if (!ptr) return null;
+
+    ptr[0..a.length] = a[];
+    ptr[a.length..a.length+b.length] = b[];
+
+    return ptr[0..a.length+b.length];
+}
+
+@witExport("test:resource-alias-redux/resource-alias1", "thing")
+struct ThingImpl {
+    const(char)[] str;
+
+    @witExport("test:resource-alias-redux/resource-alias1", "[constructor]thing")
+    static Thing1 constructor(in WitString msg) {
+        return Thing1.makeNew((out typeof(this) self) {
+            self.str = concat(msg, " GuestThing");
+        });
+    }
+
+    @witExport("test:resource-alias-redux/resource-alias1", "[method]thing.get")
+    WitString get() {
+        return concat(str, " GuestThing.get").witList; // no clone; already on C heap
+    }
+}
+
+@witExport("test:resource-alias-redux/resource-alias1", "a")
+WitList!Thing1 a(scope ref Foo1 f) {
+    scope(exit) f.witDrop;
+
+    Thing1[1] things = [f.thing];
+    f.thing = Thing1.init; // consumed
+
+    return things.witList.witClone;
+}
+
+@witExport("test:resource-alias-redux/resource-alias2", "b")
+WitList!Thing2 b(scope ref Foo2 f, scope ref Bar g) {
+    scope(exit) {
+        f.witDrop;
+        g.witDrop;
+    }
+
+    Thing1[2] things = [f.thing, g.thing];
+    f.thing = Thing2.init; // consumed
+    g.thing = Thing2.init; // consumed
+
+    return things.witList.witClone;
+}
+
+@witExport("the-test", "test")
+WitList!Thing1 test(scope ref WitList!Thing1 things) {
+    return things.witClone;
+}
+
+
+alias Exports = wit.test.resource_alias_redux.test.Exports!(
+    ThingImpl,
+    a,
+    b,
+    test
+);