Regenerated

git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@9631 72102866-910b-0410-8b05-ffd578937521

Documentation/gsdoc/NSFunctions.html

@@ -8,10 +8,13 @@
  <dl>
 <dt><a href ="http://www.gnustep.org/developers/whoiswho.html">Richard Frith-Macdonald</a>
 <dd>
+<dt><a href ="http://www.gnustep.org/developers/whoiswho.html">Nicola Pero</a>
+<dd>
 </dl>
 <p>Version: $Revision$</p>
 <p>Date: $Date$</p>
 <h2><a name ="cont-0">Functions</a></h2>
+<h3><a name ="cont-1">Thread Function</a></h3>
 <h2><a name ="function-0">GSCurrentThread</a></h2>
 <p><b>Declared in: </b> Foundation/NSThread.h</p>
 <b>Prototype: </b> NSThread* GSCurrentThread()<br>
@@ -40,7 +43,7 @@
 
 	  <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
 	    GNUstep system.  All such threads should call this function
 	    before attempting to use any GNUstep objects.
@@ -66,7 +69,7 @@
 
 	  <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
 	    system.
 	  </p>
@@ -81,7 +84,199 @@
 
 	
  <hr>
-<h2><a name ="cont-1">Types</a></h2>
+<h3><a name ="cont-2">Debugging Functions - Counting Instances of Classes</a></h3>
+<h2><a name ="function-3">GSDebugAllocationActive</a></h2>
+<p><b>Declared in: </b> Foundation/NSDebug.h</p>
+<b>Prototype: </b> BOOL GSDebugAllocationActive(BOOL active)<br>
+
+	  <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>
+
+	
+ <hr>
+<h2><a name ="function-4">GSDebugAllocationCount</a></h2>
+<p><b>Declared in: </b> Foundation/NSDebug.h</p>
+<b>Prototype: </b> int GSDebugAllocationCount(Class c)<br>
+
+	  <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>
+
+	
+ <hr>
+<h2><a name ="function-5">GSDebugAllocationPeak</a></h2>
+<p><b>Declared in: </b> Foundation/NSDebug.h</p>
+<b>Prototype: </b> int GSDebugAllocationPeak(Class c)<br>
+
+	  <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>
+
+	
+ <hr>
+<h2><a name ="function-6">GSDebugAllocationTotal</a></h2>
+<p><b>Declared in: </b> Foundation/NSDebug.h</p>
+<b>Prototype: </b> int GSDebugAllocationTotal(Class c)<br>
+
+	  <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>
+
+	
+ <hr>
+<h2><a name ="function-7">GSDebugAllocationClassList</a></h2>
+<p><b>Declared in: </b> Foundation/NSDebug.h</p>
+<b>Prototype: </b> Class* GSDebugAllocationClassList()<br>
+
+	  <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>
+
+	
+ <hr>
+<h2><a name ="function-8">GSDebugAllocationList</a></h2>
+<p><b>Declared in: </b> Foundation/NSDebug.h</p>
+<b>Prototype: </b> const char* GSDebugAllocationList()<br>
+
+	  <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>
+
+	
+ <hr>
+<h2><a name ="function-9">GSDebugAllocationListAll</a></h2>
+<p><b>Declared in: </b> Foundation/NSDebug.h</p>
+<b>Prototype: </b> const char* GSDebugAllocationListAll()<br>
+
+	  <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>
+
+	
+ <hr>
+<h3><a name ="cont-3">Debugging Functions - Tracking Instances of Classes</a></h3>
+<h2><a name ="function-10">GSDebugAllocationActiveRecordingObjects</a></h2>
+<p><b>Declared in: </b> Foundation/NSDebug.h</p>
+<b>Prototype: </b> void GSDebugAllocationActiveRecordingObjects()<br>
+
+	  <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>
+
+	
+ <hr>
+<h2><a name ="function-11">GSDebugAllocationListRecordedObjects</a></h2>
+<p><b>Declared in: </b> Foundation/NSDebug.h</p>
+<b>Prototype: </b> NSArray * GSDebugAllocationListRecordedObjects(Class c)<br>
+
+	  <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>
+
+	
+ <hr>
+<h2><a name ="cont-4">Types</a></h2>
 <h3><a name ="NSRange">NSRange</a></h3>
 <p><b>Declared in: </b> Foundation/NSRange.h</p>
 <b>typedef </b> 

