iOS Developer Library

Developer

Foundation Framework Reference NSPointerFunctions Class Reference

Options
Deployment Target:

On This Page
Language:

NSPointerFunctions

An instance of NSPointerFunctions defines callout functions appropriate for managing a pointer reference held somewhere else.

The functions specified by an instance of NSPointerFunctions are separated into two clusters—those that define “personality” such as “object” or "C-string”, and those that describe memory management issues such as a memory deallocation function. There are constants for common personalities and memory manager selections (see Memory and Personality Options).

NSHashTable, NSMapTable, and NSPointerArray use an NSPointerFunctions object to define the acquisition and retention behavior for the pointers they manage. Note, however, that not all combinations of personality and memory management behavior are valid for these collections. The pointer collection objects copy the NSPointerFunctions object on input and output, so you cannot usefully subclass NSPointerFunctions.

Subclassing Notes

NSPointerFunctions is not suitable for subclassing.

Inheritance


Conforms To


Import Statement


Swift

import Foundation

Objective-C

@import Foundation;

Availability


Available in iOS 6.0 and later.
  • init(options:) - initWithOptions: Designated Initializer

    Returns an NSPointerFunctions object initialized with the given options.

    Declaration

    Swift

    init(options options: NSPointerFunctionsOptions)

    Objective-C

    - (instancetype)initWithOptions:(NSPointerFunctionsOptions)options

    Parameters

    options

    The options for the new NSPointerFunctions object.

    Return Value

    The NSPointerFunctions object, initialized with the given options.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 6.0 and later.

  • Returns a new NSPointerFunctions object initialized with the given options.

    Declaration

    Objective-C

    + (NSPointerFunctions *)pointerFunctionsWithOptions:(NSPointerFunctionsOptions)options

    Parameters

    options

    The options for the new NSPointerFunctions object.

    Return Value

    A new NSPointerFunctions object initialized with the given options.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 6.0 and later.

  • The hash function.

    Declaration

    Swift

    var hashFunction: CFunctionPointer<((UnsafePointer<Void>, CFunctionPointer<((UnsafePointer<Void>) -> Int)>) -> Int)>

    Objective-C

    @property NSUInteger (*hashFunction)(const void *item, NSUInteger (*size)(const void *item))

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 6.0 and later.

  • The function used to compare pointers.

    Declaration

    Swift

    var isEqualFunction: CFunctionPointer<((UnsafePointer<Void>, UnsafePointer<Void>, CFunctionPointer<((UnsafePointer<Void>) -> Int)>) -> Bool)>

    Objective-C

    @property BOOL (*isEqualFunction)(const void *item1, const void *item2, NSUInteger (*size)(const void *item))

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 6.0 and later.

  • The function used to determine the size of pointers.

    Declaration

    Swift

    var sizeFunction: CFunctionPointer<((UnsafePointer<Void>) -> Int)>

    Objective-C

    @property NSUInteger (*sizeFunction)(const void *item)

    Discussion

    This function is used for copy-in operations (unless the collection has an object personality).

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 6.0 and later.

  • The function used to describe elements.

    Declaration

    Swift

    var descriptionFunction: CFunctionPointer<((UnsafePointer<Void>) -> String!)>

    Objective-C

    @property NSString *(*descriptionFunction)(const void *item)

    Discussion

    This function is used by description methods for hash and map tables.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 6.0 and later.

  • The function used to acquire memory.

    Declaration

    Swift

    var acquireFunction: CFunctionPointer<((UnsafePointer<Void>, CFunctionPointer<((UnsafePointer<Void>) -> Int)>, Bool) -> UnsafeMutablePointer<Void>)>

    Objective-C

    @property void *(*acquireFunction)(const void *src, NSUInteger (*size)(const void *item), BOOL shouldCopy)

    Discussion

    This specifies the function to use for copy-in operations.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 6.0 and later.

  • The function used to relinquish memory.

    Declaration

    Swift

    var relinquishFunction: CFunctionPointer<((UnsafePointer<Void>, CFunctionPointer<((UnsafePointer<Void>) -> Int)>) -> Void)>

    Objective-C

    @property void (*relinquishFunction)(const void *item, NSUInteger (*size)(const void *item))

    Discussion

    This specifies the function to use when an item is removed from a table or pointer array.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 6.0 and later.

    See Also

    acquireFunction

  • Specifies whether, in a garbage collected environment, pointers should be assigned using a strong write barrier.

    Declaration

    Swift

    var usesStrongWriteBarrier: Bool

    Objective-C

    @property BOOL usesStrongWriteBarrier

    Discussion

    If you use garbage collection, read and write barrier functions must be used when pointers are from memory scanned by the collector.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 6.0 and later.

  • Specifies whether, in a garbage collected environment, pointers should use weak read and write barriers.

    Declaration

    Swift

    var usesWeakReadAndWriteBarriers: Bool

    Objective-C

    @property BOOL usesWeakReadAndWriteBarriers

    Discussion

    If you use garbage collection, read and write barrier functions must be used when pointers are from memory scanned by the collector.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 6.0 and later.

