Struct DispatchRetained 

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

A reference counted pointer type for Dispatch objects.

DispatchRetained 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 DispatchRetained<T> can be anything that implements DispatchObject, i.e. any Dispatch object.

Comparison to other types

DispatchRetained<T> is equivalent to objc2::rc::Retained, and can be converted to/from that when the "objc2" feature is enabled. Note though that this type uses the underlying Dispatch primitives dispatch_retain / dispatch_release instead of objc_retain / objc_release for performance, and to avoid depending on the Objective-C runtime if not needed.

You can also view DispatchRetained<T> as the Dispatch equivalent of std::sync::Arc, that is, it is a thread-safe reference-counting smart pointer that allows cloning by bumping the reference count.

Unlike Arc, objects can be retained directly from a &T using DispatchObject::retain (for Arc you need &Arc<T>).

Weak references are not supported, for that you need to convert to objc2::rc::Retained.

Forwarding implementations

Since DispatchRetained<T> is a smart pointer, it Derefs to T.

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. DispatchRetained<DispatchQueue> as-if it you had a &DispatchQueue. Note that having a DispatchQueue directly is not possible since dispatch objects cannot live on the stack, but instead must reside on the heap, and as such must be accessed behind a pointer or a reference.

Memory layout

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

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

Implementations

impl<T: ?Sized + DispatchObject> DispatchRetained<T>

pub unsafe fn from_raw(ptr: NonNull<T>) -> Self

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

This is useful when you have been given a pointer to an object from some API that returns a retained pointer, and expects you to release it. That is, an API that follows the create rule.

Safety

The pointer must be a valid and live object according to Dispatch, and it must be of type T.

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

pub unsafe fn retain(ptr: NonNull<T>) -> Self

Retain the pointer and construct a DispatchRetained from it.

This is useful when you have been given a pointer to an object from some API that follows the get rule, and you would like to keep it around for longer than the current memory context.

Safety

The pointer must be a valid and live object according to Dispatch, and it must be of type T.

pub fn into_raw(this: Self) -> NonNull<T>

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

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

This is effectively the opposite of DispatchRetained::from_raw.

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

pub fn as_ptr(this: &Self) -> NonNull<T>

Returns a raw pointer to the object.

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

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

pub unsafe fn cast_unchecked<U: DispatchObject>( this: Self, ) -> DispatchRetained<U>

Unchecked conversion to another Dispatch object.

This is equivalent to a cast between two pointers.

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

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.

Trait Implementations

impl<T: ?Sized + AsRef<U>, U: ?Sized> AsRef<U> for DispatchRetained<T>

fn as_ref(&self) -> &U

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

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

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

Formats the value using the given formatter.

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

fn borrow(&self) -> &T

Immutably borrows from an owned value.

impl<T: ?Sized + DispatchObject> Clone for DispatchRetained<T>

fn clone(&self) -> Self

Retain the object, increasing its reference count.

This calls DispatchObject::retain internally.

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> Deref for DispatchRetained<T>

fn deref(&self) -> &T

Obtain a reference to the object.

type Target = T

The resulting type after dereferencing.

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

fn drop(&mut self)

Releases the contained object.

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

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

Returns 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<'a, A, T: ?Sized> Extend<A> for &'a DispatchRetained<T>

where &'a T: Extend<A>,

fn extend<I: IntoIterator<Item = A>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

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

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

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

Reserves capacity in a collection for the given number of additional elements.

impl<A, T: ?Sized> Extend<A> for DispatchRetained<T>

where for<'a> &'a T: Extend<A>,

fn extend<I: IntoIterator<Item = A>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

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

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

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

Reserves capacity in a collection for the given number of additional elements.

impl<T: ?Sized + AsRef<U>, U: DispatchObject> From<&T> for DispatchRetained<U>

fn from(obj: &T) -> Self

Cast the object to a superclass, and retain it.

impl<T: ?Sized + DispatchObject + Message> From<DispatchRetained<T>> for Retained<T>

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

Convert a DispatchRetained into a objc2::rc::Retained.

This conversion is cost-free, since Dispatch objects are fully interoperable with Objective-C retain/release message sending.

impl<T: ?Sized + DispatchObject + Message> From<Retained<T>> for DispatchRetained<T>

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

Convert a objc2::rc::Retained into a DispatchRetained.

This only works if the type is a Dispatch object (implements the DispatchObject trait).

This conversion is cost-free.

impl<'a, T: ?Sized> Future for &'a DispatchRetained<T>

where &'a T: Future,

type Output = <&'a T as Future>::Output

The type of value produced on completion.

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

Attempts 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 DispatchRetained<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<'a, T: ?Sized> Hasher for &'a DispatchRetained<T>

where &'a T: Hasher,

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<T: ?Sized> Hasher for DispatchRetained<T>

where for<'a> &'a T: Hasher,

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<T: LowerExp + ?Sized> LowerExp for Retained<T>

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

Formats the value using the given formatter.

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

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

Formats the value using the given formatter.

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

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

Formats the value using the given formatter.

impl<T: Ord + ?Sized> Ord for DispatchRetained<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,

Restrict a value to a certain interval.

impl<T: ?Sized + PartialEq<U>, U: ?Sized> PartialEq<DispatchRetained<U>> for DispatchRetained<T>

fn eq(&self, other: &Retained<U>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Retained<U>) -> bool

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

impl<T: ?Sized + PartialOrd<U>, U: ?Sized> PartialOrd<DispatchRetained<U>> for DispatchRetained<T>

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

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

fn lt(&self, other: &Retained<U>) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Retained<U>) -> bool

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

fn ge(&self, other: &Retained<U>) -> bool

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

fn gt(&self, other: &Retained<U>) -> bool

Tests greater than (for self and other) and is used by the > operator.

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

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

Formats the value using the given formatter.

impl<'a, T: ?Sized> Read for &'a DispatchRetained<T>

where &'a T: Read,

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>

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

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

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

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

Reads 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)

Reads 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: ?Sized> Read for DispatchRetained<T>

where for<'a> &'a T: Read,

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>

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

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

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

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

Reads 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)

Reads 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<'a, T: ?Sized> Seek for &'a DispatchRetained<T>

where &'a T: Seek,

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: ?Sized> Seek for DispatchRetained<T>

where for<'a> &'a T: Seek,

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: UpperExp + ?Sized> UpperExp for Retained<T>

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

Formats the value using the given formatter.

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

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

Formats the value using the given formatter.

impl<'a, T: ?Sized> Write for &'a DispatchRetained<T>

where &'a T: Write,

fn write_str(&mut self, s: &str) -> Result

Writes a string slice into this writer, returning whether the write succeeded.

fn write_char(&mut self, c: char) -> Result

Writes a char into this writer, returning whether the write succeeded.

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

Glue for usage of the write! macro with implementors of this trait.

impl<'a, T: ?Sized> Write for &'a DispatchRetained<T>

where &'a T: Write,

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

Writes 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<()>

Flushes 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: ?Sized> Write for DispatchRetained<T>

where for<'a> &'a T: Write,

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

Writes 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<()>

Flushes 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 DispatchRetained<T>

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

impl<T: ?Sized + Sync + Send> Send for DispatchRetained<T>

DispatchRetained<T> is Send if T is Send + Sync.

impl<T: ?Sized + Sync + Send> Sync for DispatchRetained<T>

DispatchRetained<T> is Sync if T is Send + Sync.

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

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