Crate objc2

source ·
Expand description

§Objective-C interface and runtime bindings

Quick links:

Objective-C was 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 function call.

It has since been superseded by Swift, but most of the core libraries and frameworks that are in use on Apple systems are still 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 allocate a new NSObject using ClassType::alloc. Next, we initialize this object. It is ensured to be deallocated using rc::Retained. 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 Retained goes out of scope, and the object is released and deallocated.

use objc2::{msg_send, msg_send_id, ClassType};
use objc2::ffi::NSUInteger;
use objc2::rc::Retained;
use objc2::runtime::{NSObject, NSObjectProtocol};

// Creation

let obj1: Retained<NSObject> = unsafe {
    msg_send_id![NSObject::alloc(), init]
};
// Or
let obj2 = NSObject::new();

// 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: NSObject::class()]
};
assert!(is_kind);

let obj1_self: Retained<NSObject> = unsafe { msg_send_id![&obj1, self] };
assert_eq!(obj1, obj1_self);

// Deallocation on drop

Note that this 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 accidentally made hash an f32, or any other type, and this would trigger undefined behaviour!

See the framework crates for much more ergonomic usage of the system frameworks like Foundation, AppKit, UIKit and so on.

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 encode module for a full overview of what this is.

The important part is: To make message sending safer, all arguments and return values for messages must implement encode::Encode. This allows the Rust compiler to prevent you from passing e.g. a Vec into Objective-C, which would both be UB and leak the vector.

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, such as &T and *const T), but it gets us much closer to it!

When debug_assertions are enabled we check the encoding 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’ll panic if debug assertions are enabled:

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

This library contains further such debug checks.

§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 declare Objective-C classes, advanced reference-counting utilities, and more - peruse the documentation at will!

Re-exports§

Modules§

  • declareDeprecated
    Deprecated location for a few things that are now in the runtime module.
  • Support for type-encodings.
  • @throw and @try/@catch exceptions.
  • Marker types for class mutability.
  • Reference counting utilities.
  • Direct runtime bindings.
  • topicsNowhere
    Various explanations and topics of discussion.

Macros§

Traits§

  • Marks types that represent specific classes.
  • Marks types whose implementation is defined in Rust.
  • Types that can be sent Objective-C messages.
  • Marks types that represent specific protocols.