Struct CFRetained 

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

A reference counted pointer type for CoreFoundation types.

CFRetained 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 CFRetained<T> can be anything that implements Type, i.e. any CoreFoundation-like type.

Comparison to other types

CFRetained<T> is equivalent to objc2::rc::Retained, and can be converted to/from that when the "objc2" feature is enabled. Note though that this uses the underlying CoreFoundation primitives CFRetain / CFRelease / CFAutorelease instead of objc_retain / objc_release / objc_autorelease, to avoid depending on the Objective-C runtime if not needed.

You can also view CFRetained<T> as the CoreFoundation 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 Type::retain (for Arc you need &Arc<T>).

Weak references are not supported though without the Objective-C runtime.

Forwarding implementations

Since CFRetained<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. CFRetained<CFString> as-if it was CFString. Note that having a CFString directly is not possible since CoreFoundation 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 (i.e. &CFString).

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

Implementations

impl<T: ?Sized + Type> CFRetained<T>

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

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

This is useful when you have been given a pointer to a type from some API that returns a retained pointer (i.e. follows the Create rule).

Safety

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

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

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

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

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

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

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

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

Returns a raw pointer to the type.

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

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

pub unsafe fn cast_unchecked<U: Type>(this: Self) -> CFRetained<U>

Unchecked conversion to another CoreFoundation type.

This is equivalent to an unsafe cast between two pointers, see CFRetained::downcast for a safe alternative.

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

Safety

You must ensure that the type 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.

impl<T: Type> CFRetained<T>

pub fn downcast<U: ConcreteType>(self) -> Result<CFRetained<U>, Self>

where T: 'static,

Attempt to downcast the type to that of type U.

This is the owned variant. Use CFType::downcast_ref if you want to convert a reference type. See also ConcreteType for more details on which types support being converted to.

See CFType::downcast_ref for more details.

Errors

If casting failed, this will return the original back as the Err variant. If you do not care about this, and just want an Option, use .downcast().ok().

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

Retain the pointer and construct a CFRetained from it.

This is useful when you have been given a pointer to a type from some API that returns a non-retained reference (i.e. follows the Get rule).

See also Type::retain for a safe alternative when you already have a reference to the type.

Safety

The pointer must be valid as a reference (aligned, dereferenceable and initialized, see the std::ptr module for more information).

You must ensure that if T is non-'static (i.e. has a lifetime parameter), that any data that T may reference lives for at least as long as the return value.

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

Autoreleases the CFRetained, returning a pointer.

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

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

Safety

This method is safe to call, but the returned pointer is only guaranteed to be valid until the innermost autorelease pool is drained.

Trait Implementations

impl<T: ?Sized + AsRef<U>, U: ?Sized> AsRef<U> for CFRetained<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 CFRetained<T>

fn borrow(&self) -> &T

Immutably borrows from an owned value.

impl<T: Type> Clone for CFRetained<T>

fn clone(&self) -> Self

Retain the type, increasing its reference count.

This calls Type::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 CFRetained<T>

fn deref(&self) -> &T

Obtain a reference to the type.

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

fn drop(&mut self)

Releases the contained type.

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

Available on crate feature std only.

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 CFRetained<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 CFRetained<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: Type> From<&T> for CFRetained<U>

fn from(obj: &T) -> Self

Cast the type to a superclass or CFType, and retain it.

impl<T: ?Sized + ConcreteType + 'static> From<CFRetained<T>> for CFRetained<CFType>

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

Convert to CFType.

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

Available on crate feature objc2 only.

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

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

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

impl<T: ?Sized + Type + Message> From<Retained<T>> for CFRetained<T>

Available on crate feature objc2 only.

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

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

This only works if the type is a CoreFoundation type (implements the Type trait).

This conversion is cost-free.

impl<'a, T: ?Sized> Future for &'a CFRetained<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 CFRetained<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 CFRetained<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 CFRetained<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: Type> IntoIterator for CFRetained<CFArray<T>>

Available on crate feature CFArray only.

type Item = CFRetained<T>

The type of the elements being iterated over.

type IntoIter = CFArrayIntoIter<T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T: Type> IntoIterator for CFRetained<CFMutableArray<T>>

Available on crate feature CFArray only.

type Item = CFRetained<T>

The type of the elements being iterated over.

type IntoIter = CFArrayIntoIter<T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

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 CFRetained<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<CFRetained<U>> for CFRetained<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<CFRetained<U>> for CFRetained<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 CFRetained<T>

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

Formats the value using the given formatter.

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

where &'a T: Read,

Available on crate feature std only.

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

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

Available on crate feature std only.

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

where &'a T: Seek,

Available on crate feature std only.

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

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

Available on crate feature std only.

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

where &'a T: Write,

Available on crate feature std only.

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

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

Available on crate feature std only.

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

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

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

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

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

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

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

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