gnustep/libs-base
0
0
Fork 0
mirror of https://github.com/gnustep/libs-base.git synced 2025-04-22 16:33:29 +00:00
Code Issues Projects Releases Packages Wiki Activity

Improve documentation

Browse source 
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@13757 72102866-910b-0410-8b05-ffd578937521
This commit is contained in:
Richard Frith-Macdonald 2002-06-02 09:05:11 +00:00
parent f10a1ecf5d
commit 13a53a8093
3 changed files with 143 additions and 40 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
ChangeLog
View file

@ -1,3 +1,13 @@
2002-06-02 Richard Frith-Macdonald <rfm@gnu.org>
* Headers/Foundation/NSObject.h: Removed ([_dealloc]),
([-deallocNotificationsActive]), ([setDeallocNotificationsActive:])
* Source/NSObject.m: Removed ([_dealloc]),
([-deallocNotificationsActive]), ([setDeallocNotificationsActive:])
as these methods are no longer necessary now that the dealloc method
itsself is able to refrain from performing deallocation if if wishes
(the retain count mechanism can no longer reach a zero retain count).
2002-06-01 Richard Frith-Macdonald <rfm@gnu.org>
* Source/NSObject.m: Change NSDecrementExtraRefCountWasZero() to

85
Headers/gnustep/base/NSObject.h
View file

