Struct objc2::rc::Retained

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

A reference counted pointer type for Objective-C objects.

Retained 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 Retained<T> can be anything that implements Message.

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

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

Comparison to std types

Retained<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<_>), Retained<T> acts like Box<T>, and allows mutable / unique access to the type.

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

Forwarding implementations

Since Retained<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. Retained<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 DefaultRetained, RetainedIntoIterator and RetainedFromIterator traits, which make some of the the aforementioned traits implementable on Retained.

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<Retained<T>> is guaranteed to have the same size as Retained<T>.

Example

Various usage of Retained on an immutable object.

use objc2_foundation::{NSObject, NSString};
use objc2::rc::Retained;
use objc2::{ClassType, msg_send_id};

// Use `msg_send_id!` to create an `Retained` with correct memory management
//
// SAFETY: The types are correct, and it is safe to call the `new`
// selector on `NSString`.
let string: Retained<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: Retained<NSString> = string.clone();

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

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

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

Implementations

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

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

Construct an Retained 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.

If you do not have +1 retain count, such as if your object was retrieved from other methods than the ones noted above, use Retained::retain instead.

Safety

You must uphold the same requirements as described in Retained::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::Retained;
use objc2::runtime::NSObject;
use objc2::{msg_send, msg_send_id, ClassType};

// Manually using `msg_send!` and `Retained::from_raw`
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: Retained<NSObject> = unsafe { Retained::from_raw(obj).unwrap() };

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

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

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

👎Deprecated: use the more descriptive name Retained::from_raw instead

Deprecated alias for Retained::from_raw, see that for details.

Safety

Same as Retained::from_raw.

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

Consumes the Retained, returning a raw pointer with +1 retain count.

After calling this function, the caller is responsible for the memory previously managed by the Retained.

This is effectively the opposite of Retained::from_raw, see that for more details on when this function is useful.

Examples

Converting an Retained to a pointer and back.

use objc2::rc::Retained;
use objc2::runtime::NSObject;

let obj = NSObject::new();
let ptr = Retained::into_raw(obj);
// SAFETY: The pointer is valid, and has +1 retain count from above.
let obj = unsafe { Retained::from_raw(ptr) }.unwrap();

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 Retained is held.

See Retained::as_mut_ptr for the mutable equivalent.

This is an associated method, and must be called as Retained::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 Retained is held.

See Retained::as_ptr for the immutable equivalent.

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

impl<T: Message> Retained<T>

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

Convert the type of the given object to another.

This is equivalent to a cast between two pointers.

See Retained::into_super and ProtocolObject::from_retained 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. Retained<NSString> to Retained<NSMutableString>, even if you’ve checked at runtime that the object is an instance of NSMutableString! This is because Retained<NSMutableString> assumes the string is unique, whereas it may have been cloned while being an Retained<NSString>.

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

Retain the pointer and construct an Retained 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 Retained::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 Retained 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<Retained<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 Retained::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 Retained::retain.

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

Autoreleases the Retained, returning a pointer.

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

This is useful when defining your own classes and you have some error parameter passed as Option<&mut *mut NSError>, and you want to create and autorelease an error before returning.

See Retained::autorelease and Retained::autorelease_mut for alternatives that yield safe references.

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

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

Autoreleases the Retained, 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 Retained::autorelease_mut for the mutable alternative.

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

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

where T: IsMutable,

Autoreleases the Retained, 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 Retained::autorelease for the immutable alternative.

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

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

Autoreleases and prepares the Retained 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 Retained::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 / Retained::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 Retained 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::Retained;
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: Retained<AnyObject> = unsafe { msg_send_id![cls, new] };
    Retained::autorelease_return(obj)
}

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

let cls = builder.register();

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

where T::Super: 'static,

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

Convert the object into its superclass.

Trait Implementations

impl<T: ?Sized + IsMutable> AsMut<T> for Retained<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 Retained<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 Retained<T>

fn borrow(&self) -> &T

Immutably borrows from an owned value.

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

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

Mutably borrows from an owned value.

impl<T: BufRead + ?Sized + IsMutable> BufRead for Retained<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 Retained<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 Retained<T>

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

Formats the value using the given formatter.

impl<T: ?Sized + DefaultRetained> Default for Retained<T>

fn default() -> Self

Returns the “default value” for a type.

impl<T: ?Sized> Deref for Retained<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 Retained<T>

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

Obtain a mutable reference to the object.

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

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

Formats the value using the given formatter.

impl<T: ?Sized> Drop for Retained<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 Retained<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<&Retained<T>> for Weak<T>

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

Converts to this type from the input type.

impl<T: Message + IsIdCloneable> From<Retained<T>> for Weak<T>

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

Converts to this type from the input type.

impl<T, U: RetainedFromIterator<T>> FromIterator<T> for Retained<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 Retained<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 Retained<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 Retained<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 Retained<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 Retained<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 + RetainedIntoIterator> IntoIterator for Retained<T>

type Item = <T as RetainedIntoIterator>::Item

The type of the elements being iterated over.

type IntoIter = <T as RetainedIntoIterator>::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 Retained<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 Retained<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 Retained<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 Retained<T>

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

Formats the value using the given formatter.

impl<T: Read + ?Sized + IsMutable> Read for Retained<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 Retained<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>

Seeks relative to the current position.

impl<T: Write + ?Sized + IsMutable> Write for Retained<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 Retained<T>

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

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

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

Retained<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 Retained<T>

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

Retained<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 Retained<T>

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