# GSTicker class documentation

### Authors

Richard Frith-Macdonald (`rfm@gnu.org`)

Copyright: (C) 2005 Free Software Foundation, Inc.

### Contents -

1. Software documentation for the GSTicker class
2. Software documentation for the GSTicker protocol
3. GSTicker functions

# Software documentation for the GSTicker class

## GSTicker : NSObject

> Declared in:
>   GSTicker.h

> Conforms to:
>   GSTicker

Wrapper round the more efficient ticker functions... this class provides convenience methods to get NSDate objects, and also provides support for registering observers ofr second by second ticks.
Method summary

- +last
- +newSecond:
- +now
- +registerObserver:userInfo:
- +start
- +tick
- +unregisterObserver:
- +update
- -last
- -newSecond:
- -now
- -start
- -tick
- -update

### last

+ (NSDate*) last;
Calls GSTickerTimeLast() and returns the result as an NSDate.

### newSecond:

+ (void) newSecond: (id)userInfo;
A dummy method... does nothing, but allows the GSTicker class itsself to act as an observer of regular timeouts.
Thus, you may register the class as its own observer in order to set up a timer to ensure that date/time information is updated at the start of every second.

### now

+ (NSDate*) now;
Calls GSTickerTimeNow() and returns the result as an NSDate.

### registerObserver: userInfo:

+ (void) registerObserver: (id<GSTicker>)anObject userInfo: (id)userInfo;
Registers an object to receive a [<GSTicker>-newSecond:] message at the start of every second.
Also starts a timer in the current thread (unless one is already running) to notify registered objects of new seconds.
The observer and the userInfo are retained by the ticker.
Adding an observer more than once has no effect.
NB. You must not add or remove observers inside the callback routine.

### start

+ (NSDate*) start;
Returns the result of GSTickerTimeStart() as an NSDate.

### tick

+ (unsigned) tick;
Calls GSTickerTimeTick() and returns the result.

### unregisterObserver:

+ (void) unregisterObserver: (id<GSTicker>)anObject;
Unregisters an observer previously set in the current thread using the +registerObserver:userInfo: method.
If all observers in a thread are removed, the timer for the thread is cancelled at the start of the next second.

### update

+ (void) update;
Calls GSTickerTimeNow() ;

### last

- (NSDate*) last;
Calls GSTickerTimeLast() and returns the result as an NSDate.

### newSecond:

- (void) newSecond: (id)userInfo;
See +newSecond:

### now

- (NSDate*) now;
Calls GSTickerTimeNow() and returns the result as an NSDate.

### start

- (NSDate*) start;
Returns the result of GSTickerTimeStart() as an NSDate.

### tick

- (unsigned) tick;
Calls GSTickerTimeTick() and returns the result.

### update

- (void) update;
Calls GSTickerTimeNow() ;

# Software documentation for the GSTicker protocol

## GSTicker

> Declared in:
>   GSTicker.h

> Conforms to:
>   NSObject

Description forthcoming.
Method summary

- -newSecond:

### newSecond:

- (void) newSecond: (id)userInfo;
Sent to tell observers that the ticker has noticed that a new second has occurred. The tick argument is the user information provided in when registering the observer.
This message is sent to each registered observer when the timeout for the thread occurs. It is not guaranteed to be called every second... other processing in the thread may delay it.

# GSTicker functions

### GSTickerTimeLast

NSTimeInterval GSTickerTimeLast();
Returns the timestamp of the most recent call to GSTickerTimeNow() .

### GSTickerTimeNow

NSTimeInterval GSTickerTimeNow();
Convenience function to provide timing information quickly.
This returns the current date/time, and stores the value for use by the GSTickerTimeLast() function.

### GSTickerTimeStart

NSTimeInterval GSTickerTimeStart();
This returns the timestamp from which GSTicker was first used.

### GSTickerTimeTick

unsigned int GSTickerTimeTick();
A convenience method to return the current clock 'tick'... which is the current second based on the time we started. This does not check the current time, but relies on GSTickerTimeLast() returning an up to date value (so if you need an accurate tick, you should ensure that GSTickerTimeNow() is called at least once a second).
The returned value is always greater than zero, and is basically calculated as (GSTickerTimeLast() - GSTickerTimeStart() + 1).
In the event that the system clock is reset into the past, the value of GSTickerTimeStart() is automatically adjusted to ensure that the result of a call to GSTickerTimeTick() is never less than the result of any earlier call to the function.