pub struct MPSTemporaryNDArray { /* private fields */ }MPSNDArray only.Expand description
A MPSNDArray that uses command buffer specific memory to store the array data
Temporary memory is command buffer specific memory, and is useful for MPSNDArray allocations with limited lifetime within a single command buffer. Typically, most MPSNDArrays that are not read or written to by the CPU or needed in other command buffers should be MPSTemporaryNDArray. This will greatly reduce time spent allocating new memory, reduce memory usage and help improve memory locality.
See also Apple’s documentation
Implementations§
Source§impl MPSTemporaryNDArray
impl MPSTemporaryNDArray
Sourcepub unsafe fn defaultAllocator() -> Retained<ProtocolObject<dyn MPSNDArrayAllocator>>
Available on crate feature MPSCore only.
pub unsafe fn defaultAllocator() -> Retained<ProtocolObject<dyn MPSNDArrayAllocator>>
MPSCore only.Get a well known <MPSNDArrayAllocator
that makes temporary MTLBuffers
Sourcepub unsafe fn temporaryNDArrayWithCommandBuffer_descriptor(
command_buffer: &ProtocolObject<dyn MTLCommandBuffer>,
descriptor: &MPSNDArrayDescriptor,
) -> Retained<Self>
Available on crate feature MPSCore only.
pub unsafe fn temporaryNDArrayWithCommandBuffer_descriptor( command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, descriptor: &MPSNDArrayDescriptor, ) -> Retained<Self>
MPSCore only.Initialize a MPSTemporaryNDArray for use on a MTLCommandBuffer
Parameter commandBuffer: The MTLCommandBuffer on which the MPSTemporaryNDArray will be exclusively used
Parameter descriptor: A valid MPSNDArrayDescriptor describing the MPSNDArray format to create
Returns: A valid MPSTemporaryNDArray. The object is not managed by a NSAutoreleasePool. The object will be released when the command buffer is committed. The underlying buffer will become invalid before this time due to the action of the readCount property. Please read and understand the use of the readCount property before using this object.
Sourcepub unsafe fn initWithDevice_descriptor(
this: Allocated<Self>,
device: &ProtocolObject<dyn MTLDevice>,
descriptor: &MPSNDArrayDescriptor,
) -> Retained<Self>
Available on crate feature MPSCore only.
pub unsafe fn initWithDevice_descriptor( this: Allocated<Self>, device: &ProtocolObject<dyn MTLDevice>, descriptor: &MPSNDArrayDescriptor, ) -> Retained<Self>
MPSCore only.Please use temporaryNDArrayWithCommandBuffer:descriptor: instead
Sourcepub unsafe fn readCount(&self) -> NSUInteger
Available on crate feature MPSCore only.
pub unsafe fn readCount(&self) -> NSUInteger
MPSCore only.The number of times a temporary MPSNDArray may be read by a MPSNDArray… kernel before its contents become undefined.
MPSTemporaryNDArrays must release their underlying buffers for reuse immediately after last use. So as to facilitate prompt convenient memory recycling, each time a MPSTemporaryNDArray is read by a MPSNDArray… -encode… method, its readCount is automatically decremented. When the readCount reaches 0, the underlying buffer is automatically made available for reuse to MPS for its own needs and for other MPSTemporaryNDArrays prior to return from the -encode.. function. The contents of the buffer become undefined at this time.
By default, the readCount is initialized to 1, indicating a MPSNDArray that may be overwritten any number of times, but read only once.
You may change the readCount as desired to allow MPSNDArrayKernels to read the MPSTemporaryNDArray additional times. However, it is an error to change the readCount once it is zero. It is an error to read or write to a MPSTemporaryNDArray with a zero readCount. You may set the readCount to 0 yourself to cause the underlying buffer to be returned to MPS. Writing to a MPSTemporaryNDArray does not adjust the readCount.
The Metal API Validation layer will assert if a MPSTemporaryNDArray is deallocated with non-zero readCount to help identify cases when resources are not returned promptly.
Sourcepub unsafe fn setReadCount(&self, read_count: NSUInteger)
Available on crate feature MPSCore only.
pub unsafe fn setReadCount(&self, read_count: NSUInteger)
MPSCore only.Setter for readCount.
Source§impl MPSTemporaryNDArray
Methods declared on superclass MPSNDArray.
impl MPSTemporaryNDArray
Methods declared on superclass MPSNDArray.
pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>
MPSCore only.Sourcepub unsafe fn initWithDevice_scalar(
this: Allocated<Self>,
device: &ProtocolObject<dyn MTLDevice>,
value: c_double,
) -> Retained<Self>
Available on crate feature MPSCore only.
pub unsafe fn initWithDevice_scalar( this: Allocated<Self>, device: &ProtocolObject<dyn MTLDevice>, value: c_double, ) -> Retained<Self>
MPSCore only.Create a 1-Dimensional length=1 NDArray to hold a scalar
Sourcepub unsafe fn initWithBuffer_offset_descriptor(
this: Allocated<Self>,
buffer: &ProtocolObject<dyn MTLBuffer>,
offset: NSUInteger,
descriptor: &MPSNDArrayDescriptor,
) -> Retained<Self>
Available on crate feature MPSCore only.
pub unsafe fn initWithBuffer_offset_descriptor( this: Allocated<Self>, buffer: &ProtocolObject<dyn MTLBuffer>, offset: NSUInteger, descriptor: &MPSNDArrayDescriptor, ) -> Retained<Self>
MPSCore only.Initialize an MPSNDArray object from a Metal Buffer with a given descriptor and offset in bytes.
Parameter buffer: The buffer used for initializing. The NDArray will alias to this buffer at the given offset.
Parameter offset: Offset in bytes to the buffer.
Parameter descriptor: The MPSNDArrayDescriptor used for initializing the the NDArray.
Returns: A valid MPSNDArray object or nil, if failure.
§Safety
buffermay need to be synchronized.buffermay be unretained, you must ensure it is kept alive while in use.buffercontents should be of the correct type.
Methods from Deref<Target = MPSNDArray>§
Sourcepub unsafe fn label(&self) -> Option<Retained<NSString>>
Available on crate feature MPSCore only.
pub unsafe fn label(&self) -> Option<Retained<NSString>>
MPSCore only.A used specified string to help identify the array during debugging.
May be externally visible to tools like Instruments
Sourcepub unsafe fn setLabel(&self, label: Option<&NSString>)
Available on crate feature MPSCore only.
pub unsafe fn setLabel(&self, label: Option<&NSString>)
MPSCore only.Sourcepub unsafe fn dataType(&self) -> MPSDataType
Available on crate features MPSCore and MPSCoreTypes only.
pub unsafe fn dataType(&self) -> MPSDataType
MPSCore and MPSCoreTypes only.The type of data stored by each element in the array
Sourcepub unsafe fn dataTypeSize(&self) -> usize
Available on crate feature MPSCore only.
pub unsafe fn dataTypeSize(&self) -> usize
MPSCore only.The size of one element in the MPSNDArray
Sourcepub unsafe fn numberOfDimensions(&self) -> NSUInteger
Available on crate feature MPSCore only.
pub unsafe fn numberOfDimensions(&self) -> NSUInteger
MPSCore only.Number of dimensions in the NDArray
Sourcepub unsafe fn lengthOfDimension(
&self,
dimension_index: NSUInteger,
) -> NSUInteger
Available on crate feature MPSCore only.
pub unsafe fn lengthOfDimension( &self, dimension_index: NSUInteger, ) -> NSUInteger
MPSCore only.The number of elements in the dimension at dimensionIndex
The dimension length is at least as large as the existing slice length. Views of this MPSNDArray may have differing dimension lengths.
Sourcepub unsafe fn device(&self) -> Retained<ProtocolObject<dyn MTLDevice>>
Available on crate feature MPSCore only.
pub unsafe fn device(&self) -> Retained<ProtocolObject<dyn MTLDevice>>
MPSCore only.The device on which the MSPNDArray may be used
Sourcepub unsafe fn descriptor(&self) -> Retained<MPSNDArrayDescriptor>
Available on crate feature MPSCore only.
pub unsafe fn descriptor(&self) -> Retained<MPSNDArrayDescriptor>
MPSCore only.Create a MPSNDArrayDescriptor that describes this MPSNDArray
The descriptor will describe the shape of the MPSNDArray after all deferred slicing and transposes have completed. A new descriptor is created each time to allow for further customization of the descriptor by the application.
Returns: A new autoreleased MPSNDArrayDescriptor that matches the shape of the MPSNDArray, suitable for introduction of slice, cast and transpose operations.
Sourcepub unsafe fn userBuffer(
&self,
) -> Option<Retained<ProtocolObject<dyn MTLBuffer>>>
Available on crate feature MPSCore only.
pub unsafe fn userBuffer( &self, ) -> Option<Retained<ProtocolObject<dyn MTLBuffer>>>
MPSCore only.Returns the user buffer in case the NDArray was initialized with an MTLBuffer.
Returns: The user-provided MTLBuffer that was used to initialize this MPSNDArray or nil, in case it was not..
Sourcepub unsafe fn resourceSize(&self) -> NSUInteger
Available on crate feature MPSCore only.
pub unsafe fn resourceSize(&self) -> NSUInteger
MPSCore only.Get the number of bytes used to allocate underyling MTLResources
This is the size of the backing store of underlying MTLResources. It does not include all storage used by the object, for example the storage used to hold the MPSNDArray instantiation and MTLBuffer is not included. It only measures the size of the allocation used to hold the MPSNDArray data in the MTLBuffer. This value is subject to change between different devices and operating systems.
Except when -initWithBuffer:descriptor: is used, most MPSNDArrays are allocated initiallly without a backing store. The backing store is allocated lazily when it is needed, typically when the MPSNDArray is written to the first time. Consequently, in most cases, it should be inexpensive to make a MPSImage to see how much memory it will need, and release it if it is too large.
Sourcepub unsafe fn arrayViewWithCommandBuffer_descriptor_aliasing(
&self,
cmd_buf: &ProtocolObject<dyn MTLCommandBuffer>,
descriptor: &MPSNDArrayDescriptor,
aliasing: MPSAliasingStrategy,
) -> Option<Retained<MPSNDArray>>
Available on crate features MPSCore and MPSCoreTypes only.
pub unsafe fn arrayViewWithCommandBuffer_descriptor_aliasing( &self, cmd_buf: &ProtocolObject<dyn MTLCommandBuffer>, descriptor: &MPSNDArrayDescriptor, aliasing: MPSAliasingStrategy, ) -> Option<Retained<MPSNDArray>>
MPSCore and MPSCoreTypes only.Make a new representation of a MPSNDArray with a slice, transpose or other change in property
If possible, the views will merely record the slice or transpose without performing the operation. Many MPSKernels are able to operate on subregions of a MPSNDArray or operate on transposed data, so making a new copy of the data for these operations would be wasteful. A copy may be forced by a change in dataType, rowBytes, or when using a view with a MPSKernel that does not support the deferred operation. To force an operation to occur immediately, use MPSAliasingStrategyShallNotAlias Otherwise, it is likely that the new MPSNDArray will share a MTLBuffer with the parent and alias its memory.
Parameter cmdBuf: The command buffer on which to perform physical copies if any are required
Parameter descriptor: A MPSNDArrayDescriptor describing the shape of the new view of the data
Parameter aliasing: A aliasing strategy to direct MPS how to respond to cases when aliasing can or can not
be performed.
Returns: A new MPSNDArray, if it is possible to make one. Otherwise nil is returned. The MPSNDArray is autoreleased.
Sourcepub unsafe fn arrayViewWithDescriptor(
&self,
descriptor: &MPSNDArrayDescriptor,
) -> Option<Retained<MPSNDArray>>
Available on crate feature MPSCore only.
pub unsafe fn arrayViewWithDescriptor( &self, descriptor: &MPSNDArrayDescriptor, ) -> Option<Retained<MPSNDArray>>
MPSCore only.Make a new representation of a MPSNDArray with a slice, transpose or other change in property, trying to alias to result.
The same as arrayViewWithCommandBuffer, except that tries to always alias, and therefore does not require a commanbuffer.
If aliasing is not possible nil is returned.
This method is useful in making aliasing transposes and slices, that are guaranteed to be able to alias. For reshapes it is recommended
to use the MPSNDArrayIdentity methods.
Parameter descriptor: A MPSNDArrayDescriptor describing the shape of the new view of the data
Returns: A new MPSNDArray, if it is possible to make one. Otherwise nil is returned. The MPSNDArray is autoreleased.
Sourcepub unsafe fn arrayViewWithShape_strides(
&self,
shape: Option<&MPSShape>,
strides: &MPSShape,
) -> Option<Retained<MPSNDArray>>
Available on crate features MPSCore and MPSCoreTypes only.
pub unsafe fn arrayViewWithShape_strides( &self, shape: Option<&MPSShape>, strides: &MPSShape, ) -> Option<Retained<MPSNDArray>>
MPSCore and MPSCoreTypes only.Make a new representation of a MPSNDArray with given strides and a new shape.
This operation always returns a new view of the same underlying MTLBuffer, but works only with contiguous buffers.
Parameter shape: The new shape for the NDArray. Fastest running dimension last. If nil then current shape is used.
Parameter strides: The strides for each dimension. Must be at least length of new shape. Last number must be one. Must be non-increasing.
Returns: A new MPSNDArray, if it is possible to make one. Otherwise nil is returned. The MPSNDArray is autoreleased.
Sourcepub unsafe fn arrayViewWithDimensionCount_dimensionSizes_strides(
&self,
number_of_dimensions: NSUInteger,
dimension_sizes: NonNull<NSUInteger>,
dim_strides: NonNull<NSUInteger>,
) -> Option<Retained<MPSNDArray>>
Available on crate feature MPSCore only.
pub unsafe fn arrayViewWithDimensionCount_dimensionSizes_strides( &self, number_of_dimensions: NSUInteger, dimension_sizes: NonNull<NSUInteger>, dim_strides: NonNull<NSUInteger>, ) -> Option<Retained<MPSNDArray>>
MPSCore only.Make a new representation of a MPSNDArray with given strides and a new shape.
This operation always returns a new view of the same underlying MTLBuffer, but works only with contiguous buffers.
Parameter numberOfDimensions: Number of dimensions in the new view.
Parameter dimensionSizes: Size of each new dimension. Fastest running dimension first. Must be of length numberOfDimensions.
Parameter dimStrides: The strides for each dimension. First number must be one. Must be non-decreasing. Must be of length numberOfDimensions.
Returns: A new MPSNDArray, if it is possible to make one. Otherwise nil is returned. The MPSNDArray is autoreleased.
§Safety
dimension_sizesmust be a valid pointer.dim_stridesmust be a valid pointer.
Sourcepub unsafe fn parent(&self) -> Option<Retained<MPSNDArray>>
Available on crate feature MPSCore only.
pub unsafe fn parent(&self) -> Option<Retained<MPSNDArray>>
MPSCore only.The parent MPSNDArray that this object aliases
If the MPSNDArray was createrd as a array view of another MPSNDArray object, and aliases content in the same MTLBuffer, the original MPSNDArray will be retained as the parent here. Two MPSNDArrays alias if they share a common ancestor. Note that the parent may itself have a parent, and so forth.
Sourcepub unsafe fn exportDataWithCommandBuffer_toBuffer_destinationDataType_offset_rowStrides(
&self,
cmd_buf: &ProtocolObject<dyn MTLCommandBuffer>,
buffer: &ProtocolObject<dyn MTLBuffer>,
destination_data_type: MPSDataType,
offset: NSUInteger,
row_strides: *mut NSInteger,
)
Available on crate features MPSCore and MPSCoreTypes only.
pub unsafe fn exportDataWithCommandBuffer_toBuffer_destinationDataType_offset_rowStrides( &self, cmd_buf: &ProtocolObject<dyn MTLCommandBuffer>, buffer: &ProtocolObject<dyn MTLBuffer>, destination_data_type: MPSDataType, offset: NSUInteger, row_strides: *mut NSInteger, )
MPSCore and MPSCoreTypes only.Do a GPU side copy of the contents of a MPSNDArray to a MTLBuffer
To do a transpose or slice as part of the operation, make a MPSNDArray view first that encodes that operation.
Parameter cmdBuf: The command buffer on which to encode the operation
Parameter buffer: The destination to overwrite
Parameter destinationDataType: The destination data type.
Parameter offset: The byte offset to where the {0,0,0…}th element will be written
Parameter rowStrides: An optional array of (numberOfDimensions-1) byte counts which describe
the byte offset from position 0 of the respective dimension to position 1.
§Safety
buffermay need to be synchronized.buffermay be unretained, you must ensure it is kept alive while in use.buffercontents should be of the correct type.row_stridesmust be a valid pointer or null.
Sourcepub unsafe fn importDataWithCommandBuffer_fromBuffer_sourceDataType_offset_rowStrides(
&self,
cmd_buf: &ProtocolObject<dyn MTLCommandBuffer>,
buffer: &ProtocolObject<dyn MTLBuffer>,
source_data_type: MPSDataType,
offset: NSUInteger,
row_strides: *mut NSInteger,
)
Available on crate features MPSCore and MPSCoreTypes only.
pub unsafe fn importDataWithCommandBuffer_fromBuffer_sourceDataType_offset_rowStrides( &self, cmd_buf: &ProtocolObject<dyn MTLCommandBuffer>, buffer: &ProtocolObject<dyn MTLBuffer>, source_data_type: MPSDataType, offset: NSUInteger, row_strides: *mut NSInteger, )
MPSCore and MPSCoreTypes only.Do a GPU side copy of the contents of a MTLBuffer into a MPSNDArray
Copy data from provided buffer to the NDArray. Implicit transposes and slicing shall be honored.
Parameter cmdBuf: The command buffer on which to encode the operation
Parameter buffer: The destination to read from
Parameter sourceDataType: The source data type.
Parameter offset: The byte offset in the buffer from where the {0,0,0…}th element is to be read.
Parameter rowStrides: An optional array of (numberOfDimensions-1) byte counts which describe
the byte offset from position 0 of the respective dimension to position 1.
§Safety
buffermay need to be synchronized.buffermay be unretained, you must ensure it is kept alive while in use.buffercontents should be of the correct type.row_stridesmust be a valid pointer or null.
Sourcepub unsafe fn exportDataWithCommandBuffer_toImages_offset(
&self,
cmd_buf: &ProtocolObject<dyn MTLCommandBuffer>,
images: &MPSImageBatch,
offset: MPSImageCoordinate,
)
Available on crate features MPSCore and MPSCoreTypes and MPSImage only.
pub unsafe fn exportDataWithCommandBuffer_toImages_offset( &self, cmd_buf: &ProtocolObject<dyn MTLCommandBuffer>, images: &MPSImageBatch, offset: MPSImageCoordinate, )
MPSCore and MPSCoreTypes and MPSImage only.Do a GPU side copy of the contents of a MPSNDArray to a MPSImageBatch.
To do a transpose or slice as part of the operation, make a MPSNDArray view first that encodes that operation. The shape of the array must be [ C, W, H, N, 1, 1, … ], where C is dimension 0 (normally the fastest running index) and is mapped to feature channels in the destination image, W and H are mapped to x and y coordinates in the destination image and N is mapped to the image batch index. You can use arrayViewWithCommandBuffer: to transpose, slice and reshape the source array to layout the data in the desired way for the image(s).
Parameter cmdBuf: The command buffer on which to encode the operation/
Parameter images: The destination images. NOTE: you can use [images subarrayWithRange:…] to get a sub-batch of images.
Parameter offset: The offset to the image where to write - the size of the operation is defined by the source array.
Note: offset.featureChannel must be multiple of four, otherwise results are undefined.
Sourcepub unsafe fn importDataWithCommandBuffer_fromImages_offset(
&self,
cmd_buf: &ProtocolObject<dyn MTLCommandBuffer>,
images: &MPSImageBatch,
offset: MPSImageCoordinate,
)
Available on crate features MPSCore and MPSCoreTypes and MPSImage only.
pub unsafe fn importDataWithCommandBuffer_fromImages_offset( &self, cmd_buf: &ProtocolObject<dyn MTLCommandBuffer>, images: &MPSImageBatch, offset: MPSImageCoordinate, )
MPSCore and MPSCoreTypes and MPSImage only.Do a GPU side copy of the contents of a MPSImageBatch into a MPSNDArray.
This reverses exportDataWithCommandBuffer:toImages: function.
Parameter cmdBuf: The command buffer on which to encode the operation.
Parameter images: The source images. NOTE: you can use [images subarrayWithRange:…] to get a sub-batch of images.
Parameter offset: The offset to the image where to read - the size of the operation is defined by the destination array.
Sourcepub unsafe fn readBytes_strideBytes(
&self,
buffer: NonNull<c_void>,
stride_bytes_per_dimension: *mut NSInteger,
)
Available on crate feature MPSCore only.
pub unsafe fn readBytes_strideBytes( &self, buffer: NonNull<c_void>, stride_bytes_per_dimension: *mut NSInteger, )
MPSCore only.Copy bytes from MPSNDArray into buffer
The dimensionality and size of the copy region is given by the size of the MPSNDArray For subregions, use a MPSNDArray view.
Parameter buffer: A pointer to memory where to write the data
Parameter strideBytesPerDimension: An optional array of numberOfDimensions sizes, which gives the distance
in bytes from one element to the next in that dimension in buffer. The first value
is typically dataTypeSize. The next is a row bytes. The next is 2d matrix bytes,
and so forth. If the value is nil, these are calculated for you assuming that the
data is packed without additional space in between elements, rows, etc.
0 and negative values are permitted.
§Safety
buffermust be a valid pointer.stride_bytes_per_dimensionmust be a valid pointer or null.
Sourcepub unsafe fn writeBytes_strideBytes(
&self,
buffer: NonNull<c_void>,
stride_bytes_per_dimension: *mut NSInteger,
)
Available on crate feature MPSCore only.
pub unsafe fn writeBytes_strideBytes( &self, buffer: NonNull<c_void>, stride_bytes_per_dimension: *mut NSInteger, )
MPSCore only.Copy bytes from a buffer into the MPSNDArray
The dimensionality and size of the copy region is given by the size of the MPSNDArray For subregions, use a MPSNDArray view.
Parameter buffer: A pointer to memory where to read the data
Parameter strideBytesPerDimension: An optional array of numberOfDimensions sizes, which gives the distance
in bytes from one element to the next in that dimension in buffer. The first value
is typically dataTypeSize. The next is a row bytes. The next is 2d matrix bytes,
and so forth. If strideBytesPerDimension is nil, these are calculated for you assuming that the
data is packed without additional space in between elements, rows, etc.
0 and negative values are permitted.
§Safety
buffermust be a valid pointer.stride_bytes_per_dimensionmust be a valid pointer or null.
Sourcepub unsafe fn synchronizeOnCommandBuffer(
&self,
command_buffer: &ProtocolObject<dyn MTLCommandBuffer>,
)
Available on crate feature MPSCore only.
pub unsafe fn synchronizeOnCommandBuffer( &self, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, )
MPSCore only.Use a blit encoder if a discrete device to update CPU contents of underlying buffer with latest GPU value
Parameter commandBuffer: The commandBuffer on which we transfer the contents.
Methods from Deref<Target = NSObject>§
Sourcepub fn doesNotRecognizeSelector(&self, sel: Sel) -> !
pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !
Handle messages the object doesn’t recognize.
See Apple’s documentation for details.
Methods from Deref<Target = AnyObject>§
Sourcepub fn class(&self) -> &'static AnyClass
pub fn class(&self) -> &'static AnyClass
Dynamically find the class of this object.
§Panics
May panic if the object is invalid (which may be the case for objects
returned from unavailable init/new methods).
§Example
Check that an instance of NSObject has the precise class NSObject.
use objc2::ClassType;
use objc2::runtime::NSObject;
let obj = NSObject::new();
assert_eq!(obj.class(), NSObject::class());Sourcepub unsafe fn get_ivar<T>(&self, name: &str) -> &Twhere
T: Encode,
👎Deprecated: this is difficult to use correctly, use Ivar::load instead.
pub unsafe fn get_ivar<T>(&self, name: &str) -> &Twhere
T: Encode,
Ivar::load instead.Use Ivar::load instead.
§Safety
The object must have an instance variable with the given name, and it
must be of type T.
See Ivar::load_ptr for details surrounding this.
Sourcepub fn downcast_ref<T>(&self) -> Option<&T>where
T: DowncastTarget,
pub fn downcast_ref<T>(&self) -> Option<&T>where
T: DowncastTarget,
Attempt to downcast the object to a class of type T.
This is the reference-variant. Use Retained::downcast if you want
to convert a retained object to another type.
§Mutable classes
Some classes have immutable and mutable variants, such as NSString
and NSMutableString.
When some Objective-C API signature says it gives you an immutable class, it generally expects you to not mutate that, even though it may technically be mutable “under the hood”.
So using this method to convert a NSString to a NSMutableString,
while not unsound, is generally frowned upon unless you created the
string yourself, or the API explicitly documents the string to be
mutable.
See Apple’s documentation on mutability and on
isKindOfClass: for more details.
§Generic classes
Objective-C generics are called “lightweight generics”, and that’s because they aren’t exposed in the runtime. This makes it impossible to safely downcast to generic collections, so this is disallowed by this method.
You can, however, safely downcast to generic collections where all the
type-parameters are AnyObject.
§Panics
This works internally by calling isKindOfClass:. That means that the
object must have the instance method of that name, and an exception
will be thrown (if CoreFoundation is linked) or the process will abort
if that is not the case. In the vast majority of cases, you don’t need
to worry about this, since both root objects NSObject and
NSProxy implement this method.
§Examples
Cast an NSString back and forth from NSObject.
use objc2::rc::Retained;
use objc2_foundation::{NSObject, NSString};
let obj: Retained<NSObject> = NSString::new().into_super();
let string = obj.downcast_ref::<NSString>().unwrap();
// Or with `downcast`, if we do not need the object afterwards
let string = obj.downcast::<NSString>().unwrap();Try (and fail) to cast an NSObject to an NSString.
use objc2_foundation::{NSObject, NSString};
let obj = NSObject::new();
assert!(obj.downcast_ref::<NSString>().is_none());Try to cast to an array of strings.
use objc2_foundation::{NSArray, NSObject, NSString};
let arr = NSArray::from_retained_slice(&[NSObject::new()]);
// This is invalid and doesn't type check.
let arr = arr.downcast_ref::<NSArray<NSString>>();This fails to compile, since it would require enumerating over the array to ensure that each element is of the desired type, which is a performance pitfall.
Downcast when processing each element instead.
use objc2_foundation::{NSArray, NSObject, NSString};
let arr = NSArray::from_retained_slice(&[NSObject::new()]);
for elem in arr {
if let Some(data) = elem.downcast_ref::<NSString>() {
// handle `data`
}
}Trait Implementations§
Source§impl AsRef<AnyObject> for MPSTemporaryNDArray
Available on crate feature MPSCore only.
impl AsRef<AnyObject> for MPSTemporaryNDArray
MPSCore only.Source§impl AsRef<MPSNDArray> for MPSTemporaryNDArray
Available on crate feature MPSCore only.
impl AsRef<MPSNDArray> for MPSTemporaryNDArray
MPSCore only.Source§fn as_ref(&self) -> &MPSNDArray
fn as_ref(&self) -> &MPSNDArray
Source§impl AsRef<MPSTemporaryNDArray> for MPSTemporaryNDArray
Available on crate feature MPSCore only.
impl AsRef<MPSTemporaryNDArray> for MPSTemporaryNDArray
MPSCore only.Source§impl AsRef<NSObject> for MPSTemporaryNDArray
Available on crate feature MPSCore only.
impl AsRef<NSObject> for MPSTemporaryNDArray
MPSCore only.Source§impl Borrow<AnyObject> for MPSTemporaryNDArray
Available on crate feature MPSCore only.
impl Borrow<AnyObject> for MPSTemporaryNDArray
MPSCore only.Source§impl Borrow<MPSNDArray> for MPSTemporaryNDArray
Available on crate feature MPSCore only.
impl Borrow<MPSNDArray> for MPSTemporaryNDArray
MPSCore only.Source§fn borrow(&self) -> &MPSNDArray
fn borrow(&self) -> &MPSNDArray
Source§impl Borrow<NSObject> for MPSTemporaryNDArray
Available on crate feature MPSCore only.
impl Borrow<NSObject> for MPSTemporaryNDArray
MPSCore only.Source§impl ClassType for MPSTemporaryNDArray
Available on crate feature MPSCore only.
impl ClassType for MPSTemporaryNDArray
MPSCore only.Source§const NAME: &'static str = "MPSTemporaryNDArray"
const NAME: &'static str = "MPSTemporaryNDArray"
Source§type Super = MPSNDArray
type Super = MPSNDArray
Source§type ThreadKind = <<MPSTemporaryNDArray as ClassType>::Super as ClassType>::ThreadKind
type ThreadKind = <<MPSTemporaryNDArray as ClassType>::Super as ClassType>::ThreadKind
Source§impl Debug for MPSTemporaryNDArray
Available on crate feature MPSCore only.
impl Debug for MPSTemporaryNDArray
MPSCore only.Source§impl Deref for MPSTemporaryNDArray
Available on crate feature MPSCore only.
impl Deref for MPSTemporaryNDArray
MPSCore only.Source§impl Hash for MPSTemporaryNDArray
Available on crate feature MPSCore only.
impl Hash for MPSTemporaryNDArray
MPSCore only.Source§impl Message for MPSTemporaryNDArray
Available on crate feature MPSCore only.
impl Message for MPSTemporaryNDArray
MPSCore only.Source§impl NSObjectProtocol for MPSTemporaryNDArray
Available on crate feature MPSCore only.
impl NSObjectProtocol for MPSTemporaryNDArray
MPSCore only.Source§fn isEqual(&self, other: Option<&AnyObject>) -> bool
fn isEqual(&self, other: Option<&AnyObject>) -> bool
Source§fn hash(&self) -> usize
fn hash(&self) -> usize
Source§fn isKindOfClass(&self, cls: &AnyClass) -> bool
fn isKindOfClass(&self, cls: &AnyClass) -> bool
Source§fn is_kind_of<T>(&self) -> bool
fn is_kind_of<T>(&self) -> bool
isKindOfClass directly, or cast your objects with AnyObject::downcast_refSource§fn isMemberOfClass(&self, cls: &AnyClass) -> bool
fn isMemberOfClass(&self, cls: &AnyClass) -> bool
Source§fn respondsToSelector(&self, aSelector: Sel) -> bool
fn respondsToSelector(&self, aSelector: Sel) -> bool
Source§fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool
fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool
Source§fn debugDescription(&self) -> Retained<NSObject>
fn debugDescription(&self) -> Retained<NSObject>
Source§impl PartialEq for MPSTemporaryNDArray
Available on crate feature MPSCore only.
impl PartialEq for MPSTemporaryNDArray
MPSCore only.Source§impl RefEncode for MPSTemporaryNDArray
Available on crate feature MPSCore only.
impl RefEncode for MPSTemporaryNDArray
MPSCore only.Source§const ENCODING_REF: Encoding = <MPSNDArray as ::objc2::RefEncode>::ENCODING_REF
const ENCODING_REF: Encoding = <MPSNDArray as ::objc2::RefEncode>::ENCODING_REF
impl DowncastTarget for MPSTemporaryNDArray
MPSCore only.impl Eq for MPSTemporaryNDArray
MPSCore only.