Struct MPSNNGraph 

pub struct MPSNNGraph { /* private fields */ }

Available on crate features MPSCore and MPSKernel and MPSNNGraph only.

Optimized representation of a graph of MPSNNImageNodes and MPSNNFilterNodes

Once you have prepared a graph of MPSNNImageNodes and MPSNNFilterNodes (and if needed MPSNNStateNodes), you may initialize a MPSNNGraph using the MPSNNImageNode that you wish to appear as the result. The MPSNNGraph object will introspect the graph representation and determine which nodes are needed for inputs, and which nodes are produced as output state (if any). Nodes which are not needed to calculate the result image node are ignored. Some nodes may be internally concatenated with other nodes for better performance.

Note: the MPSNNImageNode that you choose as the result node may be interior to a graph. This feature is provided as a means to examine intermediate computations in the full graph for debugging purposes.

During MPSNNGraph construction, the graph attached to the result node will be parsed and reduced to an optimized representation. This representation may be saved using the NSSecureCoding protocol for later recall.

When decoding a MPSNNGraph using a NSCoder, it will be created against the system default MTLDevice. If you would like to set the MTLDevice, your NSCoder should conform to the <MPSDeviceProvider

protocol.

You may find it helpful to set MPSKernelOptionsVerbose on the graph when debugging. To turn this on during MPSKernel initialization (including MPSNNGraph initialization) set the MPS_LOG_INFO environment variable. There is a lot of information about what optimizations are done to your graph, including some information on why certain optimizations were not made.

See also Apple’s documentation

Implementations

impl MPSNNGraph

pub unsafe fn initWithDevice_resultImage_resultImageIsNeeded( this: Allocated<Self>, device: &ProtocolObject<dyn MTLDevice>, result_image: &MPSNNImageNode, result_is_needed: bool, ) -> Option<Retained<Self>>

Available on crate features MPSNeuralNetwork and MPSNNGraphNodes only.

Initialize a MPSNNGraph object on a device starting with resultImage working backward

The MPSNNGraph constructor will start with the indicated result image, and look to see what MPSNNFilterNode produced it, then look to its dependencies and so forth to reveal the subsection of the graph necessary to compute the image.

Parameter device: The MTLDevice on which to run the graph

Parameter resultImage: The MPSNNImageNode corresponding to the last image in the graph. This is the image that will be returned. Note: the imageAllocator for this node is ignored and the MPSNNGraph.destinationImageAllocator is used for this node instead.

Parameter resultIsNeeded: Commonly, when training a graph, the last MPSImage out of the graph is not used. The final gradient filter is run solely to update some weights. If resultIsNeeded is set to NO, nil will be returned from the left hand side of the -encode call instead, and computation to produce the last image may be pruned away.

Returns: A new MPSNNGraph.

pub unsafe fn graphWithDevice_resultImage_resultImageIsNeeded( device: &ProtocolObject<dyn MTLDevice>, result_image: &MPSNNImageNode, result_is_needed: bool, ) -> Option<Retained<Self>>

Available on crate features MPSNeuralNetwork and MPSNNGraphNodes only.

pub unsafe fn initWithDevice_resultImages_resultsAreNeeded( this: Allocated<Self>, device: &ProtocolObject<dyn MTLDevice>, result_images: &NSArray<MPSNNImageNode>, are_results_needed: *mut Bool, ) -> Option<Retained<Self>>

Available on crate features MPSNeuralNetwork and MPSNNGraphNodes only.

Initialize a MPSNNGraph object on a device starting with resultImage working backward

The MPSNNGraph constructor will start with the indicated result images, and look to see what MPSNNFilterNode produced them, then look to its dependencies and so forth to reveal the subsection of the graph necessary to compute the image. This variant is provided to support graphs and subgraphs with multiple image outputs.

Parameter device: The MTLDevice on which to run the graph

Parameter resultImages: The MPSNNImageNodes corresponding to the last images in the graph. The first image in the array will be returned from the -encode method LHS. The rest will be included in the list of intermediate images.

Parameter areResultsNeeded: An array of BOOL values with count equal to resultImages.count. If NO is passed for a given image, the image itself is marked unneeded and might be skipped. The graph will prune this branch back to the first requred filter. A filter is required if it generates a needed result image, or is needed to update training parameters.

