Crate objc2

Expand description

Objective-C interface and runtime bindings

Objective-C is¹ the standard programming language on Apple platforms like macOS, iOS, tvOS and watchOS. It is an object-oriented language centered around sending messages to it’s instances, which is for the most part equivalent to a function call.

Most of the core libraries and frameworks that are in use on Apple systems are written in Objective-C, and hence we would like the ability to interract with these using Rust; this crate enables you to do that, in as safe a manner as possible.

^{1: Yes, I know, “was”, Swift now exists. All the existing frameworks
are written in Objective-C though, so the point still holds.}

Basic usage

This example illustrates major parts of the functionality in this crate:

First, we get a reference to the NSObject’s runtime::Class using the class! macro. Next, we creates a new runtime::Object pointer, and ensures it is deallocated after we’ve used it by putting it into an rc::Owned rc::Id. Now we send messages to the object to our hearts desire using the msg_send! macro, and lastly, the Id<Object, _> goes out of scope, and the object is deallocated.

use objc2::{class, msg_send, msg_send_bool};
use objc2::ffi::NSUInteger;
use objc2::rc::{Id, Owned};
use objc2::runtime::Object;

// Creation
let cls = class!(NSObject);
let obj: *mut Object = unsafe { msg_send![cls, new] };
let obj: Id<Object, Owned> = unsafe {
    Id::new(obj).expect("Failed allocating object")
};

// Usage
let hash: NSUInteger = unsafe { msg_send![&obj, hash] };
let is_kind = unsafe { msg_send_bool![&obj, isKindOfClass: cls] };
assert!(is_kind);

Note that this very simple example contains a lot of unsafe (which should all ideally be justified with a // SAFETY comment). This is required because our compiler can verify very little about the Objective-C invocation, including all argument and return types used in msg_send!; we could have just as easily accidentally made hash an f32, or any other type, and this would trigger undefined behaviour!

Making the ergonomics better is something that is currently being worked on, see e.g. the objc2-foundation crate for more ergonomic usage of at least the Foundation framework.

Anyhow, this nicely leads us to another feature that this crate has:

Encodings and message type verification

The Objective-C runtime includes encodings for each method that describe the argument and return types. See the objc2-encode crate for the full overview of what this is.

The important part is, to make message sending safer (not fully safe), all arguments and return values for messages must implement Encode. This allows the Rust compiler to prevent you from passing e.g. a Box into Objective-C, which would both be UB and leak the box.

Furthermore, this crate can take advantage of the encodings provided by the runtime to verify that the types used in Rust match the types encoded for the method. This is not a perfect solution for ensuring safety of message sends (some Rust types have the same encoding, but are not equivalent), but it gets us much closer to it!

To use this functionality, enable the "verify_message" cargo feature while debugging. With this feature enabled, encoding types are checked every time your send a message, and the message send will panic if they are not equivalent.