ObjFW  Check-in [146db53e4a]

/*
 * Copyright (c) 2008 - 2009
 *   Jonathan Schleifer <js@webkeks.org>
 *
 * All rights reserved.
 *
 * This file is part of libobjfw. It may be distributed under the terms of the
 * Q Public License 1.0, which can be found in the file LICENSE included in
 * the packaging of this file.
 */

#import "OFObject.h"

/**
 * A struct that contains a pointer to the next list object, the previous list
 * object and the object.
 */
typedef struct __of_list_object
{
	/// A pointer to the next list object in the list
	struct __of_list_object *next;
	/// A pointer to the previous list object in the list
	struct __of_list_object *prev;
	/// The object for the list object
	id			object;
} of_list_object_t;

/**
 * The OFList class provides easy to use double-linked lists.
 */
@interface OFList: OFObject <OFCopying>

 *
 * \param listobj_size The size of a list object
 * \return An initialized OFList with the specified list object size
 */
- initWithListObjectSize: (size_t)listobj_size;

/**
 * Initializes an already allocated OFList that does not retain/releas objects
 * added to it..
 * Initializes an already allocated OFList that does not retain/release objects
 * added to it.
 *
 * \return An initialized OFList
 */
- initWithoutRetainAndRelease;

/**
 * \return The first object in the list
 * \return The first list object in the list
 */
- (of_list_object_t*)first;

/**
 * \return The last object in the list
 * \return The last list object in the list
 */
- (of_list_object_t*)last;

/**
 * Appends an object to the list.
 *
 * \param obj The object to append

 *	   For example, if you want to remove an object from the list, you need
 *	   its of_list_object_t.
 */
- (of_list_object_t*)insert: (id)obj
		      after: (of_list_object_t*)listobj;

/**
 * Removes an object from the list.
 * Removes the object with the specified list object from the list.
 *
 * \param listobj The list object returned by append / prepend
 */
- remove: (of_list_object_t*)listobj;

/**
 * Get the number of items in the list. Use with caution, as this means one
 * iteration through the whole list!
 *
 * \return The number of items in the list.
 */
- (size_t)count;
@end

#endif

/**
 * The OFObject class is the base class for all other classes inside ObjFW.
 */
@interface OFObject
{
	/// The class of the object
	Class  isa;
	Class isa;
}

/**
 * This code is executed once when a method of the class is called for the first
 * time.
 *
 * Derived classes can override this to execute their own code on
 * initialization.
 */
+ (void)initialize;

/**
 * Allocates memory for an instance of the class.
 * Allocates memory for an instance of the class and sets up the memory pool for
 * the object.
 *
 * alloc will never return nil, instead, it will throw an
 * OFAllocFailedException.
 *
 * \return The allocated object.
 */
+ alloc;

/**
 * \return The class pointer
 * \return The class
 */
+ (Class)class;

/**
 * \return The name of the class as a C string
 */
+ (const char*)className;

/**
 * \param selector The selector which should be checked for respondance
 * Checks whether instances of the class respond to a given selector.
 *
 * \param selector The selector which should be checked for respondance
 * \return A boolean whether instances of the class respond to the specified
 *	   selector
 */
+ (BOOL)instancesRespondToSelector: (SEL)selector;

/**
 * \param protocol The protocol which should be checked for conformance
 * Checks whether the class conforms to a given protocol.
 *
 * \param protocol The protocol which should be checked for conformance
 * \return A boolean whether the class conforms to the specified protocol
 */
+ (BOOL)conformsToProtocol: (Protocol*)protocol;

/**
 * \param selector The selector for which the method should be returned
 *
 * \return The implementation of the instance method for the specified selector
 *	   or nil if it isn't implemented
 */
+ (IMP)instanceMethodForSelector: (SEL)selector;

/**
 * Replace a method implementation with another implementation.
 * Replaces a method implementation with another implementation.
 *
 * \param selector The selector of the method to replace
 * \param imp The new implementation for the method
 * \return The old implementation
 */
+ (IMP)setImplementation: (IMP)newimp
	       forMethod: (SEL)selector;

/**
 * Replace a method with a method from another class.
 * Replaces a method with a method from another class.
 *
 * \param selector The selector of the method to replace
 * \param class The class from which the new method should be taken
 * \return The old implementation
 */
+  (IMP)replaceMethod: (SEL)selector
  withMethodFromClass: (Class)class;

/**
 * Initialize the already allocated object.
 * Initializes an already allocated object.
 * Also sets up the memory pool for the object.
 *
 * Derived classes may override this, but need to do self = [super init] before
 * they do any initialization themselves. init may never return nil, instead
 * an exception (for example OFInitializationFailed) should be thrown.
 *
 * \return An initialized object
 */
- init;

/**
 * \return A pointer to the class of the instance
 * \return The class of the object
 */
- (Class)class;

/**
 * \return The name of the instance's class as a C string
 * \return The name of the object's class as a C string
 */
- (const char*)className;

/**
 * \param class The class whose kind is checked
 *
 * \return A boolean whether the object is of the specified kind
 */
- (BOOL)isKindOfClass: (Class)class;