Returns: A new MPSNNGraph.

Safety

are_results_needed must be a valid pointer or null.

pub unsafe fn graphWithDevice_resultImages_resultsAreNeeded( device: &ProtocolObject<dyn MTLDevice>, result_images: &NSArray<MPSNNImageNode>, are_results_needed: *mut Bool, ) -> Option<Retained<Self>>

Available on crate features MPSNeuralNetwork and MPSNNGraphNodes only.

Safety

are_results_needed must be a valid pointer or null.

pub unsafe fn initWithDevice_resultImage( this: Allocated<Self>, device: &ProtocolObject<dyn MTLDevice>, result_image: &MPSNNImageNode, ) -> Option<Retained<Self>>

👎Deprecated

Available on crate features MPSNeuralNetwork and MPSNNGraphNodes only.

pub unsafe fn graphWithDevice_resultImage( device: &ProtocolObject<dyn MTLDevice>, result_image: &MPSNNImageNode, ) -> Option<Retained<Self>>

👎Deprecated

Available on crate features MPSNeuralNetwork and MPSNNGraphNodes only.

pub unsafe fn initWithCoder_device( this: Allocated<Self>, a_decoder: &NSCoder, device: &ProtocolObject<dyn MTLDevice>, ) -> Option<Retained<Self>>

Available on crate feature MPSNeuralNetwork only.

NSSecureCoding compatability

While the standard NSSecureCoding/NSCoding method -initWithCoder: should work, since the file can’t know which device your data is allocated on, we have to guess and may guess incorrectly. To avoid that problem, use initWithCoder:device instead.

Parameter aDecoder: The NSCoder subclass with your serialized MPSKernel

Parameter device: The MTLDevice on which to make the MPSKernel

Returns: A new MPSKernel object, or nil if failure.

Safety

a_decoder possibly has further requirements.

pub unsafe fn initWithDevice( this: Allocated<Self>, device: &ProtocolObject<dyn MTLDevice>, ) -> Retained<Self>

Available on crate feature MPSNeuralNetwork only.

Use initWithDevice:resultImage: instead

pub unsafe fn sourceImageHandles( &self, ) -> Retained<NSArray<ProtocolObject<dyn MPSHandle>>>

Available on crate features MPSNeuralNetwork and MPSNNGraphNodes only.

Get a list of identifiers for source images needed to calculate the result image

pub unsafe fn sourceStateHandles( &self, ) -> Option<Retained<NSArray<ProtocolObject<dyn MPSHandle>>>>

Available on crate features MPSNeuralNetwork and MPSNNGraphNodes only.

Get a list of identifiers for source state objects needed to calculate the result image

Not guaranteed to be in the same order as resultStateHandles

pub unsafe fn intermediateImageHandles( &self, ) -> Option<Retained<NSArray<ProtocolObject<dyn MPSHandle>>>>

Available on crate features MPSNeuralNetwork and MPSNNGraphNodes only.

Get a list of identifiers for intermediate images objects produced by the graph

pub unsafe fn resultStateHandles( &self, ) -> Option<Retained<NSArray<ProtocolObject<dyn MPSHandle>>>>

Available on crate features MPSNeuralNetwork and MPSNNGraphNodes only.

Get a list of identifiers for result state objects produced by the graph

Not guaranteed to be in the same order as sourceStateHandles

pub unsafe fn resultHandle( &self, ) -> Option<Retained<ProtocolObject<dyn MPSHandle>>>

Available on crate features MPSNeuralNetwork and MPSNNGraphNodes only.

Get a handle for the graph result image

pub unsafe fn outputStateIsTemporary(&self) -> bool

Available on crate feature MPSNeuralNetwork only.

Should MPSState objects produced by -encodeToCommandBuffer… be temporary objects.

See MPSState description. Default: NO

pub unsafe fn setOutputStateIsTemporary(&self, output_state_is_temporary: bool)

Available on crate feature MPSNeuralNetwork only.

Setter for outputStateIsTemporary.

pub unsafe fn destinationImageAllocator( &self, ) -> Retained<ProtocolObject<dyn MPSImageAllocator>>

