mirror of
https://github.com/gnustep/libs-base.git
synced 2025-05-31 16:50:58 +00:00
Documented GSDebugAllocation functions in NSFunctions; fixed syntax error
in NSRecursiveLock git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@9629 72102866-910b-0410-8b05-ffd578937521
This commit is contained in:
nico
parent
553e1540b5
commit
aabec6bdae
2 changed files with 200 additions and 3 deletions
|
|
@ -7,12 +7,18 @@
|
||||||
<email address="rfm@gnu.org"/>
|
<email address="rfm@gnu.org"/>
|
||||||
<url url="http://www.gnustep.org/developers/whoiswho.html"/>
|
<url url="http://www.gnustep.org/developers/whoiswho.html"/>
|
||||||
</author>
|
</author>
|
||||||
|
<author name="Nicola Pero">
|
||||||
|
<email address="n.pero@mi.flashnet.it"/>
|
||||||
|
<url url="http://www.gnustep.org/developers/whoiswho.html"/>
|
||||||
|
</author>
|
||||||
<version>$Revision$</version>
|
<version>$Revision$</version>
|
||||||
<date>$Date$</date>
|
<date>$Date$</date>
|
||||||
</head>
|
</head>
|
||||||
<body>
|
<body>
|
||||||
<chapter>
|
<chapter>
|
||||||
<heading>Functions</heading>
|
<heading>Functions</heading>
|
||||||
|
<section>
|
||||||
|
<heading>Thread Function</heading>
|
||||||
<function name="GSCurrentThread" type="NSThread*">
|
<function name="GSCurrentThread" type="NSThread*">
|
||||||
<declared>Foundation/NSThread.h</declared>
|
<declared>Foundation/NSThread.h</declared>
|
||||||
<desc>
|
<desc>
|
||||||
|
|
@ -36,7 +42,7 @@
|
||||||
<declared>Foundation/NSThread.h</declared>
|
<declared>Foundation/NSThread.h</declared>
|
||||||
<desc>
|
<desc>
|
||||||
<p>
|
<p>
|
||||||
This functiion is provided to let threads started by some other
|
This function is provided to let threads started by some other
|
||||||
software library register themselves to be used with the
|
software library register themselves to be used with the
|
||||||
GNUstep system. All such threads should call this function
|
GNUstep system. All such threads should call this function
|
||||||
before attempting to use any GNUstep objects.
|
before attempting to use any GNUstep objects.
|
||||||
|
|
@ -57,7 +63,7 @@
|
||||||
<declared>Foundation/NSThread.h</declared>
|
<declared>Foundation/NSThread.h</declared>
|
||||||
<desc>
|
<desc>
|
||||||
<p>
|
<p>
|
||||||
This functiion is provided to let threads started by some other
|
This function is provided to let threads started by some other
|
||||||
software library unregister themselves from the GNUstep threading
|
software library unregister themselves from the GNUstep threading
|
||||||
system.
|
system.
|
||||||
</p>
|
</p>
|
||||||
|
|
@ -70,6 +76,197 @@
|
||||||
</desc>
|
</desc>
|
||||||
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
|
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
|
||||||
</function>
|
</function>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<heading>Debugging Functions - Counting Instances of Classes</heading>
|
||||||
|
<function name="GSDebugAllocationActive" type="BOOL">
|
||||||
|
<arg type="BOOL">active</arg>
|
||||||
|
<declared>Foundation/NSDebug.h</declared>
|
||||||
|
<desc>
|
||||||
|
<p>
|
||||||
|
This function is a GNUstep extension. It activates or
|
||||||
|
deactivates object allocation debugging. Returns the
|
||||||
|
previous state. You should call this function to activate
|
||||||
|
allocation debugging before using any of the functions
|
||||||
|
described in this section. Object allocation debugging
|
||||||
|
should not affect performance too much, and is very useful
|
||||||
|
as it allows you to monitor how many objects of each class
|
||||||
|
your application has allocated. See below for a detailed
|
||||||
|
description of the info you can get, and why it is useful.
|
||||||
|
</p>
|
||||||
|
</desc>
|
||||||
|
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
|
||||||
|
</function>
|
||||||
|
|
||||||
|
<function name="GSDebugAllocationCount" type="int">
|
||||||
|
<arg type="Class">c</arg>
|
||||||
|
<declared>Foundation/NSDebug.h</declared>
|
||||||
|
<desc>
|
||||||
|
<p>
|
||||||
|
This function is a GNUstep extension. Returns the number
|
||||||
|
of instances of the specified class which are currently
|
||||||
|
allocated. This number is very important to detect memory
|
||||||
|
leaks. If you notice that this number is constantly
|
||||||
|
increasing without apparent reason, it is very likely a
|
||||||
|
memory leak - you need to check that you are correctly
|
||||||
|
releasing objects of this class, otherwise when your
|
||||||
|
application runs for a long time, it will eventually
|
||||||
|
allocate so many objects as to eat up all your system's
|
||||||
|
memory ...
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
This function, like the ones below, returns the number of
|
||||||
|
objects allocated/released from the time when
|
||||||
|
GSDebugAllocationActive was first called. A negative
|
||||||
|
number means that in total, there are less objects of this
|
||||||
|
class allocated now than there were when you called
|
||||||
|
GSDebugAllocationActive; a positive one means there are
|
||||||
|
more.
|
||||||
|
</p>
|
||||||
|
</desc>
|
||||||
|
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
|
||||||
|
</function>
|
||||||
|
|
||||||
|
<function name="GSDebugAllocationPeak" type="int">
|
||||||
|
<arg type="Class">c</arg>
|
||||||
|
<declared>Foundation/NSDebug.h</declared>
|
||||||
|
<desc>
|
||||||
|
<p>
|
||||||
|
This function is a GNUstep extension. Returns the peak
|
||||||
|
number of instances of the specified class which have been
|
||||||
|
concurrently allocated. If this number is very high, it
|
||||||
|
means at some point in time you had a situation with a
|
||||||
|
huge number of objects of this class allocated - this is
|
||||||
|
an indicator that probably at some point in time your
|
||||||
|
application was using a lot of memory - so you might want
|
||||||
|
to investigate whether you can prevent this problem by
|
||||||
|
inserting autorelease pools in your application's
|
||||||
|
processing loops.
|
||||||
|
</p>
|
||||||
|
</desc>
|
||||||
|
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
|
||||||
|
</function>
|
||||||
|
|
||||||
|
<function name="GSDebugAllocationTotal" type="int">
|
||||||
|
<arg type="Class">c</arg>
|
||||||
|
<declared>Foundation/NSDebug.h</declared>
|
||||||
|
<desc>
|
||||||
|
<p>
|
||||||
|
This function is a GNUstep extension. Returns the total
|
||||||
|
number of instances of the specified class which have been
|
||||||
|
allocated - basically the number of times you have
|
||||||
|
allocated an object of this class. If this number is very
|
||||||
|
high, it means you are creating a lot of objects of this
|
||||||
|
class; even if you are releasing them correctly, you must
|
||||||
|
not forget that allocating and deallocating objects is
|
||||||
|
usually one of the slowest things you can do, so you might
|
||||||
|
want to consider whether you can reduce the number of
|
||||||
|
allocations and deallocations that you are doing - for
|
||||||
|
example, by recycling objects of this class, uniquing
|
||||||
|
them, and/or using some sort of flyweight pattern. It
|
||||||
|
might also be possible that you are unnecessarily creating
|
||||||
|
too many objects of this class. Well - of course some times
|
||||||
|
there is nothing you can do about it.
|
||||||
|
</p>
|
||||||
|
</desc>
|
||||||
|
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
|
||||||
|
</function>
|
||||||
|
|
||||||
|
<function name="GSDebugAllocationClassList" type="Class*">
|
||||||
|
<declared>Foundation/NSDebug.h</declared>
|
||||||
|
<desc>
|
||||||
|
<p>
|
||||||
|
This function is a GNUstep extension. Returns a NULL
|
||||||
|
terminated array listing all the classes for which
|
||||||
|
statistical information has been collected. Usually, you
|
||||||
|
call this function, and then loop on all the classes returned,
|
||||||
|
and for each one you get current, peak and total count by
|
||||||
|
using GSDebugAllocationCount, GSDebugAllocationPeak and
|
||||||
|
GSDebugAllocationTotal.
|
||||||
|
</p>
|
||||||
|
</desc>
|
||||||
|
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
|
||||||
|
</function>
|
||||||
|
|
||||||
|
<function name="GSDebugAllocationList" type="const char*">
|
||||||
|
<declared>Foundation/NSDebug.h</declared>
|
||||||
|
<desc>
|
||||||
|
<p>
|
||||||
|
This function is a GNUstep extension. Returns a newline
|
||||||
|
separated list of the classes which have instances
|
||||||
|
allocated, and the instance counts. If the 'changeFlag'
|
||||||
|
argument is YES then the list gives the number of
|
||||||
|
instances allocated/deallocated since the function was
|
||||||
|
last called. This function only returns the current count
|
||||||
|
of instances (not the peak or total count), but its output
|
||||||
|
is ready to be displayed or logged.
|
||||||
|
</p>
|
||||||
|
</desc>
|
||||||
|
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
|
||||||
|
</function>
|
||||||
|
|
||||||
|
<function name="GSDebugAllocationListAll" type="const char*">
|
||||||
|
<declared>Foundation/NSDebug.h</declared>
|
||||||
|
<desc>
|
||||||
|
<p>
|
||||||
|
This function is a GNUstep extension. Returns a newline
|
||||||
|
separated list of the classes which have had instances
|
||||||
|
allocated at any point, and the total count of the number
|
||||||
|
of instances allocated for each class. The difference with
|
||||||
|
GSDebugAllocationList is that this function returns also
|
||||||
|
classes which have no objects allocated at the moment, but
|
||||||
|
which had in the past.
|
||||||
|
</p>
|
||||||
|
</desc>
|
||||||
|
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
|
||||||
|
</function>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<heading>Debugging Functions - Tracking Instances of Classes</heading>
|
||||||
|
<function name="GSDebugAllocationActiveRecordingObjects" type="void">
|
||||||
|
<declared>Foundation/NSDebug.h</declared>
|
||||||
|
<desc>
|
||||||
|
<p>
|
||||||
|
This function is a GNUstep extension. It activates
|
||||||
|
tracking all allocated instances of the specified class
|
||||||
|
(passed as argument). This tracking can slow your
|
||||||
|
application down, so you should use it only when you are
|
||||||
|
into serious debugging. Usually, you will monitor your
|
||||||
|
application by using the functions GSDebugAllocationList
|
||||||
|
and similia (see above), which do not slow things down
|
||||||
|
much and return the number of allocated instances; when
|
||||||
|
(if) by studying the reports generated by these functions
|
||||||
|
you have found a leak of objects of a certain class, and
|
||||||
|
if you can't figure out how to fix it by looking at the
|
||||||
|
code, you can use this function to start tracking
|
||||||
|
allocated instances of that class, and the following one
|
||||||
|
can sometime allow you to list the leaked objects directly.
|
||||||
|
</p>
|
||||||
|
</desc>
|
||||||
|
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
|
||||||
|
</function>
|
||||||
|
|
||||||
|
<function name="GSDebugAllocationListRecordedObjects" type="NSArray *">
|
||||||
|
<arg type="Class">c</arg>
|
||||||
|
<declared>Foundation/NSDebug.h</declared>
|
||||||
|
<desc>
|
||||||
|
<p>
|
||||||
|
This function is a GNUstep extension. Returns an array
|
||||||
|
containing all the allocated objects of a certain class
|
||||||
|
which have been recorded (to start the recording, you need
|
||||||
|
to invoke GSDebugAllocationActiveRecordedObjects).
|
||||||
|
Presumably, you will immediately call -description on them
|
||||||
|
to find out the objects you are leaking. The objects are
|
||||||
|
returned in an array, so until the array is autoreleased,
|
||||||
|
the objects are not released.
|
||||||
|
</p>
|
||||||
|
</desc>
|
||||||
|
<standards><NotOpenStep/><NotMacOS-X/><GNUstep/></standards>
|
||||||
|
</function>
|
||||||
|
</section>
|
||||||
</chapter>
|
</chapter>
|
||||||
|
|
||||||
<chapter>
|
<chapter>
|
||||||
|
|
|
||||||
|
|
@ -34,10 +34,10 @@
|
||||||
</method>
|
</method>
|
||||||
<method type="BOOL">
|
<method type="BOOL">
|
||||||
<sel>tryLock</sel>
|
<sel>tryLock</sel>
|
||||||
|
<desc>
|
||||||
Attempts to aquire a lock, but returns NO immediately if the lock
|
Attempts to aquire a lock, but returns NO immediately if the lock
|
||||||
cannot be aquired. It returns YES if the lock is aquired. Can be
|
cannot be aquired. It returns YES if the lock is aquired. Can be
|
||||||
called multiple times to make nested locks.
|
called multiple times to make nested locks.
|
||||||
<desc>
|
|
||||||
</desc>
|
</desc>
|
||||||
</method>
|
</method>
|
||||||
</class>
|
</class>
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue