Struct objc2::rc::Id

pub struct Id<T: ?Sized> { /* private fields */ }

A reference counted pointer type for Objective-C objects.

Id strongly references or “retains” the given object T, and decrements the retain count or “releases” it again when dropped, thereby ensuring it will be deallocated at the right time.

The type T inside Id<T> can be anything that implements Message.

T’s ClassType implementation (if any) determines whether it is mutable, and by extension whether Id<T> is mutable.

This can usually be gotten from one of the methods in icrate, but can be created manually with the msg_send_id! macro (or even more manually, with the Id::new, Id::retain or Id::retain_autoreleased methods).

Comparison to std types

Id<T> can be thought of as kind of a weird combination of Arc and Box:

If T implements IsMutable (like it does on NSMutableString and NSMutableArray<_>), Id<T> acts like Box<T>, and allows mutable / unique access to the type.

Otherwise, which is the most common case, Id<T> acts like Arc<T>, and allows cloning by bumping the reference count.

Forwarding implementations

Since Id<T> is a smart pointer, it Derefs to T, and similarly implements DerefMut when mutable.

It also forwards the implementation of a bunch of standard library traits such as PartialEq, AsRef, and so on, so that it becomes possible to use e.g. Id<NSString> as if it was NSString. (Having NSString directly is not possible since Objective-C objects cannot live on the stack, but instead must reside on the heap).

Note that because of current limitations in the Rust trait system, some traits like Default, IntoIterator, FromIterator, From and Into are not directly implementable on NSString; for that use-case, we instead provide the DefaultId, IdIntoIterator and IdFromIterator traits, which make some of the the aforementioned traits implementable on Id.

Memory layout

This is guaranteed to have the same size and alignment as a pointer to the object, *const T.

Additionally, it participates in the null-pointer optimization, that is, Option<Id<T>> is guaranteed to have the same size as Id<T>.

Example

Various usage of Id on an immutable object.

use icrate::Foundation::{NSObject, NSString};
use objc2::rc::Id;
use objc2::{ClassType, msg_send_id};

// Use `msg_send_id!` to create an `Id` with correct memory management
//
// SAFETY: The types are correct, and it is safe to call the `new`
// selector on `NSString`.
let string: Id<NSString> = unsafe { msg_send_id![NSString::class(), new] };
// Or:
// let string = NSString::new();

// Methods on `NSString` is usable via. `Deref`
#[cfg(not_available)]
assert_eq!(string.len(), 0);

// Bump the reference count of the object (possible because the object is
// immutable, would not be possible for `NSMutableString`).
let another_ref: Id<NSString> = string.clone();

// Convert one of the references to a reference to `NSObject` instead
let obj: Id<NSObject> = Id::into_super(string);

// And use the `Debug` impl from that
assert_eq!(format!("{obj:?}"), "");

// Finally, the `Id`s go out of scope, the reference counts are decreased,
// and the string will deallocate

Implementations

impl<T: ?Sized + Message> Id<T>

pub unsafe fn new(ptr: *mut T) -> Option<Self>

Construct an Id from a pointer that already has +1 retain count.

Returns None if the pointer was NULL.

This is useful when you have a retain count that has been handed off from somewhere else, usually Objective-C methods like init, alloc, new, copy, or methods with the ns_returns_retained attribute.

Safety

You must uphold the same requirements as described in Id::retain.

Additionally, you must ensure the given object pointer has +1 retain count.

Example

Comparing different ways of creating a new NSObject.

use objc2::rc::Id;
use objc2::runtime::NSObject;
use objc2::{msg_send, msg_send_id, ClassType};

// Manually using `msg_send!` and `Id::new`
let obj: *mut NSObject = unsafe { msg_send![NSObject::class(), alloc] };
let obj: *mut NSObject = unsafe { msg_send![obj, init] };
// SAFETY: `-[NSObject init]` returns +1 retain count
let obj: Id<NSObject> = unsafe { Id::new(obj).unwrap() };

// Or with `msg_send_id!`
let obj: Id<NSObject> = unsafe { msg_send_id![NSObject::alloc(), init] };

// Or using the `NSObject::new` method
let obj = NSObject::new();

pub fn as_ptr(this: &Self) -> *const T

Returns a raw pointer to the object.

The pointer is valid for at least as long as the Id is held.

See Id::as_mut_ptr for the mutable equivalent.

This is an associated method, and must be called as Id::as_ptr(obj).

pub fn as_mut_ptr(this: &mut Self) -> *mut T

where T: IsMutable,

Returns a raw mutable pointer to the object.

The pointer is valid for at least as long as the Id is held.

See Id::as_ptr for the immutable equivalent.

