What is objc_setAssociatedObject() and in what cases should it be used?

In a project I have taken on, the original author has opted to use objc_setAssociatedObject() and I'm not 100% clear what it does or why they decided to use it.

I decided to look it up and, unfortunately, the docs aren't very descriptive about its purpose.

objc_setAssociatedObject
Sets an associated value for a given object using a given key and association policy.
void objc_setAssociatedObject(id object, void *key, id value, objc_AssociationPolicy policy)
Parameters
object
The source object for the association.
key
The key for the association.
value
The value to associate with the key key for object. Pass nil to clear an existing association.
policy
The policy for the association. For possible values, see “Associative Object Behaviors.”

So what exactly does this function do and in what cases should it be used?

---

Edit after reading answers

So what is the point in the following code?

Device *device = [self.list objectAtIndex:[indexPath row]];
DeviceViewController *next = [[DeviceViewController alloc] initWithController:self.controller
																			device:device
																			   item:self.rootVC.selectedItem];	
	objc_setAssociatedObject(device, &kDeviceControllerKey, next, OBJC_ASSOCIATION_RETAIN);

What is the point in associating the device with the view controller if it's already an instance variable?

objc_setAssociatedObject adds a key value store to each Objective-C object. It lets you store additional state for the object, not reflected in its instance variables.

It's really convenient when you want to store things belonging to an object outside of the main implementation. One of the main use cases is in categories where you cannot add instance variables. Here you use objc_setAssociatedObject to attach your additional variables to the self object.

When using the right association policy your objects will be released when the main object is deallocated.

From the reference documents on Objective-C Runtime Reference:

> You use the Objective-C runtime > function objc_setAssociatedObject to > make an association between one object > and another. The function takes four > parameters: the source object, a key, > the value, and an association policy > constant. The key is a void pointer. > > - The key for each association must be unique. A typical pattern is to > use a static variable. > - The policy specifies whether the associated object is assigned,
> retained, or copied, and whether the
> association is be made atomically or
> non-atomically. This pattern is
> similar to that of the attributes of
> a declared property (see “Property
> Declaration Attributes”). You specify > the policy for the relationship using > a constant (see
> objc_AssociationPolicy and
> Associative Object Behaviors).

Establishing an association between an array and a string

static char overviewKey;

 

NSArray *array =

    [[NSArray alloc] initWithObjects:@"One", @"Two", @"Three", nil];

// For the purposes of illustration, use initWithFormat: to ensure

// the string can be deallocated

NSString *overview =

    [[NSString alloc] initWithFormat:@"%@", @"First three numbers"];

 

objc_setAssociatedObject (

    array,

    &overviewKey,

    overview,

    OBJC_ASSOCIATION_RETAIN

);

 

[overview release];

// (1) overview valid

[array release];

// (2) overview invalid

> At point 1, the string overview is > still valid because the > OBJC_ASSOCIATION_RETAIN policy > specifies that the array retains the > associated object. When the array is > deallocated, however (at point 2), > overview is released and so in this > case also deallocated. If you try to, > for example, log the value of > overview, you generate a runtime > exception.

Here is a list of use cases for object associations:

one: To add instance variables to categories. In general this technique is advised against, but here is an example of a legitimate use. Let's say you want to simulate additional instance variables for objects you cannot modify (we are talking about modifying the object itself, ie without subclassing). Let's say setting a title on a UIImage.

// UIImage-Title.h:
@interface UIImage(Title)
@property(nonatomic, copy) NSString *title;
@end 

// UIImage-Title.m:
#import <Foundation/Foundation.h>
#import <objc/runtime.h>

static char titleKey;

@implementation UIImage(Title)
- (NSString *)title
{
    return objc_getAssociatedObject(self, &titleKey);
}

- (void)setTitle:(NSString *)title
{
    objc_setAssociatedObject(self, &titleKey, title, OBJC_ASSOCIATION_COPY);
}
@end

Also, here is a pretty complex (but awesome) way of using associated objects with categories.. it basically allows you to pass in a block instead of a selector to a UIControl.

---

two: Dynamically adding state information to an object not covered by its instance variables in conjunction with KVO.

The idea is that your object gains state information only during runtime (ie dynamically). So the idea is that although you can store this state info in an instance variable, the fact that you're attaching this info into a an object instantiated at runtime and dynamically associating it with the other object, you are highlighting the fact that this is a dynamic state of the object.

One excellent example that illustrates this is this library, in which associative objects are used with KVO notifications. Here is an excerpt of the code (note: this KVO notification isn't necessary to run make the code in that library work.. rather it's put there by the author for convenience, basically any object that registers to this will be notified via KVO that changes have happened to it):

static char BOOLRevealing;

- (BOOL)isRevealing
{
	return [(NSNumber*)objc_getAssociatedObject(self, &BOOLRevealing) boolValue];
} 

- (void)_setRevealing:(BOOL)revealing
{
	[self willChangeValueForKey:@"isRevealing"];
	objc_setAssociatedObject(self, &BOOLRevealing, 
       [NSNumber numberWithBool:revealing], OBJC_ASSOCIATION_RETAIN_NONATOMIC);
	[self didChangeValueForKey:@"isRevealing"];
}

---

bonus: take a look at this discussion/explanation of associated objects by Mattt Thompson, author of the seminal AFNetworking library

To answer your revised question:

> What is the point in associating the device with the view controller if it's already an instance variable?

There are several reasons why you might want to do this.

• the Device class doesn't have a controller instance variable, or property and you can't change it or subclass it e.g. you don't have the source code.
• you want two controllers associated with the device object and you can't change the device class or subclass it.

Personally, I think it is very rare to need to use low level Objective-C runtime functions. This looks like a code smell to me.