@ -54,34 +54,54 @@
@class NSInvocation;
@class Protocol;
/**
* The NSObject protocol describes a minimal set of methods that all
* objects are expected to support. You should be able to send any
* of the messages listed in this protocol to an object, and be safe
* in assuming that the receiver can handle it.
*/
@protocol NSObject
- (Class) class;
- (Class) superclass;
- (BOOL) isEqual: anObject;
- (BOOL) isKindOfClass: (Class)aClass;
- (BOOL) isMemberOfClass: (Class)aClass;
- (BOOL) isProxy;
- (unsigned) hash;
- self;
- performSelector: (SEL)aSelector;
- performSelector: (SEL)aSelector withObject: anObject;
- performSelector: (SEL)aSelector withObject: object1 withObject: object2;
- (Class) class; /** See [NSObject-class] */
- (Class) superclass; /** See [NSObject-superclass] */
- (BOOL) isEqual: (id)anObject; /** See [NSObject-isEqual:] */
- (BOOL) isKindOfClass: (Class)aClass; /** See [NSObject-isKindOfClass:] */
- (BOOL) isMemberOfClass: (Class)aClass;/** See [NSObject-isMemberOfClass:] */
- (BOOL) isProxy; /** See [NSObject-isProxy] */
- (unsigned) hash; /** See [NSObject-hash] */
- (id) self; /** See [NSObject-self] */
- (id) performSelector: (SEL)aSelector; /** See [NSObject-performSelector:] */
/** See [NSObject-performSelector:withObject:] */
- (id) performSelector: (SEL)aSelector
withObject: (id)anObject;
/** See [NSObject-performSelector:withObject:withObject:] */
- (id) performSelector: (SEL)aSelector
withObject: (id)object1
withObject: (id)object2;
/** See [NSObject-respondsToSelector:] */
- (BOOL) respondsToSelector: (SEL)aSelector;
- (BOOL) conformsToProtocol: (Protocol *)aProtocol;
- retain;
- autorelease;
- (oneway void) release;
- (unsigned) retainCount;
- (NSZone*) zone;
- (NSString*) description;
/** See [NSObject-conformsToProtocol:] */
- (BOOL) conformsToProtocol: (Protocol*)aProtocol;
- (id) retain; /** See [NSObject-retain] */
- (id) autorelease /** See [NSObject-autorelease] */;
- (oneway void) release; /** See [NSObject-release] */
- (unsigned) retainCount; /** See [NSObject-retainCount] */
- (NSZone*) zone; /** See [NSObject-zone] */
- (NSString*) description; /** See [NSObject-description] */
@end
/**
* This protocol must be adopted by any class wishing to support copying.
*/
@protocol NSCopying
- (id) copyWithZone: (NSZone *)zone;
- (id) copyWithZone: (NSZone*)zone;
@end
/**
* This protocol must be adopted by any class wishing to support
* mutable copying.
*/
@protocol NSMutableCopying
- (id) mutableCopyWithZone: (NSZone *)zone;
- (id) mutableCopyWithZone: (NSZone*)zone;
@end
@protocol NSCoding
@ -187,24 +207,29 @@ GS_EXPORT BOOL
NSShouldRetainWithZone(NSObject *anObject, NSZone *requestedZone);
/**
* Return the extra reference count of anObject. The retain count
* Return the extra reference count of anObject (a value in the range
* from 0 to the maximum unsigned integer value minus one).<br />
* The retain count
* for an object is this value plus one.
*/
GS_EXPORT unsigned
NSExtraRefCount(id anObject);
/**
* Increment the extra reference count for anObject. This is used
* by the [NSObject-retain] method.
* Increments the extra reference count for anObject.
* The GNUstep version raises an exception if the reference count
* would be incremented to too large a value.
* This is used by the [NSObject-retain] method.
*/
GS_EXPORT void
NSIncrementExtraRefCount(id anObject);
/**
* Examines the extra reference count for the object and, if non-zero
* decrements it. Returns a flag to say whether the count was zero
* decrements it, otherwise leaves it unchanged.<br />
* Returns a flag to say whether the count was zero
* (and hence whether the extra refrence count was decremented).<br />
* This us used by the [NSObject-release] method.
* This function is used by the [NSObject-release] method.
*/
GS_EXPORT BOOL
NSDecrementExtraRefCountWasZero(id anObject);
@ -266,14 +291,14 @@ GS_EXPORT NSRecursiveLock *gnustep_global_lock;
indent: (unsigned)level
to: (id<GNUDescriptionDestination>)output;
- (Class) transmuteClassTo: (Class)aClassObject;
- subclassResponsibility: (SEL)aSel;
- shouldNotImplement: (SEL)aSel;
- (id) subclassResponsibility: (SEL)aSel;
- (id) shouldNotImplement: (SEL)aSel;
+ (Class) autoreleaseClass;
+ (void) setAutoreleaseClass: (Class)aClass;
+ (void) enableDoubleReleaseCheck: (BOOL)enable;
- read: (TypedStream*)aStream;
- write: (TypedStream*)aStream;
/*
- (id) read: (TypedStream*)aStream;
- (id) write: (TypedStream*)aStream;
/**
* If the 'deallocActivationsActive' flag is set, the _dealloc method will be
* called during the final release of an object, and the dealloc method will
* then be called only if _dealloc returns YES.

88
Source/NSObject.m
View file

@ -228,11 +228,22 @@ NSIncrementExtraRefCount(id anObject)
if (allocationLock != 0)
{
objc_mutex_lock(allocationLock);
if (((obj)anObject)[-1].retained == UINT_MAX - 1)
{
objc_mutex_unlock (allocationLock);
[NSException raise: NSInternalInconsistencyException
format: @"NSIncrementExtraRefCount() asked to increment too far"];
}
((obj)anObject)[-1].retained++;
objc_mutex_unlock (allocationLock);
}
else
{
if (((obj)anObject)[-1].retained == UINT_MAX - 1)
{
[NSException raise: NSInternalInconsistencyException
format: @"NSIncrementExtraRefCount() asked to increment too far"];
}
((obj)anObject)[-1].retained++;
}
}
@ -241,11 +252,22 @@ NSIncrementExtraRefCount(id anObject)
if (allocationLock != 0) \
{ \
objc_mutex_lock(allocationLock); \
if (((obj)X)[-1].retained == UINT_MAX - 1) \
{ \
objc_mutex_unlock (allocationLock); \
[NSException raise: NSInternalInconsistencyException \
format: @"NSIncrementExtraRefCount() asked to increment too far"]; \
} \
((obj)(X))[-1].retained++; \
objc_mutex_unlock(allocationLock); \
} \
else \
{ \
if (((obj)X)[-1].retained == UINT_MAX - 1) \
{ \
[NSException raise: NSInternalInconsistencyException \
format: @"NSIncrementExtraRefCount() asked to increment too far"]; \
} \
((obj)X)[-1].retained++; \
} \
})
@ -313,6 +335,13 @@ NSIncrementExtraRefCount (id anObject)
node = GSIMapNodeForKey(&retain_counts, (GSIMapKey)anObject);
if (node != 0)
{
if ((node->value.uint) == UINT_MAX - 1)
{
objc_mutex_unlock(allocationLock);
[NSException raise: NSInternalInconsistencyException
format:
@"NSIncrementExtraRefCount() asked to increment too far"];
}
(node->value.uint)++;
}
else
@ -326,6 +355,12 @@ NSIncrementExtraRefCount (id anObject)
node = GSIMapNodeForKey(&retain_counts, (GSIMapKey)anObject);
if (node != 0)
{
if ((node->value.uint) == UINT_MAX - 1)
{
[NSException raise: NSInternalInconsistencyException
format:
@"NSIncrementExtraRefCount() asked to increment too far"];
}
(node->value.uint)++;
}
else
@ -413,7 +448,7 @@ NSExtraRefCount (id anObject)
ret = node->value.uint;
}
}
return ret; /* ExtraRefCount + 1 */
return ret;
}
#endif /* defined(REFCNT_LOCAL) */
@ -681,6 +716,7 @@ static BOOL double_release_check_enabled = NO;
@implementation NSObject
+ (void) _becomeMultiThreaded: (NSNotification)aNotification
@ -1113,7 +1149,9 @@ static BOOL double_release_check_enabled = NO;
/**
* Adds the receiver to the current autorelease pool, so that it will be
* sent a -release message when the pool is destroyed.<br />
* Returns the receiver.
* Returns the receiver.<br />
* In GNUstep, the [NSObject+enableDoubleReleaseCheck:] method may be used
* to turn on checking for ratain/release errors in this method.
*/
- (id) autorelease
{
@ -1152,7 +1190,12 @@ static BOOL double_release_check_enabled = NO;
}
/**
* returns the class of which the receiver is an instance.
* Returns the class of which the receiver is an instance.<br />
* The default implementation returns the private <code>isa</code>
* instance variable of NSObject, which is used to store a pointer
* to the objects class.<br />
* NB. When NSZombie is enabled (see NSDebug.h) this pointer is
* changed upon object deallocation.
*/
- (Class) class
{
@ -1314,9 +1357,18 @@ static BOOL double_release_check_enabled = NO;
}
/**
* Calls the NSDecrementExtraRefCountWasZero() function to test the
* extra reference count for the receiver (and decrement it if non-zero).<br />
* If it was zero, calls the -dealloc method to destroy the receiver.<br />
* Decrements the retain count for the receiver unless it is 1, in which
* case the dealloc method is called instead.<br />
* The default implementation calls the NSDecrementExtraRefCountWasZero()
* function to test the extra reference count for the receiver (and
* decrement it if non-zero) - if the extra reference count is zero then
* the retain count is one, and the dealloc method is called.<br />
* In GNUstep, the [NSObject+enableDoubleReleaseCheck:] method may be used
* to turn on checking for ratain/release errors in this method.<br />
* GNUstep also supports deallocation notifications ... if this feature is
* turned on (See [NSObject-setDeallocNotificationsActive:]) then the
* [NSObject-_dealloc] method is called to notify the objct that it is
* about to be deallocated.
*/
- (oneway void) release
{
@ -1365,8 +1417,8 @@ static BOOL double_release_check_enabled = NO;
}
/**
* Increments the reference count for the receiver by calling
* NSIncrementExtraRefCount()
* Increments the reference count and returns the receiver.<br />
* The default implementation does this by calling NSIncrementExtraRefCount()
*/
- (id) retain
{
@ -1390,7 +1442,10 @@ static BOOL double_release_check_enabled = NO;
/**
* Returns the reference count for the receiver. Each instance has an
* implicit reference count of 1, and has an 'extra refrence count'
* returned by the NSExtraRefCount() function.
* returned by the NSExtraRefCount() function, so the value returned by
* this method is always greater than zero.<br />
* By convention, objects which should (or can) never be deallocated
* return the maximum unsigned integer value.
*/
- (unsigned) retainCount
{
@ -1617,10 +1672,23 @@ static BOOL double_release_check_enabled = NO;
/**
* Enables runtime checking of retain/release/autorelease operations.<br />
* Whenever either -autorelease or -release is called, the contents of any
* <p>Whenever either -autorelease or -release is called, the contents of any
* autorelease pools will be checked to see if there are more outstanding
* release operations than the objects retain count. In which case an
* exception is raised to say that the object is released too many times.
* </p>
* <p><strong>Beware</strong>, since this feature entails examining all active
* autorelease pools every time an object is released or autoreleased, it
* can cause a massive performance degradation ... it should only be enabled
* for debugging.
* </p>
* <p>
* Where you are having memory allocation problems, it may make more sense
* to look at the memory allocation debugging functions documnented in
* look at the memory allocation debugging functions documnented in
* NSDebug.h, or use the NSZombie features.NSDebug.h, or use the NSZombie
* features.
* </p>
*/
+ (void) enableDoubleReleaseCheck: (BOOL)enable
{