Available on crate features MPSNeuralNetwork and MPSImage only.

Method to allocate the result image from -encodeToCommandBuffer…

This property overrides the allocator for the final result image in the graph. Default: MPSImage.defaultAllocator

pub unsafe fn setDestinationImageAllocator( &self, destination_image_allocator: &ProtocolObject<dyn MPSImageAllocator>, )

Available on crate features MPSNeuralNetwork and MPSImage only.

Setter for destinationImageAllocator.

pub unsafe fn format(&self) -> MPSImageFeatureChannelFormat

Available on crate features MPSNeuralNetwork and MPSCoreTypes only.

The default storage format used for graph intermediate images

This doesn’t affect how data is stored in buffers in states. Nor does it affect the storage format for weights such as convolution weights stored by individual filters. Default: MPSImageFeatureChannelFormatFloat16

pub unsafe fn setFormat(&self, format: MPSImageFeatureChannelFormat)

Available on crate features MPSNeuralNetwork and MPSCoreTypes only.

Setter for format.

pub unsafe fn resultImageIsNeeded(&self) -> bool

Available on crate feature MPSNeuralNetwork only.

Set at -init time.

If NO, nil will be returned from -encode calls and some computation may be omitted.

pub unsafe fn reloadFromDataSources(&self)

Available on crate feature MPSNeuralNetwork only.

Reinitialize all graph nodes from data sources

A number of the nodes that make up a graph have a data source associated with them, for example a MPSCNNConvolutionDataSource or a MPSCNNBatchNormalizationDataSource. Generally, the data is read from these once at graph initialization time and then not looked at again, except during the weight / parameter update phase of the corresponding gradient nodes and then only if CPU updates are requested. Otherwise, update occurs on the GPU, and the data in the data source is thereafter ignored.

It can happen, though, that your application has determined the graph should load a new set of weights from the data source. When this method is called, the graph will find all nodes that support reloading and direct them to reinitialize themselves based on their data source.

This process occurs immediately. Your application will need to make sure any GPU work being done by the graph is complete to ensure data coherency. Most nodes do not have a data source and will not be modified. Nodes that are not used by the graph will not be updated.

pub unsafe fn encodeToCommandBuffer_sourceImages_sourceStates_intermediateImages_destinationStates( &self, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, source_images: &NSArray<MPSImage>, source_states: Option<&NSArray<MPSState>>, intermediate_images: Option<&NSMutableArray<MPSImage>>, destination_states: Option<&NSMutableArray<MPSState>>, ) -> Option<Retained<MPSImage>>

Available on crate features MPSNeuralNetwork and MPSImage and MPSState only.

Encode the graph to a MTLCommandBuffer

Parameter commandBuffer: The command buffer. If the command buffer is a MPSCommandBuffer, the work will be committed to Metal in small pieces so that the CPU-side latency is much reduced.

Parameter sourceImages: A list of MPSImages to use as the source images for the graph. These should be in the same order as the list returned from MPSNNGraph.sourceImageHandles. The images may be image arrays. Typically, this is only one or two images such as a .JPG decoded into a MPSImage*. If the sourceImages are MPSTemporaryImages, the graph will decrement the readCount by 1, even if the graph actually reads an image multiple times.

Parameter sourceStates: A list of MPSState objects to use as state for a graph. These should be in the same order as the list returned from MPSNNGraph.sourceStateHandles. May be nil, if there is no source state. If the sourceStates are temporary, the graph will decrement the readCount by 1, even if the graph actually reads the state multiple times.

Parameter intermediateImages: An optional NSMutableArray to receive any MPSImage objects exported as part of its operation. These are only the images that were tagged with MPSNNImageNode.exportFromGraph = YES. The identity of the states is given by -resultStateHandles. If temporary, each intermediateImage will have a readCount of 1. If the result was tagged exportFromGraph = YES, it will be here too, with a readCount of 2. To be able to access the images from outside the graph on the CPU, your application must also set MPSNNImageNode.synchronizeResource = YES, and MPSNNImageNode.imageAllocator = [MPSImage defaultAllocator]; The defaultAllocator creates a permanent image that can be read with readBytes.

