/usr/share/GNUstep/Documentation/Performance/GSUniqued.gsdoc is in libperformance-dev 0.5.0-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 | <?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.3//EN" "http://www.gnustep.org/gsdoc-1_0_3.dtd">
<gsdoc base="GSUniqued">
<head>
<title>GSUniqued class documentation</title>
<author name="Richard Frith-Macdonald">
<email address="rfm@gnu.org">
rfm@gnu.org
</email>
</author>
<copy>2014 Free Software Foundation, Inc.</copy>
</head>
<body>
<front><contents /></front>
<chapter>
<heading>
Software documentation for the GSUniqued class
</heading>
<class name="GSUniqued" super="NSObject">
<declared>GSUniqued.h</declared>
<desc>
<strong>Class</strong> used to unique other objects.
<br />
<p>
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. <br /> 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. <br /> 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
<strong>long</strong> lifetime and is tested for
equality with other instances frequently. <br />
In <strong>short</strong>, use with care; while uniquing
can have a big performance advantage for some programs,
this is actually quite rare.
</p>
<p>
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. <br /> Access to
the hash table is protected by locks so that uniqued
objects may be used freely in multiple threads.
<br /> The name of the subclass used is the name of
the original class with 'GSUniqued' added as a prefix.
</p>
</desc>
<method type="id" factory="yes">
<sel>copyUniqued:</sel>
<arg type="id<NSObject,NSCopying>">anObject</arg>
<desc>
This method returns a copy of its argument, uniqued so
that other such copies of equal objects will be the
same instance. <br /> The argument must respond to
<ref type="method" id="-copyWithZone:">
-copyWithZone:
</ref>
by returning an instance of class of immutable objects
(ie where the <ref type="method" id="-hash">-hash</ref>
and <ref type="method" id="-isEqual:">-isEqual:</ref>
methods are stable for that instance).
</desc>
</method>
</class>
</chapter>
<chapter>
<heading>
Software documentation for the NSObject(GSUniqued)
category
</heading>
<category name="GSUniqued" class="NSObject">
<declared>GSUniqued.h</declared>
<desc>
Category for uniquing any copyable object. <br />
NB. This must only be used by classes for which
<ref type="method" id="-copyWithZone:">
-copyWithZone:
</ref>
produces an instance of an immutable class.
</desc>
<method type="id">
<sel>copyUniqued</sel>
<desc>
This method returns a copy of the receiver uniqued so
that other such copies of equal objects content will
be the same instance.
</desc>
</method>
</category>
</chapter>
</body>
</gsdoc>
|