This is an associated method, and must be called as Id::as_mut_ptr(obj).

impl<T: Message> Id<T>

pub unsafe fn cast<U: Message>(this: Self) -> Id<U>

Convert the type of the given object to another.

This is equivalent to a cast between two pointers.

See Id::into_super and ProtocolObject::from_id for safe alternatives.

This is common to do when you know that an object is a subclass of a specific class (e.g. casting an instance of NSString to NSObject is safe because NSString is a subclass of NSObject).

All 'static objects can safely be cast to AnyObject, since that assumes no specific class.

Safety

You must ensure that the object can be reinterpreted as the given type.

If T is not 'static, you must ensure that U ensures that the data contained by T is kept alive for as long as U lives.

Additionally, you must ensure that any safety invariants that the new type has are upheld.

Note that it is not in general safe to cast e.g. Id<NSString> to Id<NSMutableString>, even if you’ve checked at runtime that the object is an instance of NSMutableString! This is because Id<NSMutableString> assumes the string is unique, whereas it may have been cloned while being an Id<NSString>.

pub unsafe fn retain(ptr: *mut T) -> Option<Id<T>>

Retain the pointer and construct an Id from it.

Returns None if the pointer was NULL.

This is useful when you have been given a pointer to an object from some API, and you would like to ensure that the object stays around while you work on it.

For normal Objective-C methods, you may want to use Id::retain_autoreleased instead, as that is usually more performant.

See ClassType::retain for a safe alternative.

Safety

If the object is mutable, the caller must ensure that there are no other pointers or references to the object, such that the returned Id pointer is unique.

Additionally, the pointer must be valid as a reference (aligned, dereferencable and initialized, see the std::ptr module for more information) or NULL.

Finally, you must ensure that any data that T may reference lives for at least as long as T.

pub unsafe fn retain_autoreleased(ptr: *mut T) -> Option<Id<T>>

Retains a previously autoreleased object pointer.

This is useful when calling Objective-C methods that return autoreleased objects, see Cocoa’s Memory Management Policy.

This has exactly the same semantics as Id::retain, except it can sometimes avoid putting the object into the autorelease pool, possibly yielding increased speed and reducing memory pressure.

Note: This relies heavily on being inlined right after msg_send!, be careful to not accidentally require instructions between these.

Safety

Same as Id::retain.

pub fn autorelease<'p>(this: Self, pool: AutoreleasePool<'p>) -> &'p T

Autoreleases the Id, returning a reference bound to the pool.

The object is not immediately released, but will be when the innermost / current autorelease pool (given as a parameter) is drained.

See Id::autorelease_mut for the mutable alternative.

This is an associated method, and must be called as Id::autorelease(obj, pool).

pub fn autorelease_mut<'p>(this: Self, pool: AutoreleasePool<'p>) -> &'p mut T

where T: IsMutable,

Autoreleases the Id, returning a mutable reference bound to the pool.

The object is not immediately released, but will be when the innermost / current autorelease pool (given as a parameter) is drained.

See Id::autorelease for the immutable alternative.

This is an associated method, and must be called as Id::autorelease_mut(obj, pool).

pub fn autorelease_return(this: Self) -> *mut T

Autoreleases and prepares the Id to be returned to Objective-C.

The object is not immediately released, but will be when the innermost autorelease pool is drained.

This is useful when declaring your own methods where you will often find yourself in need of returning autoreleased objects to properly follow Cocoa’s Memory Management Policy.

To that end, you could use Id::autorelease, but that would require you to have an AutoreleasePool object at hand, which you often won’t have in such cases. This function doesn’t require a pool object (but as a downside returns a pointer instead of a reference).

This is also more efficient than a normal autorelease, since it makes a best effort attempt to hand off ownership of the retain count to a subsequent call to objc_retainAutoreleasedReturnValue / Id::retain_autoreleased in the enclosing call frame.

This optimization relies heavily on this function being tail called, so make sure you only call this function at the end of your method.

Example

Returning an Id from a declared method (note: the declare_class! macro supports doing this for you automatically).

use objc2::{class, msg_send_id, sel};
use objc2::declare::ClassBuilder;
use objc2::rc::Id;
use objc2::runtime::{AnyClass, AnyObject, Sel};

let mut builder = ClassBuilder::new("ExampleObject", class!(NSObject)).unwrap();

extern "C" fn get(cls: &AnyClass, _cmd: Sel) -> *mut AnyObject {
    let obj: Id<AnyObject> = unsafe { msg_send_id![cls, new] };
    Id::autorelease_return(obj)
}

unsafe {
    builder.add_class_method(
        sel!(get),
        get as extern "C" fn(_, _) -> _,
    );
}