Parameter destinationStates: An optional NSMutableArray to receive any MPSState objects created as part of its operation. The identity of the states is given by -resultStateHandles.

Returns: A MPSImage or MPSTemporaryImage allocated per the destinationImageAllocator containing the output of the graph. It will be automatically released when commandBuffer completes.

pub unsafe fn encodeBatchToCommandBuffer_sourceImages_sourceStates_intermediateImages_destinationStates( &self, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, source_images: &NSArray<MPSImageBatch>, source_states: Option<&NSArray<MPSStateBatch>>, intermediate_images: Option<&NSMutableArray<MPSImageBatch>>, destination_states: Option<&NSMutableArray<MPSStateBatch>>, ) -> Option<Retained<MPSImageBatch>>

Available on crate features MPSNeuralNetwork and MPSImage and MPSNDArray and MPSState only.

Encode the graph to a MTLCommandBuffer

This interface is like the other except that it operates on a batch of images all at once. In addition, you may specify whether the result is needed.

Parameter commandBuffer: The command buffer. If the command buffer is a MPSCommandBuffer, the work will be committed to Metal in small pieces so that the CPU-side latency is much reduced.

Parameter sourceImages: A list of MPSImages to use as the source images for the graph. These should be in the same order as the list returned from MPSNNGraph.sourceImageHandles. The images may be image arrays. Typically, this is only one or two images such as a .JPG decoded into a MPSImage*. If the sourceImages are MPSTemporaryImages, the graph will decrement the readCount by 1, even if the graph actually reads an image multiple times.

Parameter sourceStates: A list of MPSState objects to use as state for a graph. These should be in the same order as the list returned from MPSNNGraph.sourceStateHandles. May be nil, if there is no source state. If the sourceStates are temporary, the graph will decrement the readCount by 1, even if the graph actually reads the state multiple times.

Parameter intermediateImages: An optional NSMutableArray to receive any MPSImage objects exported as part of its operation. These are only the images that were tagged with MPSNNImageNode.exportFromGraph = YES. The identity of the states is given by -resultStateHandles. If temporary, each intermediateImage will have a readCount of 1. If the result was tagged exportFromGraph = YES, it will be here too, with a readCount of 2. To be able to access the images from outside the graph on the CPU, your application must also set MPSNNImageNode.synchronizeResource = YES, and MPSNNImageNode.imageAllocator = [MPSImage defaultAllocator]; The defaultAllocator creates a permanent image that can be read with readBytes.

Parameter destinationStates: An optional NSMutableArray to receive any MPSState objects created as part of its operation. The identity of the states is given by -resultStateHandles.

Returns: A MPSImageBatch or MPSTemporaryImageBatch allocated per the destinationImageAllocator containing the output of the graph. It will be automatically released when commandBuffer completes. If resultIsNeeded == NO, then this will return nil.

pub unsafe fn encodeToCommandBuffer_sourceImages( &self, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, source_images: &NSArray<MPSImage>, ) -> Option<Retained<MPSImage>>

Available on crate features MPSNeuralNetwork and MPSImage only.

Encode the graph to a MTLCommandBuffer

IMPORTANT: Please use [MTLCommandBuffer addCompletedHandler:] to determine when this work is done. Use CPU time that would have been spent waiting for the GPU to encode the next command buffer and commit it too. That way, the work for the next command buffer is ready to go the moment the GPU is done. This will keep the GPU busy and running at top speed.

Those who ignore this advice and use [MTLCommandBuffer waitUntilCompleted] instead will likely cause their code to slow down by a factor of two or more. The CPU clock spins down while it waits for the GPU. When the GPU completes, the CPU runs slowly for a while until it spins up. The GPU has to wait for the CPU to encode more work (at low clock), giving it plenty of time to spin its own clock down. In typical CNN graph usage, neither may ever reach maximum clock frequency, causing slow down far beyond what otherwise would be expected from simple failure to schedule CPU and GPU work concurrently. Regrattably, it is probable that every performance benchmark you see on the net will be based on [MTLCommandBuffer waitUntilCompleted].

Parameter commandBuffer: The command buffer. If the command buffer is a MPSCommandBuffer, the work will be committed to Metal in small pieces so that the CPU-side latency is much reduced.

