Handling objects passed as "out parameters"

[madsmtm]

See Passing to an out parameter by writeback.

Some methods take pointers to an instance, and, if the pointer is not NULL, write some value to the pointer. Examples include:

• -[NSObject validateValue:forKey:error:]
• -[NSAppleScript initWithContentsOfURL:error:]
• -[NSCalendar rangeOfUnit:startDate:interval:forDate:]
• -[NSNetService getInputStream:outputStream:]
• Any error: (NSError**) err method

Note that out parameters work by autoreleasing the value - there may be a design where we embrace this, allowing us to cut down on some unnecessary retains and releases:

// Id<T, O> -> Id<T, O>
{
    let mut foo: Option<Id<T, O>>;
    // let old_foo = foo;
    msg_send![abc, validateValue: &mut foo];
    // [foo retain]
    // [old_foo release]

    drop(foo)
}

// &T -> &T (easily possible today, but not very clear that the reference is bound to the pool)
pool {
    let mut foo: Option<&T>;
    msg_send![abc, validateValue: &mut foo];

    // `foo` still usable inside the pool
}

// Id<T, O> -> &T
// Can be done using the above combined with `Option::as_deref`
pool {
    let foo: Option<Id<T, O>>;

    let mut new_foo: Option<&T> = foo1.as_deref();
    msg_send![abc, validateValue: &mut new_foo];

    // `new_foo` should still somehow be bound to the pool

    drop(foo)
}

// &T -> Id<T, O>
// Can easily be done with a manual `Id::retain`, similar to the above
pool {
    let mut foo: Option<&T>;
    msg_send![abc, validateValue: &mut foo];
    let new_foo: Option<Id<T, O>> = unsafe { Id::retain(foo) };
}

TODO

Many things, including documenting how out and inout parameters work ABI-wise They don't have an effect on the ABI:

• https://stackoverflow.com/questions/5609564/objective-c-in-out-inout-byref-byval-and-so-on-what-are-they
• https://developer.apple.com/documentation/swift/manual-memory-management
• https://developer.apple.com/documentation/swift/autoreleasingunsafemutablepointer
• https://docs.swift.org/swift-book/LanguageGuide/Functions.html#ID173
• -[NSCalendar getEra:yearForWeekOfYear:weekOfYear:weekday:fromDate:]

[madsmtm]

One implementation is the current Id::writeback (name up for bikeshedding).

But I'm wondering whether we could just allow passing &mut Option<Id<T, O>>/Option<&mut Option<Id<T, O>> in msg_send!, and let it automatically handle the required retain/release?

[madsmtm]

Also: Can we let it be automatically handled in declare_class!?

[madsmtm]

For declare_class!, let's have a look at this Objective-C ARC-enabled code:

+(void) outParam: (NSObject * _Nonnull * _Nonnull) param {
    NSObject* x = *param;
    *param = [x description];
    *param = [NSObject new];
}

It compiles to roughly this non-ARC code:

+(void) outParam: (NSObject * _Nonnull * _Nonnull) param {
    NSObject* x = objc_retain(*param);
    @defer { // If such a thing existed
        objc_release(x);
    }

    NSObject* __tmp = [x description];
    retainAutoreleasedReturnValue(__tmp);
    objc_autorelease(__tmp);
    *param = __tmp;

    NSObject* __tmp2 = [NSObject new];
    objc_autorelease(__tmp2);
    *param = __tmp2;
}

The retain/release on x is simply a deficiency in ARC, it has to keep locals alive for longer, if you just did [*param description], then those would not be there. So we don't have to handle that.

To translate the rest to Rust, we could do something like this:

pub struct Helper<T, O>(ManuallyDrop<T, O>);

impl<T, O> Helper<T, O> {
    pub fn write(&mut self, obj: Id<T, O>) {
        objc_autorelease(obj.as_ptr());
        *self.0 = obj;
    }
}

impl<T, O> Deref for Helper<T, O> {
    type Target = T;
}
impl<T, O> DerefMut for Helper<T, O> {}

extern "C" fn out_param(&self, _cmd: Sel, param: &mut Helper<NSObject, Shared>) {
    // *param = ...;
    // ^ would be disallowed, instead we'd do:
    let x = &**param; // If you really wanted the retain/release that ARC does, we could've just done a `.clone()` here
    param.write(x.description());
    param.write(NSObject::new());
}

This would give us the exact same semantics, at the cost of not being able to use &mut Id<T, O> as is otherwise natural :/

I'm wondering if we could perhaps do the following instead:

extern "C" fn out_param(&self, _cmd: Sel, param: &mut Id<NSObject, Shared>) {
    objc_retain(*param);
    {
        let x = &**param;
        *param = x.description();
        *param = NSObject::new();
    }
    objc_autorelease(*param); // Maybe in Drop?
}

Which is roughly the following in Objective-C non-ARC:

+(void) outParam: (NSObject * _Nonnull * _Nonnull) param {
    objc_retain(*param);
    {
        NSObject* __old_param = *param;
        NSObject* __tmp = [__old_param description];
        retainAutoreleasedReturnValue(__tmp);
        *param = __tmp;
        objc_release(__old_param);
    
        NSObject* __old_param = *param;
        *param = [NSObject new];
        objc_release(__old_param);
    }
    objc_autorelease(*param);
}

Which I'm pretty sure would be correct, but it would also be slightly less efficient, since there would basically always be an extra retain/release call than is strictly necessary.

For ergonomics though, I think it's probably the right call to do it this way (also, doing an autorelease by far exceeds the cost of retain/release, so in the case where the variable is assigned to twice, this would very likely be more efficient).

(Note: For NSError parameters we'd already want to something else, so this does not apply there)