NEVER!

Seriously. Just don't do it.

Just follow the Memory Management Guidelines and only release what you alloc, new or copy (or anything you called retain upon originally).

@bbum said it best here on SO, and in even more detail on his blog.

What problems can you get from using it? All it does is return the retain count of the object. I have never called it and can't think of any reason that I would. I have overridden it in singletons to make sure they aren't deallocated though.

Take a look at the Apple documentation on NSObject, it pretty much covers your question: NSObject retainCount

In short, retainCount is probably useless to you unless you've implemented your own reference counting system (and I can almost guarantee you won't have).

In Apple's own words, retainCount is "typically of no value in debugging memory management issues".

You should not be worrying about memory leaking until your app is up and running and doing something useful.

Once it is, fire up Instruments and use the app and see if memory leaks really happen. In most cases you created an object yourself (thus you own it) and forgot to release it after you were done.

Don't try and optimize your code as you are writing it, your guesses as to what may leak memory or take too long are often wrong when you actually use the app normally.

Do try and write correct code e.g. if you create an object using alloc and such, then make sure you release it properly.

Autoreleased objects are one case where checking -retainCount is uninformative and potentially misleading. The retain count tells you nothing about how many times -autorelease has been called on an object and therefore how many time it will be released when the current autorelease pool drains.

You should never use -retainCount, because it never tells you anything useful. The implementation of the Foundation and AppKit/UIKit frameworks is opaque; you don't know what's being retained, why it's being retained, who's retaining it, when it was retained, and so on.

For example:

• You'd think that [NSNumber numberWithInt:1] would have a retainCount of 1. It doesn't. It's 2.
• You'd think that @"Foo" would have a retainCount of 1. It doesn't. It's 1152921504606846975.
• You'd think that [NSString stringWithString:@"Foo"] would have a retainCount of 1. It doesn't. Again, it's 1152921504606846975.

Basically, since anything can retain an object (and therefore alter its retainCount), and since you don't have the source to most of the code that runs an application, an object's retainCount is meaningless.

If you're trying to track down why an object isn't getting deallocated, use the Leaks tool in Instruments. If you're trying to track down why an object was deallocated too soon, use the Zombies tool in Instruments.

But don't use -retainCount. It's a truly worthless method.

edit

Please everyone go to http://bugreport.apple.com and request that -retainCount be deprecated. The more people that ask for it, the better.

edit #2

As an update,[NSNumber numberWithInt:1] now has a retainCount of 9223372036854775807. If your code was expecting it to be 2, your code has now broken.

I do find retainCounts very useful when checked using 'Instruments'.

Using the 'allocations' tool, make sure 'Record reference counts' is turned on and you can go into any object and see its retainCount history.

By pairing allocs and releases you can get a good picture of what is going on and often solve those difficult cases where something is not being released.

This has never let me down - including finding bugs in early beta releases of iOS.

You should never use it in your code, but it could definitely help when debugging

Never use the -retainCount in your code. However if you use, you will never see it returns zero. Think about why. :-)

Of course you should never use the retainCount method in your code, since the meaning of its value depends on how many autoreleases have been applied to the object and that is something you cannot predict. However it is very useful for debugging -- especially when you are hunting down memory leaks in code that calls methods of Appkit objects outside of the main event loop -- and it should not be deprecated.

In your effort to make your point you seriously overstated the inscrutable nature of the value. It is true that it is not always a reference count. There are some special values that are used for flags, for example to indicate that an object should never be deallocated. A number like 1152921504606846975 looks very mysterious until you write it in hex and get 0xfffffffffffffff. And 9223372036854775807 is 0x7fffffffffffffff in hex. And it really is not so surprising that someone would choose to use values like these as flags, given that it would take almost 3000 years to get a retainCount as high as the larger number, assuming you incremented the retainCount 100,000,000 times per second.

The examples used in Dave's post are NSNumber and NSStrings...so, if you use some other classes, such as UIViews, I'm sure you will get the correct answer(The retain count depends on the implementation, and it's predictable).