Struct objc2::rc::Allocated

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

An Objective-C object that has been allocated, but not initialized.

Objective-C splits the allocation and initialization steps up into two, so we need to track it in the type-system whether something has been intialized or not.

Note that allocation in Objective-C can fail, e.g. in Out Of Memory situations! This is handled by objc2 automatically, but if you really need to, you can check for this explicitly by inspecting the pointer returned from as_ptr.

Note also that this represents that the current class’s instance variables are not yet initialized; but subclass instance variables may have been so.

See Apple’s documentation on Object Allocation for a few more details.

Memory layout

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

Implementations

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

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

See Allocated::as_mut_ptr for the mutable equivalent.

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

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

Returns a raw mutable pointer to the object.

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

See Allocated::as_ptr for the immutable equivalent.

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

Note about mutable references

In general, you’re not allowed to create a mutable reference from Allocated, unless you’re defining the object and know that to be safe.

For example, +[NSMutableString alloc] is allowed to return a non-unique object as an optimization, and then only figure out afterwards whether it needs to allocate, or if it can store an NSString internally.

Similarly, while e.g. +[NSData alloc] may return a unique object, calling -[NSData init] afterwards could return a shared empty NSData instance.

pub fn set_ivars(self, ivars: T::Ivars) -> PartialInit<T>

where T: DeclaredClass + Sized,

Initialize the instance variables for this object.

This consumes the allocated instance, and returns the now partially initialized instance instead, which can be further used in msg_send_id! super calls.

This works very similarly to Swift’s two-phase initialization scheme, see that for details.

Panics

If debug assertions are enabled, this function will panic if the allocated instance is NULL, which usually only happens in Out of Memory situations.

If debug assertions are disabled, this will return a NULL instance and the ivars will be dropped. The NULL instance cannot cause unsoundness and will likely lead to an initialization failure later on instead, but not panicking here is done as a code-size optimization.

Trait Implementations

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

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

Formats the value using the given formatter.

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

fn drop(&mut self)

Executes the destructor for this type.

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

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

Formats the value using the given formatter.