Becoming an extern "Qt" block

[ahayzen-kdab]

Requirements

• Allow for mixing arbitrary CXX code so we become a "superset"
• Allow for custom types to be use in methods
• Describe the types so that we don't need pattern matching in the extraction/generation/expansion phases

Solutions

Use an extern "Qt" block where we define anything we want to become a QObject, note that the scope of anything define inside it moves outside of the bridge.

Developer code

#[derive(Default)]
struct PrivateObj {
    field: i32,
}

impl PrivateObj {
    fn private_method(&self) {
        // work
    }
}

struct MyThing;

#[cxx_qt::bridge(namespace = "cxx_qt")]
mod ffi {
    extern "Rust" {
        type MyThing;
    }

    unsafe extern "Qt" {
        // Define types that we want
        //
        // These then end up in extern "C++", or should we force users to write them there?
        //
        // Or do we just include all "normal" Qt types if you use extern "Qt"
        type QPoint = cxx_qt_lib::QPoint;

        // Define the QObject
        //
        // This creates a type MyObject in the extern "C++"
        // this also adds getter/setter methods for the Property's
        //
        // Note that this ends up moving into a private scope
	#[base(QObject)]
	struct MyObject {
            prop: Property<T>,

            // Private Rust code, not exposed to Qt
            state: PrivateObj,
        }

        // Implement defaults as usual
        impl Default for MyObject {
            fn default() -> Self {
                Self {
                    prop: Property::new(value),
                    state: PrivateObj::default(),
                }
            }
        }

        // Define invokables that are exposed to the C++ side
        //
        // They need to be implemented within the extern Qt block for our macros to find them
        //
        // Note that this remains in a more "public" scope
	impl MyObject {
	    #[invokable]
	    fn add(self: Pin<&mut Self>)  {
                let number = 1 + self.prop(); // Pin<&T>
                self.set_prop(value); // (T)
 
                // we can use the PrivateObj like normal
                self.state.private_method();

                self.my_thing();
	    }

            fn my_thing(self: Pin<&mut self>) {
                //
            }
        }

        // Define signals that are exposed to Qt
	// enum MyObject::Signal {  << invalid syntax
        enum Signal<MyObject> {
            Ready,
            DataChanged { first: i32, second: QPoint },
	}

        // Define update requester
        impl UpdateRequestHandler for MyObject {
            fn handle_update_request(&mut self) {
                println!("update");
            }
        }
    }
}

Generated Code

// CXX bridge definition moves into a sub module
#[cxx::bridge]
mod ffi {
    unsafe extern "C++" {
        // This is our generated C++ file
        include!("cxx-qt-gen/include/my_object.h");
        // The name of our QObject and this is actually our CppObj
        // this needs to match the C++ nme
        #[namespace = "cxx_qt"]
        type MyObject;

        // TODO: can we define static methods in CXX?
        // as ideally we want to ignore collisions
        #[rust_name = "new_cpp_object"]
        fn newCppObject() -> UniquePtr<MyObject>;

        // Our Qt types
        include!("cxx-qt-lib/include/qt_types.h");
        type QPoint = cxx_qt_lib::QPoint;
    }

    extern "Rust" {
        type MyObjectRust = super::MyObject;

        // Define getters and setters for properties
        #[cxx_name = "getProp"]
        fn prop(self: Pin<&MyObjectRust>) -> &T;
        #[cxx_name = "setProp"]
        fn set_prop(self: Pin<&mut MyObjectRust>, value: T);

        #[cxx_name = "add"]
        fn add(self: &MyObjectRust);

        // TODO: can we implement static methods on the Rust side as well? to avoid collisions
        fn create_rs(cpp: MyObject) -> Box<MyObjectRust>;

        type MyThing;  // we merge in any custom definitions
    }
}

// The struct in extern "Qt" is moved outside
struct MyObject {
    prop: Property<T>,

    // Private Rust code, not exposed to Qt
    state: PrivateObj,

    cpp_obj: Option<ffi::MyObject>,
}

fn create_rs(cpp: ffi::MyObject) -> Box<MyObject> {
    MyObject {
        cpp_obj: Some(CppObj::new(cpp)),
        ..Self::default()
    }
}

impl MyObject {
    pub fn prop(&self) -> Pin<&T> {
        Pin::new(&self.prop)
    }

    pub fn prop_mut(&mut self) -> PropertyMut<T> {
        PropertyMut::new(Pin::new(&mut self.cpp_obj), Pin::new(&mut self.prop))
    }

    pub fn set_prop(&mut self, value: T) {
        self.prop = value;

        // TODO: we need an enum here like signals? and through the prop route etc
        self.cpp_obj.emit_queued(PropChanged);
    }
}

// Implement defaults as usual
impl Default for MyObject {
    fn default() -> Self {
        Self {
            prop: Property::new(value),
            state: PrivateObj::default(),
            cpp_obj: None,
        }
    }
}

// Define invokables that are exposed to the C++ side
//
// They need to be implemented within the extern Qt block for our macros to find them
//
// Note that this remains in a more "public" scope
impl MyObject {
    #[invokable]
    fn add(self: Pin<&mut Self>)  {
        let number = 1 + self.prop(); // Pin<&T>
        self.set_prop(value); // (T)
 
        // we can use the PrivateObj like normal
        self.state.private_method();

        self.my_thing();
    }

