Expand description
Objective-C interface and runtime bindings
Objective-C is1 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!, msg_send_bool! 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_bool, 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].expect("Failed allocating")
};
let obj2: Id<Object, Owned> = unsafe {
// Equivalent to using `new`
msg_send_id![msg_send_id![cls, alloc], init].expect("Failed allocating")
};
// Usage
let hash1: NSUInteger = unsafe { msg_send![&obj1, hash] };
let hash2: NSUInteger = unsafe { msg_send![&obj2, hash] };
assert_ne!(hash1, hash2);
let is_kind = unsafe { msg_send_bool![&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].unwrap() };
let is_equal = unsafe { msg_send_bool![&obj1, isEqual: &*obj1_self] };
assert!(is_equal);
// Deallocation on dropNote 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 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!
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 as encode;pub use objc_sys as ffi;pub use objc2_encode::Encode;pub use objc2_encode::EncodeArguments;pub use objc2_encode::Encoding;pub use objc2_encode::RefEncode;Modules
Functionality for declaring Objective-C classes.
Objective-C’s @throw and @try/@catch.
Utilities for reference counting Objective-C objects.
A Rust interface for the functionality of the Objective-C runtime.
Macros
Send a message to an object or class.
msg_send! for methods returning BOOL.
msg_send! for methods returning id, NSObject*, or similar object
pointers.
Register a selector with the Objective-C runtime.
Structs
Failed verifying selector on a class.
Traits
Types that can be sent Objective-C messages.
Types that may be used as the arguments of an Objective-C message.
Types that can directly be used as the receiver of Objective-C messages.