Crate objc2

Objective-C interface and runtime bindings

Objective-C is¹ the standard programming language on Apple platforms like macOS, iOS, iPadOS, tvOS and watchOS. It is an object-oriented language centered around “sending messages” to its instances - this can for the most part be viewed as a simple method 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.

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 ensure it is deallocated after we’ve used it by putting it into an rc::Owned rc::Id. Now we’re free to send messages to the object to our hearts desire using the msg_send! or msg_send_id! macros (depending on the return type of the method). Finally, the Id<Object, _> goes out of scope, and the object is released and deallocated.

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

let cls = class!(NSObject);

// Creation

let obj1: Id<Object, Owned> = unsafe { msg_send_id![cls, new] };
let obj2: Id<Object, Owned> = unsafe {
    // Equivalent to using `new`
    msg_send_id![msg_send_id![cls, alloc], init]
};

// Usage

let hash1: NSUInteger = unsafe { msg_send![&obj1, hash] };
let hash2: NSUInteger = unsafe { msg_send![&obj2, hash] };
assert_ne!(hash1, hash2);

let is_kind: bool = unsafe { msg_send![&obj1, isKindOfClass: cls] };
assert!(is_kind);

// We're going to create a new reference to the first object, so
// relinquish mutable ownership.
let obj1: Id<Object, Shared> = obj1.into();
let obj1_self: Id<Object, Shared> = unsafe { msg_send_id![&obj1, self] };
let is_equal: bool = unsafe { msg_send![&obj1, isEqual: &*obj1_self] };
assert!(is_equal);

// Deallocation on drop

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, the foundation module contains more ergonomic usage of at least parts of the Foundation framework.

Anyhow, all of this unsafe 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 (its types are re-exported in this crate).

The important part is: To make message sending safer, 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, we can take advantage of the encodings provided by the runtime to verify that the types used in Rust actually match the types encoded for the method. This is not a perfect solution for ensuring safety (some Rust types have the same Objective-C 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, encodings are checked every time you send a message, and the message send will panic if they are not equivalent.

To take the example above, if we changed the hash method’s return type as in the following example, it panics when the feature is enabled:

// Wrong return type - this is UB!
let hash1: f32 = unsafe { msg_send![&obj1, hash] };

Crate features

This crate exports several optional cargo features, see Cargo.toml for an overview and description of these.

Support for other Operating Systems

The bindings can be used on Linux or *BSD utilizing the GNUstep Objective-C runtime, see the objc-sys crate for how to configure this.

Other functionality

That was a quick introduction, this library also has support for handling exceptions, the ability to dynamically declare Objective-C classes, advanced reference-counting utilities, and more - peruse the documentation at will!

---

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

Re-exports

• pub use objc2_encode::Encode;
• pub use objc2_encode::EncodeArguments;
• pub use objc2_encode::Encoding;
• pub use objc2_encode::RefEncode;
• pub use objc2_encode as encode;
• pub use objc_sys as ffi;

Modules

• declare
  Functionality for dynamically declaring Objective-C classes.
• exception
  Objective-C’s @throw and @try/@catch.
• foundation
  Bindings to the Foundation framework.
• rc
  Utilities for reference counting Objective-C objects.
• runtime
  A Rust interface for the functionality of the Objective-C runtime.

Macros

• class
  Gets a reference to a Class from the given name.
• declare_class
  Declare a new Objective-C class.
• extern_class
  Create a new type to represent an Objective-C class.
• extern_methods
  Define methods on an external class.
• msg_send
  Send a message to an object or class.
• msg_send_boolDeprecated
  Deprecated. Use msg_send! instead.
• msg_send_id
  msg_send! for methods returning id, NSObject*, or similar object pointers.
• ns_string
  Creates an NSString from a static string.
• sel
  Register a selector with the Objective-C runtime.

Traits

• ClassType
  Marks types that represent specific classes.
• Message
  Types that can be sent Objective-C messages.
• MessageArguments
  Types that may be used as the arguments of an Objective-C message.
• MessageReceiver
  Types that can directly be used as the receiver of Objective-C messages.