let cls = builder.register();

impl<T: ClassType + 'static> Id<T>

where T::Super: 'static,

pub fn into_super(this: Self) -> Id<T::Super>

Convert the object into its superclass.

Trait Implementations

impl<T: ?Sized + IsMutable> AsMut<T> for Id<T>

fn as_mut(&mut self) -> &mut T

Converts this type into a mutable reference of the (usually inferred) input type.

impl<T: ?Sized> AsRef<T> for Id<T>

fn as_ref(&self) -> &T

Converts this type into a shared reference of the (usually inferred) input type.

impl<T: ?Sized> Borrow<T> for Id<T>

fn borrow(&self) -> &T

Immutably borrows from an owned value.

impl<T: ?Sized + IsMutable> BorrowMut<T> for Id<T>

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value.

impl<T: BufRead + ?Sized + IsMutable> BufRead for Id<T>

fn fill_buf(&mut self) -> Result<&[u8]>

Returns the contents of the internal buffer, filling it with more data from the inner reader if it is empty.

fn consume(&mut self, amt: usize)

Tells this buffer that amt bytes have been consumed from the buffer, so they should no longer be returned in calls to read.

fn read_until(&mut self, byte: u8, buf: &mut Vec<u8>) -> Result<usize>

Read all bytes into buf until the delimiter byte or EOF is reached.

fn read_line(&mut self, buf: &mut String) -> Result<usize>

Read all bytes until a newline (the 0xA byte) is reached, and append them to the provided String buffer.

fn has_data_left(&mut self) -> Result<bool, Error>

🔬This is a nightly-only experimental API. (buf_read_has_data_left)

Check if the underlying Read has any data left to be read.

fn skip_until(&mut self, byte: u8) -> Result<usize, Error>

🔬This is a nightly-only experimental API. (bufread_skip_until)

Skip all bytes until the delimiter byte or EOF is reached.

fn split(self, byte: u8) -> Split<Self>

where Self: Sized,

Returns an iterator over the contents of this reader split on the byte byte.

fn lines(self) -> Lines<Self>

where Self: Sized,

Returns an iterator over the lines of this reader.

impl<T: Message + IsIdCloneable> Clone for Id<T>

fn clone(&self) -> Self

Makes a clone of the shared object.

This increases the object’s reference count.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug + ?Sized> Debug for Id<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: ?Sized + DefaultId> Default for Id<T>

fn default() -> Self

Returns the “default value” for a type.

impl<T: ?Sized> Deref for Id<T>

fn deref(&self) -> &T

Obtain an immutable reference to the object.

type Target = T

The resulting type after dereferencing.

impl<T: ?Sized + IsMutable> DerefMut for Id<T>

fn deref_mut(&mut self) -> &mut T

Obtain a mutable reference to the object.

impl<T: Display + ?Sized> Display for Id<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: ?Sized> Drop for Id<T>

#[may_dangle] (see this) doesn’t apply here since we don’t run T’s destructor (rather, we want to discourage having Ts with a destructor); and even if we did run the destructor, it would not be safe to add since we cannot verify that a dealloc method doesn’t access borrowed data.

fn drop(&mut self)

Releases the retained object.

The contained object’s destructor (Drop impl, if it has one) is never run - override the dealloc method instead (which declare_class! does for you).

impl<T: Error + ?Sized> Error for Id<T>

