opaque structs (#44)

Author: jadamcrain

generators/c-oo-bindgen/src/lib.rs

@@ -299,7 +299,15 @@ fn write_struct_definition(
     handle: &NativeStructHandle,
     lib: &Library,
 ) -> FormattingResult<()> {
-    doxygen(f, |f| doxygen_print(f, &handle.doc, lib))?;
+    let doc = match handle.struct_type {
+        NativeStructType::Public => handle.doc.clone(),
+        NativeStructType::Opaque => handle
+            .doc
+            .clone()
+            .warning("This struct should never be initialized or modified by user code"),
+    };
+
+    doxygen(f, |f| doxygen_print(f, &doc, lib))?;
 
     // Write the struct definition
     f.writeln(&format!("typedef struct {}", handle.to_c_type()))?;
@@ -355,7 +363,19 @@ fn write_struct_definition(
     })?;
     f.writeln(&format!("}} {};", handle.to_c_type()))?;
 
-    // Write the struct initializer
+    // user should never try to initialize opaque structs, so don't suggest this is OK
+    if handle.struct_type != NativeStructType::Opaque {
+        f.newline()?;
+        write_struct_initializer(f, handle)?;
+    }
+
+    Ok(())
+}
+
+fn write_struct_initializer(
+    f: &mut dyn Printer,
+    handle: &NativeStructHandle,
+) -> FormattingResult<()> {
     let params = handle
         .elements()
         .filter(|el| !el.element_type.has_default())
@@ -369,8 +389,6 @@ fn write_struct_definition(
         .collect::<Vec<String>>()
         .join(", ");
 
-    f.newline()?;
-
     f.writeln(&format!(
         "static {} {}_init({})",
         handle.to_c_type(),
@@ -470,9 +488,7 @@ fn write_struct_definition(
             Ok(())
         })?;
         f.writeln("};")
-    })?;
-
-    Ok(())
+    })
 }
 
 fn write_enum_definition(

generators/dotnet-oo-bindgen/src/structure.rs

@@ -2,6 +2,20 @@ use crate::*;
 use heck::{CamelCase, MixedCase};
 use oo_bindgen::native_struct::*;
 
+fn field_visibility(struct_type: NativeStructType) -> &'static str {
+    match struct_type {
+        NativeStructType::Opaque => "internal",
+        NativeStructType::Public => "public",
+    }
+}
+
+fn constructor_visibility(struct_type: NativeStructType) -> &'static str {
+    match struct_type {
+        NativeStructType::Opaque => "internal",
+        NativeStructType::Public => "public",
+    }
+}
+
 pub(crate) fn generate(
     f: &mut impl Printer,
     native_struct: &StructHandle,
@@ -14,10 +28,18 @@ pub(crate) fn generate(
     print_imports(f)?;
     f.newline()?;
 
+    let doc = match native_struct.definition.struct_type {
+        NativeStructType::Public => native_struct.doc().clone(),
+        NativeStructType::Opaque => native_struct
+            .doc()
+            .clone()
+            .warning("This class is an opaque handle and cannot be constructed by user code"),
+    };
+
     namespaced(f, &lib.name, |f| {
         documentation(f, |f| {
             // Print top-level documentation
-            xmldoc_print(f, &native_struct.doc(), lib)
+            xmldoc_print(f, &doc, lib)
         })?;
 
         f.writeln(&format!("public class {}", struct_name))?;
@@ -73,7 +95,8 @@ pub(crate) fn generate(
                 })?;
 
                 f.writeln(&format!(
-                    "public {} {}",
+                    "{} {} {}",
+                    field_visibility(native_struct.definition.struct_type),
                     el.element_type.to_type().as_dotnet_type(),
                     el.name.to_camel_case()
                 ))?;
@@ -188,7 +211,11 @@ pub(crate) fn generate(
 
             // Write constructor
             if !native_struct.definition().is_default_constructed() {
-                f.writeln(&format!("public {}(", struct_name))?;
+                f.writeln(&format!(
+                    "{} {}(",
+                    constructor_visibility(native_struct.definition.struct_type),
+                    struct_name
+                ))?;
                 f.write(
                     &native_struct
                         .elements()

generators/java-oo-bindgen/src/java/structure.rs

@@ -3,15 +3,37 @@ use super::*;
 use heck::{CamelCase, MixedCase, ShoutySnakeCase};
 use oo_bindgen::native_struct::*;
 
+fn constructor_visibility(struct_type: NativeStructType) -> &'static str {
+    match struct_type {
+        NativeStructType::Public => "public",
+        NativeStructType::Opaque => "private",
+    }
+}
+
+fn field_visibility(struct_type: NativeStructType) -> &'static str {
+    match struct_type {
+        NativeStructType::Public => "public",
+        NativeStructType::Opaque => "private final",
+    }
+}
+
 pub(crate) fn generate(
     f: &mut impl Printer,
     native_struct: &StructHandle,
     lib: &Library,
 ) -> FormattingResult<()> {
     let struct_name = native_struct.name().to_camel_case();
 
+    let doc = match native_struct.definition.struct_type {
+        NativeStructType::Public => native_struct.doc().clone(),
+        NativeStructType::Opaque => native_struct
+            .doc()
+            .clone()
+            .warning("This class is an opaque handle and cannot be constructed by user code"),
+    };
+
     // Documentation
-    documentation(f, |f| javadoc_print(f, &native_struct.doc(), lib))?;
+    documentation(f, |f| javadoc_print(f, &doc, lib))?;
 
     // Structure definition
     f.writeln(&format!("public class {}", struct_name))?;
@@ -63,7 +85,8 @@ pub(crate) fn generate(
             })?;
 
             f.writeln(&format!(
-                "public {} {}",
+                "{} {} {}",
+                field_visibility(native_struct.definition.struct_type),
                 el.element_type.to_type().as_java_primitive(),
                 el.name.to_mixed_case()
             ))?;
@@ -177,7 +200,11 @@ pub(crate) fn generate(
         f.newline()?;
 
         if !native_struct.definition().is_default_constructed() {
-            f.writeln(&format!("public {}(", struct_name,))?;
+            f.writeln(&format!(
+                "{} {}(",
+                constructor_visibility(native_struct.definition.struct_type),
+                struct_name,
+            ))?;
             f.write(
                 &native_struct
                     .elements()

oo-bindgen/src/native_struct.rs

@@ -142,6 +142,15 @@ impl From<Type> for StructElementType {
     }
 }
 
+/// struct type affects the type of code the backend will generate
+#[derive(Copy, Clone, Debug, PartialEq)]
+pub enum NativeStructType {
+    /// struct members are public
+    Public,
+    /// struct members are private (except C of course), and the struct is just an opaque "token"
+    Opaque,
+}
+
 #[derive(Debug)]
 pub struct NativeStructElement {
     pub name: String,
@@ -152,6 +161,7 @@ pub struct NativeStructElement {
 /// C-style structure definition
 #[derive(Debug)]
 pub struct NativeStruct {
+    pub struct_type: NativeStructType,
     pub declaration: NativeStructDeclarationHandle,
     pub elements: Vec<NativeStructElement>,
     pub doc: Doc,
@@ -179,6 +189,7 @@ pub type NativeStructHandle = Handle<NativeStruct>;
 
 pub struct NativeStructBuilder<'a> {
     lib: &'a mut LibraryBuilder,
+    struct_type: NativeStructType,
     declaration: NativeStructDeclarationHandle,
     elements: Vec<NativeStructElement>,
     element_names_set: HashSet<String>,
@@ -192,13 +203,19 @@ impl<'a> NativeStructBuilder<'a> {
     ) -> Self {
         Self {
             lib,
+            struct_type: NativeStructType::Public, // defaults to a public struct
             declaration,
             elements: Vec::new(),
             element_names_set: HashSet::new(),
             doc: None,
         }
     }
 
+    pub fn make_opaque(mut self) -> Self {
+        self.struct_type = NativeStructType::Opaque;
+        self
+    }
+
     pub fn add<S: Into<String>, T: Into<StructElementType>, D: Into<Doc>>(
         mut self,
         name: S,
@@ -250,6 +267,7 @@ impl<'a> NativeStructBuilder<'a> {
         };
 
         let handle = NativeStructHandle::new(NativeStruct {
+            struct_type: self.struct_type,
             declaration: self.declaration.clone(),
             elements: self.elements,
             doc,

tests/bindings/dotnet/foo.Tests/OpaqueStructureTest.cs

@@ -0,0 +1,17 @@
+using System;
+using Xunit;
+using foo;
+
+namespace foo.Tests
+{
+   
+    public class OpaqueStructureTest
+    {
+        [Fact]
+        public void StructureByValueEchoTest()
+        {            
+            Assert.Equal(42ul, OpaqueStruct.CreateMagicValue().GetId());
+        }
+        
+    }
+}

tests/bindings/java/foo-tests/src/test/java/io/stepfunc/foo_test/OpaqueStructureTest.java

@@ -0,0 +1,13 @@
+package io.stepfunc.foo_test;
+
+import io.stepfunc.foo.OpaqueStruct;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+import static org.joou.Unsigned.*;
+
+class OpaqueStructTest {
+    @Test
+    void OpaqueStructureCanRoundTripValues() {
+        Assertions.assertEquals(ulong(42), OpaqueStruct.createMagicValue().getId());
+    }
+}

tests/foo-ffi/src/lib.rs

@@ -8,6 +8,7 @@ mod enums;
 mod integer;
 mod iterator;
 mod lifetime;
+mod opaque_struct;
 mod strings;
 mod structure;
 
@@ -19,6 +20,7 @@ pub use enums::*;
 pub use integer::*;
 pub use iterator::*;
 pub use lifetime::*;
+pub(crate) use opaque_struct::*;
 pub use strings::*;
 pub(crate) use structure::*;
 

tests/foo-ffi/src/opaque_struct.rs

@@ -0,0 +1,7 @@
+pub(crate) unsafe fn opaque_struct_get_id(value: Option<&crate::ffi::OpaqueStruct>) -> u64 {
+    value.unwrap().id
+}
+
+pub(crate) fn opaque_struct_magic_init() -> crate::ffi::OpaqueStruct {
+    crate::ffi::OpaqueStruct { id: 42 }
+}

tests/foo-schema/src/lib.rs

@@ -9,6 +9,7 @@ mod enums;
 mod integer;
 mod iterator;
 mod lifetime;
+mod opaque_struct;
 mod strings;
 mod structure;
 
@@ -36,6 +37,7 @@ pub fn build_lib() -> Result<Library, BindingError> {
     enums::define(&mut builder)?;
     integer::define(&mut builder)?;
     iterator::define(&mut builder)?;
+    opaque_struct::define(&mut builder)?;
     strings::define(&mut builder)?;
     structure::define(&mut builder)?;
     lifetime::define(&mut builder)?;

tests/foo-schema/src/opaque_struct.rs

@@ -0,0 +1,40 @@
+use oo_bindgen::native_function::{ReturnType, Type};
+use oo_bindgen::*;
+
+pub fn define(lib: &mut LibraryBuilder) -> Result<(), BindingError> {
+    let opaque_struct = lib.declare_native_struct("OpaqueStruct")?;
+
+    let opaque_struct = lib
+        .define_native_struct(&opaque_struct)?
+        .make_opaque()
+        .add("id", Type::Uint64, "64-bit id")?
+        .doc("Opaque structure")?
+        .build()?;
+
+    let get_id_fn = lib
+        .declare_native_function("opaque_struct_get_id")?
+        .param(
+            "value",
+            Type::StructRef(opaque_struct.declaration.clone()),
+            "struct value",
+        )?
+        .return_type(ReturnType::Type(Type::Uint64, "value of id field".into()))?
+        .doc("Get the id field of the struct")?
+        .build()?;
+
+    let opaque_struct_magic_init_fn = lib
+        .declare_native_function("opaque_struct_magic_init")?
+        .return_type(ReturnType::Type(
+            Type::Struct(opaque_struct.clone()),
+            "initialized value".into(),
+        ))?
+        .doc("Create an OpaqueStruct initialized with a magic id")?
+        .build()?;
+
+    lib.define_struct(&opaque_struct)?
+        .method("GetId", &get_id_fn)?
+        .static_method("CreateMagicValue", &opaque_struct_magic_init_fn)?
+        .build();
+
+    Ok(())
+}