Parameter sourceImages: A list of MPSImages to use as the source images for the graph. These should be in the same order as the list returned from MPSNNGraph.sourceImageHandles.

Returns: A MPSImage or MPSTemporaryImage allocated per the destinationImageAllocator containing the output of the graph. It will be automatically released when commandBuffer completes. It can be nil if resultImageIsNeeded == NO

pub unsafe fn encodeBatchToCommandBuffer_sourceImages_sourceStates( &self, command_buffer: &ProtocolObject<dyn MTLCommandBuffer>, source_images: &NSArray<MPSImageBatch>, source_states: Option<&NSArray<MPSStateBatch>>, ) -> Option<Retained<MPSImageBatch>>

Available on crate features MPSNeuralNetwork and MPSImage and MPSNDArray and MPSState only.

Convenience method to encode a batch of images

pub unsafe fn executeAsyncWithSourceImages_completionHandler( &self, source_images: &NSArray<MPSImage>, handler: MPSNNGraphCompletionHandler, ) -> Retained<MPSImage>

Available on crate features MPSNeuralNetwork and MPSImage and block2 only.

Convenience method to execute a graph without having to manage many Metal details

This function will synchronously encode the graph on a private command buffer, commit it to a MPS internal command queue and return. The GPU will start working. When the GPU is done, the completion handler will be called. You should use the intervening time to encode other work for execution on the GPU, so that the GPU stays busy and doesn’t clock down.

The work will be performed on the MTLDevice that hosts the source images.

This is a convenience API. There are a few situations it does not handle optimally. These may be better handled using [encodeToCommandBuffer:sourceImages:]. Specifically:

                    o     If the graph needs to be run multiple times for different images,
                          it would be better to encode the graph multiple times on the same
                          command buffer using [encodeToCommandBuffer:sourceImages:]  This
                          will allow the multiple graphs to share memory for intermediate
                          storage, dramatically reducing memory usage.

                    o     If preprocessing or post-processing of the MPSImage is required,
                          such as resizing or normalization outside of a convolution, it would
                          be better to encode those things on the same command buffer.
                          Memory may be saved here too for intermediate storage. (MPSTemporaryImage
                          lifetime does not span multiple command buffers.)

Parameter sourceImages: A list of MPSImages to use as the source images for the graph. These should be in the same order as the list returned from MPSNNGraph.sourceImageHandles. They should be allocated against the same MTLDevice. There must be at least one source image. Note: this array is intended to handle the case where multiple input images are required to generate a single graph result. That is, the graph itself has multiple inputs. If you need to execute the graph multiple times, then call this API multiple times, or (faster) make use of MPSImageBatches using -executeBatchToCommandBuffer:sourceImages:sourceStates:… (See discussion)

Parameter handler: A block to receive any errors generated. This block may run on any thread and may be called before this method returns. The image, if any, passed to this callback is the same image as that returned from the left hand side.

Returns: A MPSImage to receive the result. The data in the image will not be valid until the completionHandler is called.

Safety

handler must be a valid pointer.

pub unsafe fn readCountForSourceImageAtIndex( &self, index: NSUInteger, ) -> NSUInteger

Available on crate feature MPSNeuralNetwork only.

Find the number of times a image will be read by the graph *

From the set of images (or image batches) passed in to the graph, find the number of times the graph will read an image. This may be needed by your application to correctly set the MPSImage.readCount property.

Parameter index: The index of the image. The index of the image matches the index of the image in the array returned by the sourceImageHandles property.

Returns: The read count of the image(s) at the index will be reduced by the value returned when the graph is finished encoding. The readcount of the image(s) must be at least this value when it is passed into the -encode… method.

pub unsafe fn readCountForSourceStateAtIndex( &self, index: NSUInteger, ) -> NSUInteger

Available on crate feature MPSNeuralNetwork only.

Find the number of times a state will be read by the graph *

From the set of state (or state batches) passed in to the graph, find the number of times the graph will read a state. This may be needed by your application to correctly set the MPSState.readCount property.

Parameter index: The index of the state. The index of the state matches the index of the state in the array returned by the sourceStateHandles property.

