|
|
3 weeks ago | |
|---|---|---|
| .. | ||
| inc | 4 weeks ago | |
| src/OSX | 3 weeks ago | |
| Avalonia.Native.macOS.proj | 4 weeks ago | |
| README.md | 4 weeks ago | |
| generate-headers.sh | 4 weeks ago | |
README.md
Avalonia.Native
This project implements the macOS native platform backend for Avalonia using Objective-C++ and COM (Component Object Model) interfaces.
COM Reference Management
This codebase uses COM for cross-boundary object lifetime management. COM types are typically prefixed with IAvn (interfaces) or Avn (implementations). All COM objects ultimately derive from IUnknown and use reference counting (AddRef/Release).
Do not use raw COM pointers. Fields, instance variables, closures, containers, locals and function parameters all use the smart pointer types below. Raw pointers appear only at real boundaries: C exports, untyped void** out-parameters and C callback contexts.
Implementing COM interfaces
avalonia-native.h is generated by MicroCom in smart pointer wrapper mode. Every interface method has a raw impl_* vtable slot and a non-virtual wrapper with ComPtr arguments. Implementations override the ComPtr shaped methods of MicroComImpl<IFoo>:
| IDL | Override |
|---|---|
IFoo* GetFoo() |
ComPtr<IFoo> GetFoo() |
HRESULT GetFoo(IFoo** ppv) |
HRESULT GetFoo(ComPtr<IFoo>& ppv) |
HRESULT SetFoo(IFoo* foo) |
HRESULT SetFoo(const ComPtr<IFoo>& foo) |
| no interface types | unchanged |
The generated impl_* thunk opens an autorelease pool and keeps this and every interface argument alive for the duration of the call. Implementations need no manual call prologue.
Never inherit from a raw interface, only from MicroComImpl<IFoo> (or ComSingleObject<IFoo, &IID_IFoo>, which does it for you). For interfaces in a cpp-virtual-inherits chain (IAvnTopLevel → IAvnWindowBase → IAvnWindow / IAvnPopup), inherit the adapters with virtual in every class. This is a MANDATORY requirement that is needed because with
Itanium ABI (followed by clang on mac) we'll have NULL's (or something worse, it's UB) in vtable slots.
There is NO compiler warning for this, you'll get a hard crash when attempting to call from C#.
INTERFACE_MAP_ENTRY keeps the interface type, not the adapter: INTERFACE_MAP_ENTRY(IAvnWindow, IID_IAvnWindow).
COM Return Value Convention
Any COM interface reference returned from a COM call has its reference counter incremented. With ComPtr signatures the wrappers handle this. New methods in avn.idl should still prefer the out-parameter pattern:
// Avoid:
IFoo* GetFoo();
// Prefer:
HRESULT GetFoo(IFoo** ppv);
Smart pointer types
Objective-C Objects
For Objective-C objects, reference counting is provided by the compiler. Objective-C pointers look like raw pointers, however every NSObject* reference is properly ref-counted by ARC (Automatic Reference Counting). No manual wrapping is needed for NSObject* fields.
COM Smart Pointer Types
All retained COM references must use one of the following wrappers defined in inc/comimpl.h:
ComPtr<T> — Owning Reference
Use for any COM pointer that the holder needs to keep alive.
ComPtr<IAvnWindow> _window; // correct
IAvnWindow* _window; // WRONG — raw COM pointer in a field
ComPtr has no implicit conversion to a raw pointer. Pass ComPtr along, and make helper functions and Objective-C methods take const ComPtr<T>& or return ComPtr<T>. Use getRetainedReference() only to hand an owned reference to a raw boundary, such as an untyped void** out-parameter (we currently use those for second COM return due to MicroCOM limitation in few places) or a C export.
Use dynamicCast<T>() to get the C++ implementation behind an interface pointer. It is safe on objects implemented in C#: they yield null. Never use raw dynamic_cast on a COM pointer, because C# objects have no RTTI.
ComObjectWeakPtr<T> — Non-Owning Weak Reference
Use for intentional non-owning references to ComObject-derived objects (internal implementations). Allows safely referencing COM objects without extending their lifetime.
ComObjectWeakPtr<WindowBaseImpl> _parent; // correct
WindowBaseImpl* _parent; // WRONG
Access weak references with tryGet(), which returns a ComPtr<T> (null if the object was destroyed):
auto parent = _parent.tryGet();
if (parent) {
parent->DoSomething();
}
Thread safety
The ComObject reference counter is atomic. C# can release objects from any thread, for example from the GC finalizer or the render thread. tryGet() is safe from any thread: it never returns an object that is in destruction. A single ComPtr or ComObjectWeakPtr instance is not safe for concurrent modification, the same as std::shared_ptr.
ComStaticPtr<T> — Process-Lifetime Static Reference
Use for static/global COM singletons that must live for the entire process lifetime. Intentionally does not Release in its destructor to avoid crashes during app teardown.
static ComStaticPtr<IAvnGlDisplay> GlDisplay; // correct
static IAvnGlDisplay* GlDisplay; // WRONG
Assign via set(), read via get() or the implicit conversion to ComPtr<T>:
GlDisplay.set(comnew<AvnGlDisplay>());
comnew<T>(args...) — COM Object Factory
A convenience template similar to std::make_shared. Creates a new COM object and returns it wrapped in a ComPtr<T> that owns the initial reference:
ComPtr<Cursor> cursor = comnew<Cursor>(nsCursor);
comself(this) — Reference to the Calling Object
ComPtr has no constructor from a raw pointer. To pass this where a ComPtr or ComObjectWeakPtr is expected, use comself(this). It only accepts ComObject-derived classes:
View = [[AvnView alloc] initWithParent:comself(this)];