Firstly I’d like to draw your attention to the Cocoa/CF documentation (which is always a great first port of call). The Apple docs have a section at the top of each reference article called “Companion Guides”, which lists guides for the topic being documented (if any exist). For example, with
NSTimer, the documentation lists two companion guides:
- Timer Programming Topics for Cocoa
- Threading Programming Guide
For your situation, the Timer Programming Topics article is likely to be the most useful, whilst threading topics are related but not the most directly related to the class being documented. If you take a look at the Timer Programming Topics article, it’s divided into two parts:
- Using Timers
For articles that take this format, there is often an overview of the class and what it’s used for, and then some sample code on how to use it, in this case in the “Using Timers” section. There are sections on “Creating and Scheduling a Timer”, “Stopping a Timer” and “Memory Management”. From the article, creating a scheduled, non-repeating timer can be done something like this:
[NSTimer scheduledTimerWithTimeInterval:2.0 target:self selector:@selector(targetMethod:) userInfo:nil repeats:NO];
This will create a timer that is fired after 2.0 seconds and calls
self with one argument, which is a pointer to the
If you then want to look in more detail at the method you can refer back to the docs for more information, but there is explanation around the code too.
If you want to stop a timer that is one which repeats, (or stop a non-repeating timer before it fires) then you need to keep a pointer to the
NSTimer instance that was created; often this will need to be an instance variable so that you can refer to it in another method. You can then call
invalidate on the
[myTimer invalidate]; myTimer = nil;
It’s also good practice to
nil out the instance variable (for example if your method that invalidates the timer is called more than once and the instance variable hasn’t been set to
nil and the
NSTimer instance has been deallocated, it will throw an exception).
Note also the point on Memory Management at the bottom of the article:
Because the run loop maintains the timer, from the perspective of memory management there’s typically no need to keep a reference to a timer after you’ve scheduled it. Since the timer is passed as an argument when you specify its method as a selector, you can invalidate a repeating timer when appropriate within that method. In many situations, however, you also want the option of invalidating the timer—perhaps even before it starts. In this case, you do need to keep a reference to the timer, so that you can send it an invalidate message whenever appropriate. If you create an unscheduled timer (see “Unscheduled Timers”), then you must maintain a strong reference to the timer (in a reference-counted environment, you retain it) so that it is not deallocated before you use it.