NSPointerFunctions Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in iOS 6.0 and later.
Declared in
NSPointerFunctions.h
Companion guides
Collections Programming Topics
Garbage Collection Programming Guide

Overview

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.

Adopted Protocols

NSCopying

Tasks

Creating and Initializing an NSPointerFunctions Object

Personality Functions

Memory Configuration

Properties

acquireFunction

The function used to acquire memory.

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

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

Availability
  • Available in iOS 6.0 and later.
Declared In
NSPointerFunctions.h

descriptionFunction

The function used to describe elements.

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

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

Availability
  • Available in iOS 6.0 and later.
Declared In
NSPointerFunctions.h

hashFunction

The hash function.

@property NSUInteger (*hashFunction)(const void *item, NSUInteger (*size)(const void *item))
Availability
  • Available in iOS 6.0 and later.
Declared In
NSPointerFunctions.h

isEqualFunction

The function used to compare pointers.

@property BOOL (*isEqualFunction)(const void *item1, const void*item2, NSUInteger (*size)(const void *item))
Availability
  • Available in iOS 6.0 and later.
Declared In
NSPointerFunctions.h

relinquishFunction

The function used to relinquish memory.

@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.

Availability
  • Available in iOS 6.0 and later.
Declared In
NSPointerFunctions.h

sizeFunction

The function used to determine the size of pointers.

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

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

Availability
  • Available in iOS 6.0 and later.
Declared In
NSPointerFunctions.h

usesStrongWriteBarrier

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

@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.

Availability
  • Available in iOS 6.0 and later.
Declared In
NSPointerFunctions.h

usesWeakReadAndWriteBarriers

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

@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.

Availability
  • Available in iOS 6.0 and later.
Declared In
NSPointerFunctions.h

Class Methods

pointerFunctionsWithOptions:

Returns a new NSPointerFunctions object initialized with the given options.

+ (id)pointerFunctionsWithOptions:(NSPointerFunctionsOptions)options
Parameters
options

The options for the new NSPointerFunctions object.

Return Value

A new NSPointerFunctions object initialized with the given options.

Availability
  • Available in iOS 6.0 and later.
Declared In
NSPointerFunctions.h

Instance Methods

initWithOptions:

Returns an NSPointerFunctions object initialized with the given options.

- (id)initWithOptions:(NSPointerFunctionsOptions)options
Parameters
options

The options for the new NSPointerFunctions object.

Return Value

The NSPointerFunctions object, initialized with the given options.

Availability
  • Available in iOS 6.0 and later.
Declared In
NSPointerFunctions.h

Constants

NSPointerFunctionsOptions

Defines the memory and personality options for an NSPointerFunctions object.

typedef NSUInteger NSPointerFunctionsOptions;
Discussion

For values, see “Memory and Personality Options.”

Availability
  • Available in iOS 6.0 and later.
Declared In
NSPointerFunctions.h

Memory and Personality Options

Specify memory and personality options for an NSPointerFunctions object.

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

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.

Declared in NSPointerFunctions.h.

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.

Declared in NSPointerFunctions.h.

NSPointerFunctionsMallocMemory

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

Available in iOS 6.0 and later.

Declared in NSPointerFunctions.h.

NSPointerFunctionsMachVirtualMemory

Use Mach memory.

Available in iOS 6.0 and later.

Declared in NSPointerFunctions.h.

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.

Declared in NSPointerFunctions.h.

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.

Declared in NSPointerFunctions.h.

NSPointerFunctionsOpaquePersonality

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

Available in iOS 6.0 and later.

Declared in NSPointerFunctions.h.

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.

Declared in NSPointerFunctions.h.

NSPointerFunctionsCStringPersonality

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

Available in iOS 6.0 and later.

Declared in NSPointerFunctions.h.

NSPointerFunctionsStructPersonality

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

Available in iOS 6.0 and later.

Declared in NSPointerFunctions.h.

NSPointerFunctionsIntegerPersonality

Use unshifted value as hash and equality.

Available in iOS 6.0 and later.

Declared in NSPointerFunctions.h.

NSPointerFunctionsCopyIn

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

Available in iOS 6.0 and later.

Declared in NSPointerFunctions.h.

Discussion

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

Declared In
NSPointerFunctions.h