Rework type model: concrete wrappers + parallel Kind-lattice dispatch (#63)

Today, `@objcwrapper Foo <: Bar` emits an abstract `Foo` plus a concrete `FooInstance`. Anything stored as a `Foo` (containers, struct fields, inferred return types) carries an abstract type, which boxes in `Vector{Foo}`, breaks inference through property chains, and triggers dynamic dispatch in profiles.

With this change, each `@objcwrapper Foo <: Bar` now emits *two* parallel definitions:

```julia
struct Foo <: Object                        # concrete leaf (storage)
  ptr::id{Foo}
end
abstract type FooKind <: BarKind end        # parallel lattice (dispatch)
classkind(::Type{Foo}) = FooKind
```

Crucially, the inheritance stays flat: every wrapper is `<: Object` directly so that `Vector{NSString}` is bits-packed and inference sees fixed types through property access.

This of course breaks dispatch on "non-leaf" classes, for which we introduce a parallel Kind lattice used by `@objcmethod` methods:

```julia
@objcmethod foo(obj::KindOf{Bar}) = ...
```

The macro `KindOf{T}` lowers to trait dispatch on `Type{<:classkind(T)}` plus a method that forwards from untyped `Object` inputs. Multiple sites on the same function compose naturally -- Julia's dispatch picks the most specific Kind at the call site -- and downstream wrappers automatically participate by virtue of `SubKind <: ParentKind`. When the static type is known at the call site (the common case), the entry-then-body chain folds at compile time, so the trait dispatch is often zero-cost.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: maleadt

Project.toml

@@ -1,14 +1,16 @@
 name = "ObjectiveC"
 uuid = "e86c9b32-1129-44ac-8ea0-90d5bb39ded9"
-version = "3.4.2"
+version = "4.0.0"
 
 [deps]
 CEnum = "fa961155-64e5-5f13-b03f-caf6b980ea82"
+ExprTools = "e2ba6199-217a-4e67-a87a-7c52f15ade04"
 Libdl = "8f399da3-3557-5675-b5ff-fb832c97cbdb"
 Preferences = "21216c6a-2e73-6563-6e65-726566657250"
 
 [compat]
 CEnum = "0.5"
+ExprTools = "0.1"
 Preferences = "1"
 julia = "1.10"
 

README.md

@@ -41,29 +41,93 @@ julia> obj_ptr = @objc [NSValue valueWithPointer:C_NULL::Ptr{Cvoid}]::id{NSValue
 id{NSValue}(0x00006000023cfca0)
 
 julia> obj = NSValue(obj_ptr)
-NSValueInstance (object of type NSConcreteValue)
+NSValue (object of type NSConcreteValue)
 ```
 
-The generated `NSValue` class is an abstract type that implements the type hierarchy, while
-the `NSValueInstance` object is a concrete structure that houses the `id` pointer. This
-split makes it possible to implement multi-level inheritance and attach functionality at
-each level of the hierarchy, and should be entirely transparent to the user (i.e., you
-should never need to use the `*Instance` types in code or signatures).
+`@objcwrapper` emits a concrete `struct NSValue <: Object` holding the `id` pointer. The
+macro also generates conversion routines so the wrapper can be passed directly to `@objc`
+calls expecting `id`.
 
-The `@objcwrapper` macro also generates conversion routines and accessors that makes it
-possible to use these objects directly with `@objc` calls that require `id` pointers:
+To declare a method on a wrapper class, use `@objcmethod` with a `KindOf{T}` argument
+marker:
 
 ```julia
-julia> get_pointer(val::NSValue) = @objc [val::id{NSValue} pointerValue]::Ptr{Cvoid}
+julia> @objcmethod get_pointer(val::KindOf{NSValue}) =
+           @objc [val::id{NSValue} pointerValue]::Ptr{Cvoid}
 
 julia> get_pointer(obj)
 Ptr{Nothing} @0x0000000000000000
 ```
 
+`KindOf{T}` in combination with `@objcmethod` makes the method polymorphic over `T` and any
+wrapped subclasses; important because wrappers do *not* form a Julia `<:` chain (every
+wrapper is `<: Object` directly), so a plain `f(val::NSValue, …)` would silently fail to
+dispatch on a subclass.
+
+
+## Type model
+
+Every `@objcwrapper Foo <: Bar` declaration produces **two** parallel definitions:
+
+* a concrete `struct Foo <: Object` holding `ptr::id{Foo}`, for storage and value identity;
+* an abstract `FooKind <: BarKind` (defaulting to `<: ObjectKind`), for dispatch purposes.
+
+The concrete struct chain stays flat: every wrapper is `<: Object` directly, regardless of
+its ObjC parent, so that `Vector{NSString}` is alloc-free and inference sees a single fixed
+type through container access. The Kind lattice mirrors the ObjC class hierarchy and is
+walked by Julia's native multiple dispatch for polymorphic methods.
+
+### Methods on wrapper classes
+
+**Recommendation: use `@objcmethod` with `KindOf{T}` for wrapper-typed parameters.** Because
+the concrete struct chain is flat, a plain `f(x::Parent, …)` is monomorphic and does *not*
+match a later `@objcwrapper Sub <: Parent`. To avoid this footgun, route every wrapper-typed
+argument through `@objcmethod` and mark it with `KindOf{T}`:
+
+```julia
+@objcmethod release(obj::KindOf{NSObject}) =
+    @objc [obj::id{NSObject} release]::Cvoid
+
+@objcmethod endEncoding!(ce::KindOf{MTLCommandEncoder}) =
+    @objc [ce::id{MTLCommandEncoder} endEncoding]::Nothing
+
+@objcmethod function Base.copy(kernel::KindOf{MPSKernel})
+    K = typeof(kernel)
+    obj = @objc [kernel::id{MPSKernel} copy]::id{MPSKernel}
+    K(reinterpret(id{K}, obj))
+end
+```
+
+For each `KindOf{T}` slot, `@objcmethod` emits a body method dispatched on the parallel
+Kind lattice and an entry forwarder on `::Object` that routes calls to it. When the
+argument's static type is known at the call site (the common case), the chain folds at
+compile time to a direct call; the trait dispatch is zero-cost.
+
+`KindOf{T}` is **macro-level syntax**, not a real Julia type. `@objcmethod` rewrites every
+`KindOf{T}` slot at macroexpand-time and the marker never reaches runtime, so it cannot
+appear in containers, fields, or return positions — `Vector{KindOf{T}}`, `id{KindOf{T}}`,
+and `f(…)::KindOf{T}` are all meaningless. The storage axis is unaffected by the choice
+of dispatch style: `Vector{NSString}` is still tightly packed, and the wrapper struct
+remains an immutable `isbits` value carrying a single `id` pointer regardless of whether
+methods on it use `@objcmethod`.
+
+**When to write a plain method instead.** Skipping `@objcmethod` is fine when:
+
+* The class is a true leaf with no `@objcwrapper` subclasses (e.g. `NSString`, where the
+  underlying `__NSCFString` / `NSTaggedPointerString` subclasses are *not* wrapped on the
+  Julia side and so `typeof(obj)` is always `NSString`). The ObjC runtime still
+  dispatches to the real concrete class via `objc_msgSend`, so a normal
+  `Base.length(s::NSString) = Int(s.length)` works correctly.
+* You genuinely want to refuse subclasses (rare in Objective-C, where messaging is
+  polymorphic by design).
+
+In all other cases, prefer `@objcmethod`: it costs only a runtime type check while
+protecting the method from breaking when a downstream `@objcwrapper Sub <: Parent` lands.
+
 
 ## Properties
 
-A common pattern in Objective-C is to use properties to acces instance variables. Although
+A common pattern in Objective-C is to use properties to access instance variables. Although
 it is possible to access these directly using `@objc`, ObjectiveC.jl provides a macro to
 automatically generate the appropriate `getproperty`, `setproperty!` and `propertynames`
 definitions:

src/ObjectiveC.jl

@@ -2,6 +2,8 @@ module ObjectiveC
 
 using CEnum
 
+using ExprTools: splitdef, combinedef
+
 using Preferences
 
 """

src/foundation.jl

@@ -33,27 +33,37 @@ export NSObject, retain, release, autorelease, is_kind_of
     @autoproperty retainCount::NSUInteger
 end
 
-function Base.show(io::IO, ::MIME"text/plain", obj::NSObject)
+# Methods defined by ObjC on NSObject. `@objcmethod` dispatches through
+# the Kind lattice, so downstream wrappers (Metal, MPS, user code) automatically
+# participate without re-declaration: `classkind(typeof(obj)) <: NSObjectKind`
+# routes through the trait-dispatched body, while a non-NSObject `Object`
+# subtype hits a clean `MethodError` on the body method.
+@objcmethod function Base.show(io::IO, ::MIME"text/plain",
+                                 obj::KindOf{NSObject})
     if get(io, :compact, false)
         print(io, String(obj.description))
     else
         print(io, String(obj.debugDescription))
     end
 end
 
-release(obj::NSObject) = @objc [obj::id{NSObject} release]::Cvoid
+@objcmethod release(obj::KindOf{NSObject}) =
+    @objc [obj::id{NSObject} release]::Cvoid
 
-autorelease(obj::NSObject) = @objc [obj::id{NSObject} autorelease]::Cvoid
+@objcmethod autorelease(obj::KindOf{NSObject}) =
+    @objc [obj::id{NSObject} autorelease]::Cvoid
 
-retain(obj::NSObject) = @objc [obj::id{NSObject} retain]::Cvoid
+@objcmethod retain(obj::KindOf{NSObject}) =
+    @objc [obj::id{NSObject} retain]::Cvoid
 
-ObjectiveC.class(obj::NSObject) = @objc [obj::id{NSObject} class]::Class
-
-function is_kind_of(obj::NSObject, class::Class)
+@objcmethod function is_kind_of(obj::KindOf{NSObject}, class::Class)
     @objc [obj::id{NSObject} isKindOfClass:class::Class]::Bool
 end
 
-function Base.:(==)(obj1::NSObject, obj2::NSObject)
+# Default equality for ObjC objects via `isEqual:`. Specific classes can
+# override this for a faster path (NSString, NSURL, etc. already do).
+@objcmethod function Base.:(==)(obj1::KindOf{NSObject},
+                                  obj2::KindOf{NSObject})
     @objc [obj1::id{NSObject} isEqual:obj2::id{NSObject}]::Bool
 end
 
@@ -299,7 +309,7 @@ end
 
 NSArray() = NSArray(@objc [NSArray array]::id{NSArray})
 
-function NSArray(elements::Vector{<:NSObject})
+function NSArray(elements::Vector{<:Object})
     arr = @objc [NSArray arrayWithObjects:elements::id{Object}
                                     count:length(elements)::NSUInteger]::id{NSArray}
     return NSArray(arr)
@@ -335,7 +345,7 @@ end
 
 NSDictionary() = NSDictionary(@objc [NSDictionary dictionary]::id{NSDictionary})
 
-function NSDictionary(items::Dict{<:NSObject,<:NSObject})
+function NSDictionary(items::Dict{<:Object,<:Object})
     nskeys = NSArray(collect(keys(items)))
     nsvals = NSArray(collect(values(items)))
     dict = @objc [NSDictionary dictionaryWithObjects:nsvals::id{NSArray}
@@ -349,7 +359,7 @@ Base.isempty(dict::NSDictionary) = length(dict) == 0
 Base.keys(dict::NSDictionary) = dict.allKeys
 Base.values(dict::NSDictionary) = dict.allValues
 
-function Base.getindex(dict::NSDictionary, key::NSObject)
+function Base.getindex(dict::NSDictionary, key::Object)
     ptr = @objc [dict::id{NSDictionary} objectForKey:key::id{NSObject}]::id{Object}
     ptr == nil && throw(KeyError(key))
     return ptr

src/primitives.jl

@@ -132,11 +132,19 @@ Base.:(==)(x::Ptr, y::id) = throw(ArgumentError("Cannot compare id with Ptr"))
 function Base.convert(::Type{id{T}}, x::id{U}) where {T,U}
     # nil is an exception (we want to be able to use `nil` in `@objc` directly)
     x == nil && return Base.bitcast(id{T}, nil)
-    # otherwise, types must match (i.e., only allow converting to a supertype)
-    U <: T || throw(ArgumentError("Cannot convert id{$U} to id{$T}"))
+    # allow conversion to a Julia supertype, or up an Objective-C inheritance chain (encoded
+    # by `inherits_from`). When both U and T are concrete leaf classes, Julia's `<:` alone
+    # is insufficient, since every `@objcwrapper` class is <:Object but not <:its-ObjC-parent.
+    if !(U <: T) && !(compatible_id_types(T, U)::Bool)
+        throw(ArgumentError("Cannot convert id{$U} to id{$T}"))
+    end
     Base.bitcast(id{T}, x)
 end
 
+# default: only Julia subtyping. syntax.jl extends this to use `inherits_from`
+# for the Object hierarchy.
+compatible_id_types(::Type, ::Type) = false
+
 # conversion to integer
 Base.Int(x::id)  = Base.bitcast(Int, x)
 Base.UInt(x::id) = Base.bitcast(UInt, x)
@@ -153,12 +161,12 @@ Base.unsafe_convert(::Type{P}, x::id) where {P<:id} = convert(P, x)
 
 # Objects
 
-# Object is an abstract type, so that we can define subtypes with constructors.
-# The expected interface is that any subtype of Object should be convertible to id.
-
+# Object is the sole abstract supertype of every Objective-C wrapper. Each
+# `@objcwrapper` declaration emits a concrete `struct`/`mutable struct` that
+# inherits directly from `Object`. The Objective-C class hierarchy is encoded
+# via a recursive `inherits_from` trait (see syntax.jl) rather than via
+# Julia's `<:` relation.
 abstract type Object end
-# interface: subtypes of Object should be convertible to `id`s
-#            (i.e., `Base.unsafe_convert(::Type{id}, ::MyObj)`)
 
 const nil = id{Object}(0)
 
@@ -171,10 +179,3 @@ class(obj::Union{Object,id}) =
 Base.methods(obj::Union{Object,id}) = methods(class(obj))
 
 Base.show(io::IO, obj::T) where {T <: Object} = print(io, "$T (object of type ", class(obj), ")")
-
-struct UnknownObject <: Object
-    ptr::id
-    UnknownObject(ptr::id) = new(ptr)
-end
-Base.unsafe_convert(T::Type{<:id}, obj::UnknownObject) = convert(T, obj.ptr)
-Object(ptr::id) = UnknownObject(ptr)