objc.h: Updated comments.

2010-10-11  Nicola Pero  <nicola.pero@meta-innovation.com>

        * objc/objc.h: Updated comments.
        * objc/objc-api.h: (object_copy): Added one argument; use a
        #define to maintain backwards-compatibility.  Moved
        _objc_object_alloc, _objc_object_copy, _objc_object_dispose and
        objc_get_uninstalled_dtable into
        objc/deprecated/objc_get_uninstalled_dtable.h and
        objc/deprecated/objc_object_alloc.h.  Include these files.
        * objc/deprecated/objc_get_uninstalled_dtable.h: New.
        * objc/deprecated/objc_object_alloc.h: New.
        * objc/runtime.h (set_getName): New.
        (sel_getType): New.
        (sel_getUid): New.
        (sel_registerName): New.
        (sel_registerTypedName): New.
        (sel_isEqual): New.
        (class_createInstance): New.
        (object_copy): New.
        (object_dispose): New.
        * objects.c: Do not include tconfig.h.  Include gc_typed.h if
        building the garbage collection version.
        (__objc_object_alloc): Removed.
        (__objc_object_copy): Removed.
        (__objc_object_dispose): Removed.
        (class_createInstance): New from code in class_create_instance.
        Cast second argument of GC_malloc_explicitly_typed.  Use
        objc_calloc.  Do not call _objc_object_alloc.
        (class_create_instance): Call class_createInstance.
        (object_copy): Added extraBytes argument.  Do not call
        _objc_object_copy.
        (object_dispose): Do not call _objc_object_dispose.
        * memory.c (objc_free): When using garbage collection, mark the
        argument as unused.
        * selector.c (sel_getName): New.
        (sel_get_name): Call sel_getName.
        (sel_getType): New.
        (sel_get_type): Call sel_getType.
        (sel_registerName): New.
        (sel_register_name): Call sel_registerName.
        (sel_registerTypedName): New.
        (sel_register_typed_name): Call sel_registerTypedName.
        (sel_getUid): New.
        (sel_get_uid): Call sel_getUid.

From-SVN: r165264

1 files changed, 63 insertions, 1 deletions

diff --git a/libobjc/objc/runtime.h b/libobjc/objc/runtime.h
index 6f25ec8..73c05d9 100644
--- a/libobjc/objc/runtime.h
+++ b/libobjc/objc/runtime.h
@@ -145,7 +145,67 @@ struct objc_method_description
 #define _F_ONEWAY	0x10
 #define _F_GCINVISIBLE	0x20
 
-/* TODO: Add all the functions in the API.  */
+
+/** Internals: the following functions are in selector.c.  */
+
+/* Return the name of a given selector.  */
+objc_EXPORT const char *sel_getName (SEL selector);
+
+/* Return the type of a given selector.
+
+   Compatibility Note: the Apple/NeXT runtime has untyped selectors,
+   so it does not have this function, which is specific to the GNU
+   Runtime.  */
+objc_EXPORT const char *sel_getType (SEL selector);
+
+/* This is the same as sel_registerName ().  Please use
+   sel_registerName () instead.  */
+objc_EXPORT SEL sel_getUid (const char *name);
+
+/* Register a selector with a given name (but unspecified types).  If
+   you know the types, it is better to call sel_registerTypedName().
+   If a selector with this name already exists, it is returned.  */
+objc_EXPORT SEL sel_registerName (const char *name);
+
+/* Register a selector with a given name and types.  If a selector
+   with this name and types already exists, it is returned.
+
+   Compatibility Note: the Apple/NeXT runtime has untyped selectors,
+   so it does not have this function, which is specific to the GNU
+   Runtime.  */
+objc_EXPORT SEL set_registerTypedName (const char *name, const char *type);
+
+/* Return YES if first_selector is the same as second_selector, and NO
+   if not.  */
+objc_EXPORT BOOL sel_isEqual (SEL first_selector, SEL second_selector);
+
+
+/** Internals: the following functions are in objects.c.  */
+
+/* Create an instance of class 'class', adding extraBytes to the size
+   of the returned object.  This method allocates the appropriate
+   amount of memory for the instance, initializes it to zero, then
+   calls all the C++ constructors on appropriate C++ instance
+   variables of the instance (if any) (TODO: This is not implemented
+   yet).  */
+objc_EXPORT id class_createInstance (Class class, size_t extraBytes);
+
+/* Copy an object and return the copy.  extraBytes should be identical
+   to the extraBytes parameter that was passed when creating the
+   original object.  */
+objc_EXPORT id object_copy (id object, size_t extraBytes);
+
+/* Dispose of an object.  This method calls the appropriate C++
+   destructors on appropriate C++ instance variables of the instance
+   (if any) (TODO: This is not implemented yet), then frees the memory
+   for the instance.  */
+objc_EXPORT id object_dispose (id object);
+
+
+/* TODO: Add all the other functions in the API.  */
+
+
+/** Internals: the following functions are in objc-foreach.c.  */
 
 /* 'objc_enumerationMutation()' is called when a collection is
    mutated while being "fast enumerated".  That is a hard error, and
@@ -199,6 +259,8 @@ struct __objcFastEnumerationState
 */
 
 
+/** Internals: the following functions are implemented in encoding.c.  */
+
 /* Traditional GNU Objective-C Runtime functions that are currently
    used to implement method forwarding.
 */