GSUniqued class documentation

Authors

Richard Frith-Macdonald (rfm@gnu.org)

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


Contents -

  1. Software documentation for the GSUniqued class
  2. Software documentation for the NSObject(GSUniqued) category

Software documentation for the GSUniqued class

GSUniqued : NSObject

Declared in:
GSUniqued.h
Class used to unique other objects.

The point of this class is to lower the memory footprint and speed up comparisons (pointer equality) in cases where an application stores multiple copies of the same object in various maps.
Since uniquing is performed by storing an immutable copy of the original object in a map until there are no further references to that object, it's pointless to use this uniquing unless the application would be storing at least two copies of the object.
Also, since this is thread-safe there is a lock management overhead wherever a uniqued object is released, so performance gains are to be expected only if the uniqued object has a relatively long lifetime and is tested for equality with other instances frequently.
In short, use with care; while uniquing can have a big performance advantage for some programs, this is actually quite rare.

The internal implementation of the uniquing works by taking immutable copies of the objects to be uniqued, storing those copies in a hash table, and swizzling their class pointers to a sub-class which will automatically remove the instance from the hash table before it is deallocated.
Access to the hash table is protected by locks so that uniqued objects may be used freely in multiple threads.
The name of the subclass used is the name of the original class with 'GSUniqued' added as a prefix.

Method summary

copyUniqued: 

+ (id) copyUniqued: (id)anObject;
This method returns a copy of its argument, uniqued so that other such copies of equal objects will be the same instance.
The argument must respond to -copyWithZone: by returning an instance of class of immutable objects (ie where the -hash and -isEqual: methods are stable for that instance).

Software documentation for the NSObject(GSUniqued) category

NSObject(GSUniqued)

Declared in:
GSUniqued.h
Category for uniquing any copyable object.
NB. This must only be used by classes for which -copyWithZone: produces an instance of an immutable class.
Method summary

copyUniqued 

- (id) copyUniqued;
This method returns a copy of the receiver uniqued so that other such copies of equal objects content will be the same instance.