/**
 * \param selector The selector which should be checked for respondance
 *
 * \return A boolean whether the objects responds to the specified selector
 */
- (BOOL)respondsToSelector: (SEL)selector;

/**
 * \param protocol The protocol which should be checked for conformance
 *
 * \return A boolean whether the objects conforms to the specified protocol
 */
- (BOOL)conformsToProtocol: (Protocol*)protocol;

/**
 * \param selector The selector for which the method should be returned
 *
 * \return The implementation for the specified selector
 */
- (IMP)methodForSelector: (SEL)selector;

/**
 * Compare two objects.
 * Checks two objects for equality.
 *
 * Classes containing data (like strings, arrays, lists etc.) should reimplement
 * this!
 *
 * \param obj The object which is tested for equality
 * \return A boolean whether the object is equal to the other object
 * \param obj The object which should be tested for equality
 * \return A boolean whether the object is equal to the specified object
 */
- (BOOL)isEqual: (id)obj;

/**
 * Calculate a hash for the object.
 * Calculates a hash for the object.
 *
 * Classes containing data (like strings, arrays, lists etc.) should reimplement
 * this!
 *
 * \return A 32 bit hash for the object
 */
- (uint32_t)hash;

/**
 * Adds a pointer to the memory pool.
 * Adds a pointer to the object's memory pool.
 *
 * This is useful to add memory allocated by functions such as asprintf to the
 * pool so it gets free'd automatically when the object is deallocated.
 *
 * \param ptr A pointer to add to the memory pool
 */
- addMemoryToPool: (void*)ptr;

/**
 * Allocate memory and store it in the objects memory pool so it can be free'd
 * automatically when the object is deallocated.
 * Allocates memory and stores it in the object's memory pool so it can be
 * free'd automatically when the object is deallocated.
 *
 * \param size The size of the memory to allocate
 * \return A pointer to the allocated memory
 */
- (void*)allocMemoryWithSize: (size_t)size;

/**
 * Allocate memory for a specified number of items and store it in the objects
 * memory pool so it can be free'd automatically when the object is deallocated.
 * Allocates memory for the specified number of items and stores it in the
 * object's memory pool so it can be free'd automatically when the object is
 * deallocated.
 *
 * \param nitems The number of items to allocate
 * \param size The size of each item to allocate
 * \return A pointer to the allocated memory
 */
- (void*)allocMemoryForNItems: (size_t)nitems
		     withSize: (size_t)size;

/**
 * Resize memory in the memory pool to a specified size.
 * Resizes memory in the object's memory pool to the specified size.
 *
 * \param ptr A pointer to the already allocated memory
 * \param size The new size for the memory chunk
 * \return A pointer to the resized memory chunk
 */
- (void*)resizeMemory: (void*)ptr
	       toSize: (size_t)size;

/**
 * Resize memory in the memory pool to a specific number of items of a
 * specified size.
 * Resizes memory in the object's memory pool to the specific number of items of
 * the specified size.
 *
 * \param ptr A pointer to the already allocated memory
 * \param nitems The number of items to resize to
 * \param size The size of each item to resize to
 * \return A pointer to the resized memory chunk
 */
- (void*)resizeMemory: (void*)ptr
	     toNItems: (size_t)nitems
	     withSize: (size_t)size;

/**
 * Frees allocated memory and removes it from the memory pool.
 * Frees allocated memory and removes it from the object's memory pool.
 *
 * \param ptr A pointer to the allocated memory
 */
- freeMemory: (void*)ptr;

/**
 * Increases the retain count.
 *
 * Each time an object is released, the retain count gets decreased and the
 * object deallocated if it reaches 0.
 */
- retain;

/**
 * Adds the object to the autorelease pool that is on top of the thread's stack.
 */
- autorelease;

/**
 * \return The retain count
 */
- (size_t)retainCount;

/**
 * Decreases the retain cound and deallocates the object if it reaches 0.
 * Decreases the retain count.
 *
 * Each time an object is released, the retain count gets decreased and the
 * object deallocated if it reaches 0.
 */
- (void)release;

/**
 * Adds the object to the topmost OFAutoreleasePool of the thread's release pool
 * stack.
 */
- autorelease;

/**
 * Deallocates the object and also frees all memory allocated via its memory
 * Deallocates the object and also frees all memory in its memory pool.
 * pool.
 *
 * It is also called when the retain count reaches zero.
 */
- (void)dealloc;

/*
 * Those are needed as the root class is the superclass of the root class's
 * metaclass and thus instance methods can be sent to class objects as well.
 */

- retain
{
	PRE_IVAR->retain_count++;

	return self;
}

- autorelease
{
	[OFAutoreleasePool addObjectToTopmostPool: self];

	return self;
}

- (size_t)retainCount
{
	return PRE_IVAR->retain_count;
}

- (void)release
{
	if (!--PRE_IVAR->retain_count)
		[self dealloc];
}

- autorelease
{
	[OFAutoreleasePool addObjectToTopmostPool: self];

	return self;
}

- (void)dealloc
{
	void **iter = PRE_IVAR->memchunks + PRE_IVAR->memchunks_size;

	while (iter-- > PRE_IVAR->memchunks)
		free(*iter);