Documentation/gsdoc/NSLock.html

@@ -8,7 +8,7 @@
 <h1>NSLock</h1>
 <h3>Authors </h3>
  <dl>
-<dt><a href ="http://www.gnustep.org/developers/whoiswho.html">Richard Frith-Macdonald</a>
+<dt><a href ="http://www.gnustep.org/developers/whoiswho.html">Adam Fedor</a>
 <dd>
 </dl>
 <p>Version: $Revision$</p>
@@ -21,6 +21,14 @@
 </p>
 <hr>
 
+	  An NSLock is used in multi-threaded applications to protect critical
+	  pieces of code. While one thread holds a lock within a piece of code,
+	  another thread cannot execute that code until the first thread has
+	  given up it's hold on the lock. The limitation of NSLock is that 
+	  you can only lock an
+	  NSLock once and it must be unlocked before it can be aquired again. 
+	  Other lock classes, notably NSRecursiveLock, have 
+	  different restrictions.
           
 <h2>Instance Variables </h2>
 <ul>
@@ -34,11 +42,19 @@
 <h3><a name ="method-0">lockBeforeDate:</a></h3>
 - (BOOL) <b>lockBeforeDate:</b> (NSDate*)limit;<br>
 
+	  Attempts to aquire a lock before the date limit passes. It returns YES
+	  if it can. It returns NO if it cannot, or if the current thread already
+	  has the lock (but it waits until the time limit is up before returning
+	  NO).
           
  <hr>
 <h3><a name ="method-1">tryLock</a></h3>
 - (BOOL) <b>tryLock</b>;<br>
 
+	  Attempts to aquire a lock, but returns immediately if the lock
+	  cannot be aquired. It returns YES if the lock is aquired. It returns
+	  NO if the lock cannot be aquired or if the current thread already has
+	  the lock.
           
  <hr>
 </body>

Documentation/gsdoc/NSRecursiveLock.html

@@ -8,7 +8,7 @@
 <h1>NSRecursiveLock</h1>
 <h3>Authors </h3>
  <dl>
-<dt><a href ="http://www.gnustep.org/developers/whoiswho.html">Richard Frith-Macdonald</a>
+<dt><a href ="http://www.gnustep.org/developers/whoiswho.html">Adam Fedor</a>
 <dd>
 </dl>
 <p>Version: $Revision$</p>
@@ -21,6 +21,11 @@
 </p>
 <hr>
 
+	  See NSLock for more information about what a lock is. A recursive
+	  lock extends NSLock in that you can lock a recursive lock multiple
+	  times. Each lock must be balanced by a cooresponding unlock, and the
+	  lock is not released for another thread to aquire until the last
+	  unlock call is made (cooresponding to the fist lock message). 
           
 <h2>Instance Variables </h2>
 <ul>
@@ -34,11 +39,17 @@
 <h3><a name ="method-0">lockBeforeDate:</a></h3>
 - (BOOL) <b>lockBeforeDate:</b> (NSDate*)limit;<br>
 
+	  Attempts to aquire a lock before the date limit passes. It returns 
+	  YES if it can. It returns NO if it cannot
+	  (but it waits until the time limit is up before returning NO).
           
  <hr>
 <h3><a name ="method-1">tryLock</a></h3>
 - (BOOL) <b>tryLock</b>;<br>
 
+	  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
+	  called multiple times to make nested locks.
           
  <hr>
 </body>