Returns: The read count of the state(s) at the index will be reduced by the value returned when the graph is finished encoding. The read count of the state(s) must be at least this value when it is passed into the -encode… method.

impl MPSNNGraph

Methods declared on superclass MPSKernel.

pub unsafe fn initWithCoder( this: Allocated<Self>, a_decoder: &NSCoder, ) -> Option<Retained<Self>>

Available on crate feature MPSNeuralNetwork only.

Called by NSCoder to decode MPSKernels

This isn’t the right interface to decode a MPSKernel, but it is the one that NSCoder uses. To enable your NSCoder (e.g. NSKeyedUnarchiver) to set which device to use extend the object to adopt the MPSDeviceProvider protocol. Otherwise, the Metal system default device will be used.

Safety

a_decoder possibly has further requirements.

impl MPSNNGraph

Methods declared on superclass NSObject.

pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>

Available on crate feature MPSNeuralNetwork only.

pub unsafe fn new() -> Retained<Self>

Available on crate feature MPSNeuralNetwork only.

Methods from Deref<Target = MPSKernel>

pub unsafe fn options(&self) -> MPSKernelOptions

Available on crate feature MPSCoreTypes only.

The set of options used to run the kernel. subsubsection_options

pub unsafe fn setOptions(&self, options: MPSKernelOptions)

Available on crate feature MPSCoreTypes only.

Setter for options.

pub unsafe fn device(&self) -> Retained<ProtocolObject<dyn MTLDevice>>

The device on which the kernel will be used

pub unsafe fn label(&self) -> Option<Retained<NSString>>

A string to help identify this object.

pub unsafe fn setLabel(&self, label: Option<&NSString>)

Setter for label.

This is copied when set.

pub unsafe fn copyWithZone_device( &self, zone: *mut NSZone, device: Option<&ProtocolObject<dyn MTLDevice>>, ) -> Retained<Self>

Make a copy of this MPSKernel for a new device

-copyWithZone: will call this API to make a copy of the MPSKernel on the same device. This interface may also be called directly to make a copy of the MPSKernel on a new device. Typically, the same MPSKernels should not be used to encode kernels on multiple command buffers from multiple threads. Many MPSKernels have mutable properties that might be changed by the other thread while this one is trying to encode. If you need to use a MPSKernel from multiple threads make a copy of it for each additional thread using -copyWithZone: or -copyWithZone:device:

Parameter zone: The NSZone in which to allocate the object

Parameter device: The device for the new MPSKernel. If nil, then use self.device.

Returns: a pointer to a copy of this MPSKernel. This will fail, returning nil if the device is not supported. Devices must be MTLFeatureSet_iOS_GPUFamily2_v1 or later.

Safety

zone must be a valid pointer or null.

Methods from Deref<Target = NSObject>

pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !

Handle messages the object doesn’t recognize.

See Apple’s documentation for details.

Methods from Deref<Target = AnyObject>

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

pub unsafe fn get_ivar<T>(&self, name: &str) -> &T

where T: Encode,

👎Deprecated: this is difficult to use correctly, use 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.

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

impl AsRef<AnyObject> for MPSNNGraph

Available on crate feature MPSNeuralNetwork only.

fn as_ref(&self) -> &AnyObject

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

impl AsRef<MPSKernel> for MPSNNGraph

Available on crate feature MPSNeuralNetwork only.

fn as_ref(&self) -> &MPSKernel

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

impl AsRef<MPSNNGraph> for MPSNNGraph

Available on crate feature MPSNeuralNetwork only.

fn as_ref(&self) -> &Self

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

impl AsRef<NSObject> for MPSNNGraph

Available on crate feature MPSNeuralNetwork only.

fn as_ref(&self) -> &NSObject

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

impl Borrow<AnyObject> for MPSNNGraph

Available on crate feature MPSNeuralNetwork only.

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<MPSKernel> for MPSNNGraph

Available on crate feature MPSNeuralNetwork only.

fn borrow(&self) -> &MPSKernel

Immutably borrows from an owned value.

impl Borrow<NSObject> for MPSNNGraph

Available on crate feature MPSNeuralNetwork only.

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for MPSNNGraph

Available on crate feature MPSNeuralNetwork only.