Data Types

  • Defines the memory and personality options for an NSPointerFunctions object.

    Declaration

    Swift

    typealias NSPointerFunctionsOptions = Int

    Objective-C

    typedef NSUInteger NSPointerFunctionsOptions;

    Discussion

    For values, see Memory and Personality Options.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 6.0 and later.

  • Specify memory and personality options for an NSPointerFunctions object.

    Declaration

    Swift

    var NSPointerFunctionsStrongMemory: Int { get } var NSPointerFunctionsOpaqueMemory: Int { get } var NSPointerFunctionsMallocMemory: Int { get } var NSPointerFunctionsMachVirtualMemory: Int { get } var NSPointerFunctionsWeakMemory: Int { get } var NSPointerFunctionsObjectPersonality: Int { get } var NSPointerFunctionsOpaquePersonality: Int { get } var NSPointerFunctionsObjectPointerPersonality: Int { get } var NSPointerFunctionsCStringPersonality: Int { get } var NSPointerFunctionsStructPersonality: Int { get } var NSPointerFunctionsIntegerPersonality: Int { get } var NSPointerFunctionsCopyIn: Int { get }

    Objective-C

    enum { NSPointerFunctionsStrongMemory = (0 << 0), NSPointerFunctionsOpaqueMemory = (2 << 0), NSPointerFunctionsMallocMemory = (3 << 0), NSPointerFunctionsMachVirtualMemory = (4 << 0), NSPointerFunctionsWeakMemory = (5UL << 0), NSPointerFunctionsObjectPersonality = (0 << 8), NSPointerFunctionsOpaquePersonality = (1 << 8), NSPointerFunctionsObjectPointerPersonality = (2 << 8), NSPointerFunctionsCStringPersonality = (3 << 8), NSPointerFunctionsStructPersonality = (4 << 8), NSPointerFunctionsIntegerPersonality = (5 << 8), NSPointerFunctionsCopyIn = (1 << 16), };

    Constants

    • NSPointerFunctionsStrongMemory

      NSPointerFunctionsStrongMemory

      Use strong write-barriers to backing store; use garbage-collected memory on copy-in.

      This is the default memory value.

      As a special case, if you do not use garbage collection and specify this value in conjunction with NSPointerFunctionsObjectPersonality or NSPointerFunctionsObjectPointerPersonality then the NSPointerFunctions object uses retain and release.

      If you do not use garbage collection, and specify this value in conjunction with a valid non-object personality, it is the same as specifying NSPointerFunctionsMallocMemory.

      Available in iOS 6.0 and later.

    • NSPointerFunctionsOpaqueMemory

      NSPointerFunctionsOpaqueMemory

      Take no action when pointers are deleted.

      This is usually the preferred memory option for holding arbitrary pointers.

      This is essentially a no-op relinquish function; the acquire function is only used for copy-in operations. This option is unlikely a to be a good choice for objects.

      Available in iOS 6.0 and later.

    • NSPointerFunctionsMallocMemory

      NSPointerFunctionsMallocMemory

      Use free() on removal, calloc() on copy in.

      Available in iOS 6.0 and later.

    • NSPointerFunctionsMachVirtualMemory

      NSPointerFunctionsMachVirtualMemory

      Use Mach memory.

      Available in iOS 6.0 and later.

    • NSPointerFunctionsWeakMemory

      NSPointerFunctionsWeakMemory

      Uses weak read and write barriers appropriate for ARC or GC. Using NSPointerFunctionsWeakMemory object references will turn to NULL on last release.

      Available in iOS 6.0 and later.

    • NSPointerFunctionsObjectPersonality

      NSPointerFunctionsObjectPersonality

      Use hash and isEqual methods for hashing and equality comparisons, use the description method for a description.

      This is the default personality value.

      As a special case, if you do not use garbage collection and specify this value in conjunction with NSPointerFunctionsStrongMemory then the NSPointerFunctions object uses retain and release.

      Available in iOS 6.0 and later.

    • NSPointerFunctionsOpaquePersonality

      NSPointerFunctionsOpaquePersonality

      Use shifted pointer for the hash value and direct comparison to determine equality.

      Available in iOS 6.0 and later.

    • NSPointerFunctionsObjectPointerPersonality

      NSPointerFunctionsObjectPointerPersonality

      Use shifted pointer for the hash value and direct comparison to determine equality; use the description method for a description.

      As a special case, if you do not use garbage collection and specify this value in conjunction with NSPointerFunctionsStrongMemory then the NSPointerFunctions object uses retain and release.

      Available in iOS 6.0 and later.

    • NSPointerFunctionsCStringPersonality

      NSPointerFunctionsCStringPersonality

      Use a string hash and strcmp; C-string '%s' style description.

      Available in iOS 6.0 and later.

    • NSPointerFunctionsStructPersonality

      NSPointerFunctionsStructPersonality

      Use a memory hash and memcmp (using a size function that you must set—see sizeFunction).

      Available in iOS 6.0 and later.

    • NSPointerFunctionsIntegerPersonality

      NSPointerFunctionsIntegerPersonality

      Use unshifted value as hash and equality.

      Available in iOS 6.0 and later.

    • NSPointerFunctionsCopyIn

      NSPointerFunctionsCopyIn

      Use the memory acquire function to allocate and copy items on input (see acquireFunction).

      Available in iOS 6.0 and later.

    Discussion

    Memory options are mutually exclusive and personality options are mutually exclusive.