    fn my_thing(self: Pin<&mut self>) {
        //
    }
}

// Define signals that are exposed to Qt
enum Signal<MyObject> {  // TODO: how do we avoid collisions here?
    Ready,
    DataChanged { first: i32, second: QPoint },
}

// Define update requester
impl UpdateRequestHandler for MyObject {
    fn handle_update_request(&mut self) {
        println!("update");
    }
}

Problems

• How do we scope signals ?
• Do we have an enum for properties to emit change requests?
• Can we define static methods in CXX ? (no - Distinguish static member function on shared structs dtolnay/cxx#447 )
• Should we have the Qt object impl defined inside the extern "Qt" or the double "header" style we have with CXX ? (eg struct outside)
• The newCppObject() needs to call new(CppObj) on the Rust object with the C++ instance which then uses the default() implementation with Some(cppObj)
• How can we sanely add the CppObj onto the RustObj and keep defaults working etc, do we force the user to specify it or is there another way to add it automatically via something like a trait or mapping between instances?

[ahayzen-kdab]

For signals instead use an attribute on the enum which defines which type they should be declared on.

Note that there can only be one signals definition per QObject. (it would work having multiple enums as we just do a match and then call the relevant method, but if two enums had a signal with the same name it'd break).

#[signals(MyObject)]
enum MyObjectSignals {
    Ready,
    DataChanged { first: i32, second: QPoint },
}

[LeonMatthesKDAB]

Another idea to consider would be using a trait impl of some sort:

enum MyObjectSignals {
    Ready,
    DataChanged { first: i32, second: QPoint },
}

struct MyObject { ... }

impl QObject for MyObject {
    type BaseClass = QAbstractItemModel;
    type Signals = MyObjectSignals
}

But that's just a very rough idea...
Attribute macros are probably nicer.

[ahayzen-kdab]

Interesting idea, as then the QObject trait could provide default methods for the given types, eg for update_requester and the emit_queued. Although I wonder how we could generate a pattern match for the Signals enum in the default method definition 🤔

trait QObject {
  type Signals;

  fn emit_queued(self: Pin<&mut self>, signal: Self::Signals) {
    match signal {
      // somehow would need to match the signal enum to the relevant method
      // we can't easily pass to C++ as we need to have the possibility of parameters and they are easiest to pass as arguments rather than a struct
      Signals::Ready => self.cpp_obj().emit_ready();
    }
  }
}

[ahayzen-kdab]

We can also specify if we need an override in the invokable attribute

impl MyObject {
   #[invokable(override)]
   fn invokable(self: Pin<&Self>) {
    ...
   }
}

And if the C++ class needs any includes we can specify these as normal includes like CXX

unsafe extern "Qt" {
   include!("path/to/header.h");
   // can we also specify ones from the system
   include!("QVector");  // eg this would be #include <QVector> ?
}

[ahayzen-kdab]

If we can avoid needing to store the CppObj inside the struct (and rewriting it) this will feel much more natural. Instead if we could have the update_requester / signal emission available as implementations on the QObject this would be much easier.

impl MyObject {
  pub fn update_requester(self: Pin<&mut Self>) -> UpdateRequester { ... }
}

This could work by having a global hashmap singleton that as Rust objects are created or dropped a map from the RustObj -> CppObj is created. Then in methods such as the update_requester it can call something like CxxQtEngine::cppForRust( * ) -> Option<*> to find the CppObj and then use that as it requires to create an UpdateRequester or emit a signal etc.

[LeonMatthes]

Hm, interesting idea 🤔
Would require another indirection, I wobder whether thats worth it...

[ahayzen-kdab]

Is there such a structure that is lockfree, as it's just a mapping of this pointer should be this pointer? I know it's a singleton etc but makes the struct side of the object much simpler and provides a nice mapping from Rust -> Cpp instances (which should never have duplicates anyway).

[LeonMatthesKDAB]

https://docs.rs/lockfreehashmap/latest/lockfreehashmap/ might do the trick 🤷

[ahayzen-kdab]

Wonder if we should call the Rust and C++ sides with unique names, so that when developers extend the interface with their own extern Rust or C++ blocks it's obvious what they are doing.

Eg

extern "Qt" {
  struct MyObject {
    ...
  }
  ...
}

Would generate the following output

extern "C++" {
  type MyObjectCpp;
  fn newCppObject() -> UniquePtr<MyObjectCpp>;
}

extern "Rust" {
  type MyObjectRust = super::MyObject;
  fn prop(self: Pin<&MyObjectRust>) -> &T;
}

Then in the C++ we create the class called MyObjectCpp but have a type alias.

class MyObjectCpp : public QObject {
  ...
};

typedef MyObjectCpp MyObject;

This then has the advantage that within the CXX extern C++ / Rust blocks the typename used would be MyObjectCpp or MyObjectRust, which results in very explicit typing. Whereas the previous suggestion would result in "MyObject" being used which is not as clear which side of the bridge this refers to.

[LeonMatthesKDAB]

Also see: #156

[ahayzen-kdab]

This is effectively implemented now, closing.