const NAME: &'static str = "MPSNNGraph"

The name of the Objective-C class that this type represents.

type Super = MPSKernel

The superclass of this class.

type ThreadKind = <<MPSNNGraph as ClassType>::Super as ClassType>::ThreadKind

Whether the type can be used from any thread, or from only the main thread.

fn class() -> &'static AnyClass

Get a reference to the Objective-C class that this type represents.

fn as_super(&self) -> &Self::Super

Get an immutable reference to the superclass.

impl CopyingHelper for MPSNNGraph

Available on crate feature MPSNeuralNetwork only.

type Result = MPSNNGraph

The immutable counterpart of the type, or Self if the type has no immutable counterpart.

impl Debug for MPSNNGraph

Available on crate feature MPSNeuralNetwork only.

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

Formats the value using the given formatter.

impl Deref for MPSNNGraph

Available on crate feature MPSNeuralNetwork only.

type Target = MPSKernel

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Hash for MPSNNGraph

Available on crate feature MPSNeuralNetwork only.

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 Message for MPSNNGraph

Available on crate feature MPSNeuralNetwork only.

fn retain(&self) -> Retained<Self>

where Self: Sized,

Increment the reference count of the receiver.

impl NSCoding for MPSNNGraph

Available on crate feature MPSNeuralNetwork only.

unsafe fn encodeWithCoder(&self, coder: &NSCoder)

where Self: Sized + Message,

Safety

unsafe fn initWithCoder( this: Allocated<Self>, coder: &NSCoder, ) -> Option<Retained<Self>>

where Self: Sized + Message,

Safety

impl NSCopying for MPSNNGraph

Available on crate feature MPSNeuralNetwork only.

fn copy(&self) -> Retained<Self::Result>

where Self: Sized + Message + CopyingHelper,

Returns a new instance that’s a copy of the receiver.

unsafe fn copyWithZone(&self, zone: *mut NSZone) -> Retained<Self::Result>

where Self: Sized + Message + CopyingHelper,

Returns a new instance that’s a copy of the receiver.

impl NSObjectProtocol for MPSNNGraph

Available on crate feature MPSNeuralNetwork only.

fn isEqual(&self, other: Option<&AnyObject>) -> bool

where Self: Sized + Message,

Check whether the object is equal to an arbitrary other object.

fn hash(&self) -> usize

where Self: Sized + Message,

An integer that can be used as a table address in a hash table structure.

fn isKindOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of the class, or one of its subclasses.

fn is_kind_of<T>(&self) -> bool

where T: ClassType, Self: Sized + Message,

👎Deprecated: use isKindOfClass directly, or cast your objects with AnyObject::downcast_ref

Check if the object is an instance of the class type, or one of its subclasses.

fn isMemberOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of a specific class, without checking subclasses.

fn respondsToSelector(&self, aSelector: Sel) -> bool

where Self: Sized + Message,

Check whether the object implements or inherits a method with the given selector.

fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool

where Self: Sized + Message,

Check whether the object conforms to a given protocol.

fn description(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object.

fn debugDescription(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object to use when debugging.

fn isProxy(&self) -> bool

where Self: Sized + Message,

Check whether the receiver is a subclass of the NSProxy root class instead of the usual NSObject.

fn retainCount(&self) -> usize

where Self: Sized + Message,

The reference count of the object.

impl NSSecureCoding for MPSNNGraph

Available on crate feature MPSNeuralNetwork only.

fn supportsSecureCoding() -> bool

where Self: Sized + ClassType,

impl PartialEq for MPSNNGraph

Available on crate feature MPSNeuralNetwork only.

fn eq(&self, other: &Self) -> bool

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

fn ne(&self, other: &Rhs) -> bool

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

impl RefEncode for MPSNNGraph

Available on crate feature MPSNeuralNetwork only.

const ENCODING_REF: Encoding = <MPSKernel as ::objc2::RefEncode>::ENCODING_REF

The Objective-C type-encoding for a reference of this type.

impl DowncastTarget for MPSNNGraph

Available on crate feature MPSNeuralNetwork only.

impl Eq for MPSNNGraph

Available on crate feature MPSNeuralNetwork only.