Question

Can someone please help me understand what the following method is doing?

+ (Game *) shared
{
    static Game *sharedSingleton;

    @synchronized(self)
    {
        if (!sharedSingleton)
        {
            sharedSingleton = [[Game alloc] init];
        }
    }

    return sharedSingleton;
}

Answer 1

Obviously, the idea behind a singleton is to create only a single instance. The first step in achieving this is to declare a static instance of the class via the line static Game *sharedSingleton;.

The second step is to check whether the single instance is already created, and if it isn’t, to create it, or if it is, to return the existing single instance. However, this second step opens up the potential for problems in the event that 2 separate threads try to call the +shared method at the same exact moment. You wouldn’t want one thread to be modifying the single sharedSingleton variable while another thread is trying to examine it, as it could produce unexpected results.

The solution to this problem is to use the @synchronized() compiler directive to synchronize access to the object specified between the parenthesis. For example, say this single shared instance of the Game class has an instance variable named players which is an NSMutableArray of instances of a Player class. Let’s say the Game class had an -addPlayer: method, which would modify the players instance variable by adding the specified player. It’s important that if that method were called from multiple threads, that only one thread be allowed to modify the players array at a time. So, the implementation of that method might look something like this:

- (void)addPlayer:(Player *)player {
   if (player == nil) return;
   @synchronized(players) {
      [players addObject:player];
   }
}

Using the @synchronized() directive makes sure only one thread can access the players variable at a time. If one thread attempts to while another thread is currently accessing it, the first thread must wait until the other thread finishes.

While it’s more straightforward when you’re talking about an instance variable, it’s perhaps less clear how to achieve the same type of result within the single creation method of the class itself. The self in the @synchronized(self) line in the following code basically equates to the Game class itself. By synchronizing on the Game class, it assures that the sharedSingleton = [[Game alloc] init]; line is only ever called once.

+ (Game *) shared
{
    static Game *sharedSingleton;

    @synchronized(self) // assures only one thread can call [Game shared] at a time
    {
        if (!sharedSingleton)
        {
            sharedSingleton = [[Game alloc] init];
        }
    }

    return sharedSingleton;
}

[EDIT]: updated. Based on my tests a while back (and I just re-tested it now), the following all appear to be equivalent:

Outside @implementation:

Game *sharedInstance;

@implementation Game
+ (Game *)sharedGame {
    @synchronized(self) {
        if (sharedInstance == nil) {
            sharedInstance = [[[self class] alloc] init];
        }
    }
    return sharedInstance;
}
@end

Outside @implementation, static:

static Game *sharedInstance;

@implementation Game
+ (Game *)sharedGame {
    @synchronized(self) {
        if (sharedInstance == nil) {
            sharedInstance = [[[self class] alloc] init];
        }
    }
    return sharedInstance;
}
@end

Inside @implementation:

@implementation Game

static Game *sharedInstance;

+ (Game *)sharedGame {
    @synchronized(self) {
        if (sharedInstance == nil) {
            sharedInstance = [[[self class] alloc] init];
        }
    }
    return sharedInstance;
}
@end

Inside +sharedGame:

@implementation Game
+ (Game *)sharedGame {
    static Game *sharedInstance;
    @synchronized(self) {
        if (sharedInstance == nil) {
            sharedInstance = [[[self class] alloc] init];
        }
    }
    return sharedInstance;
}
@end

The only difference is that in the first variation, without the static keyword, sharedInstance doesn’t show up under File Statics in gdb. And obviously, in the last variation, sharedInstance isn’t visible outside of the +sharedGame method. But practically speaking, they all assure that when you call [Game sharedInstance] you’ll get back the sharedInstance, and that the sharedInstance is only created once. (Note, however, that further precautions would be needed to prevent someone from creating a non-singleton instance using something like Game *game = [[Game alloc] init];).