fn source(&self) -> Option<&(dyn Error + 'static)>

The lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type based access to context intended for error reports.

impl<T: Message + IsIdCloneable> From<&Id<T>> for WeakId<T>

fn from(obj: &Id<T>) -> Self

Converts to this type from the input type.

impl<T: Message + IsIdCloneable> From<Id<T>> for WeakId<T>

fn from(obj: Id<T>) -> Self

Converts to this type from the input type.

impl<T, U: IdFromIterator<T>> FromIterator<T> for Id<U>

fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self

Creates a value from an iterator.

impl<T: Future + Unpin + ?Sized + IsMutable> Future for Id<T>

type Output = <T as Future>::Output

The type of value produced on completion.

fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>

Attempt to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.

impl<T: Hash + ?Sized> Hash for Id<T>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T: Hasher + ?Sized + IsMutable> Hasher for Id<T>

fn finish(&self) -> u64

Returns the hash value for the values written so far.

fn write(&mut self, bytes: &[u8])

Writes some data into this Hasher.

fn write_u8(&mut self, i: u8)

Writes a single u8 into this hasher.

fn write_u16(&mut self, i: u16)

Writes a single u16 into this hasher.

fn write_u32(&mut self, i: u32)

Writes a single u32 into this hasher.

fn write_u64(&mut self, i: u64)

Writes a single u64 into this hasher.

fn write_u128(&mut self, i: u128)

Writes a single u128 into this hasher.

fn write_usize(&mut self, i: usize)

Writes a single usize into this hasher.

fn write_i8(&mut self, i: i8)

Writes a single i8 into this hasher.

fn write_i16(&mut self, i: i16)

Writes a single i16 into this hasher.

fn write_i32(&mut self, i: i32)

Writes a single i32 into this hasher.

fn write_i64(&mut self, i: i64)

Writes a single i64 into this hasher.

fn write_i128(&mut self, i: i128)

Writes a single i128 into this hasher.

fn write_isize(&mut self, i: isize)

Writes a single isize into this hasher.

fn write_length_prefix(&mut self, len: usize)

🔬This is a nightly-only experimental API. (hasher_prefixfree_extras)

Writes a length prefix into this hasher, as part of being prefix-free.

fn write_str(&mut self, s: &str)

🔬This is a nightly-only experimental API. (hasher_prefixfree_extras)

Writes a single str into this hasher.

impl<'a, T: ?Sized> IntoIterator for &'a Id<T>

where &'a T: IntoIterator,

type Item = <&'a T as IntoIterator>::Item

The type of the elements being iterated over.

type IntoIter = <&'a T as IntoIterator>::IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, T: ?Sized + IsMutable> IntoIterator for &'a mut Id<T>

where &'a mut T: IntoIterator,

type Item = <&'a mut T as IntoIterator>::Item

The type of the elements being iterated over.

type IntoIter = <&'a mut T as IntoIterator>::IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T: ?Sized + IdIntoIterator> IntoIterator for Id<T>

type Item = <T as IdIntoIterator>::Item

The type of the elements being iterated over.

type IntoIter = <T as IdIntoIterator>::IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T: Ord + ?Sized> Ord for Id<T>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl<T: PartialEq + ?Sized> PartialEq for Id<T>

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Self) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: PartialOrd + ?Sized> PartialOrd for Id<T>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Self) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Self) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn ge(&self, other: &Self) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

fn gt(&self, other: &Self) -> bool

This method tests greater than (for self and other) and is used by the > operator.

impl<T: ?Sized> Pointer for Id<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Read + ?Sized + IsMutable> Read for Id<T>

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize>

Like read, except that it reads into a slice of buffers.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize>

Read all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize>

Read all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<()>

Read the exact number of bytes required to fill buf.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Read the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

impl<T: Seek + ?Sized + IsMutable> Seek for Id<T>

fn seek(&mut self, pos: SeekFrom) -> Result<u64>

Seek to an offset, in bytes, in a stream.

fn stream_position(&mut self) -> Result<u64>

Returns the current seek position from the start of the stream.

fn rewind(&mut self) -> Result<(), Error>

Rewind to the beginning of a stream.

fn stream_len(&mut self) -> Result<u64, Error>

🔬This is a nightly-only experimental API. (seek_stream_len)

Returns the length of this stream (in bytes).

fn seek_relative(&mut self, offset: i64) -> Result<(), Error>

🔬This is a nightly-only experimental API. (seek_seek_relative)

Seeks relative to the current position.

impl<T: Write + ?Sized + IsMutable> Write for Id<T>

fn write(&mut self, buf: &[u8]) -> Result<usize>

Write a buffer into this writer, returning how many bytes were written.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize>

Like write, except that it writes from a slice of buffers.

fn flush(&mut self) -> Result<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_all(&mut self, buf: &[u8]) -> Result<()>

Attempts to write an entire buffer into this writer.

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<()>

Writes a formatted string into this writer, returning any error encountered.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.

impl<T: Eq + ?Sized> Eq for Id<T>

impl<T: ?Sized + RefUnwindSafe> RefUnwindSafe for Id<T>

impl<T: ?Sized + ClassType + Send> Send for Id<T>

where T::Mutability: IdSendSyncHelper<T>, EquivalentType<T>: Send,

Id<T> is always Send if T is Send + Sync.

Additionally, for mutable types, T doesn’t have to be Sync (only requires T: Send), since it has unique access to the object.

impl<T: ?Sized + ClassType + Sync> Sync for Id<T>

where T::Mutability: IdSendSyncHelper<T>, EquivalentType<T>: Sync,

Id<T> is always Sync if T is Send + Sync.

Additionally, for mutable types, T doesn’t have to be Send (only requires T: Sync), since it has unique access to the object.

impl<T: ?Sized> Unpin for Id<T>

impl<T: ?Sized + RefUnwindSafe + UnwindSafe> UnwindSafe for Id<T>