libobjc: header cleanup for new API (11)

libobjc: header cleanup for new API (11)

[Nicola Pero]

This patch just updates comments in objc/message.h and objc/runtime.h.

I have gone through all the functions declared by the Apple/NeXT runtime
in objc/runtime.h, and they are all either declared in our own objc/runtime.h
(and implemented) or a "Compatibility Note" comment has been added explaining
why the GNU runtime doesn't have them.  We're fairly good! :-)

Committed.

Thanks

Index: ChangeLog
===================================================================
--- ChangeLog   (revision 168059)
+++ ChangeLog   (working copy)
@@ -1,5 +1,10 @@
 2010-12-19  Nicola Pero  <nicola.pero@meta-innovation.com>
 
+       * objc/message.h: Updated comments.
+       * objc/runtime.h: Updated comments.
+
+2010-12-19  Nicola Pero  <nicola.pero@meta-innovation.com>
+
        * class.c (objc_lookupClass): Renamed to objc_lookUpClass.
        * protocols.c: Updated all calls to objc_lookupClass to call
        objc_lookUpClass instead.
Index: objc/runtime.h
===================================================================
--- objc/runtime.h      (revision 168059)
+++ objc/runtime.h      (working copy)
@@ -45,8 +45,6 @@
 # error You can not include both objc/objc-api.h and objc/runtime.h.  Include objc/objc-api.h for the traditional GNU Objective-C Runtime API and objc/runtime.h for the modern one.
 #endif
 
-/* TODO: This file is incomplete.  */
-
 #include "objc.h"
 #include "objc-decls.h"
 
@@ -875,8 +873,6 @@
 objc_EXPORT Protocol **protocol_copyProtocolList (Protocol *protocol, unsigned int *numberOfReturnedProtocols);
 
 
-/* TODO: Add all the other functions in the API.  */
-
 /** Implementation: the following hook is in init.c.  */
 
 /* This is a hook which is called by __objc_exec_class every time a
@@ -937,6 +933,25 @@
 */
 
 
+/* Compatibility Note: The Apple/NeXT runtime has the functions
+   objc_copyImageNames (), class_getImageName () and
+   objc_copyClassNamesForImage () but they are undocumented.  The GNU
+   runtime does not have them at the moment.  */
+
+/* Compatibility Note: The Apple/NeXT runtime has the functions
+   objc_setAssociatedObject (), objc_getAssociatedObject (),
+   objc_removeAssociatedObjects () and the objc_AssociationPolicy type
+   and related enum.  The GNU runtime does not have them yet.
+   TODO: Implement them.  */
+
+/* Compatibility Note: The Apple/NeXT runtime has the function
+   objc_setForwardHandler ().  The GNU runtime does not have it
+   because messaging (and, in particular, forwarding) works in a
+   different (incompatible) way with the GNU runtime.  If you need to
+   customize message forwarding at the Objective-C runtime level (that
+   is, if you are implementing your own "Foundation" library such as
+   GNUstep Base on top of the Objective-C runtime), in objc/message.h
+   there are hooks (that work in the framework of the GNU runtime) to
+   do so.  */
+
+
 /** Implementation: the following functions are in memory.c.  */
 
 /* Traditional GNU Objective-C Runtime functions that are used for
@@ -964,6 +979,12 @@
 
 /** Implementation: the following functions are in gc.c.  */
 
+/* The GNU Objective-C Runtime has a different implementation of
+   garbage collection.
+
+   Compatibility Note: these functions are not available with the
+   Apple/NeXT runtime.  */
+
 /* Mark the instance variable as inaccessible to the garbage
    collector.  */
 objc_EXPORT void class_ivar_set_gcinvisible (Class _class,
Index: objc/message.h
===================================================================
--- objc/message.h      (revision 168058)
+++ objc/message.h      (working copy)
@@ -130,10 +130,7 @@
    built-in forwarding with one based on a library, such as ffi, that
    implement closures, thereby avoiding gcc's __builtin_apply
    problems.  __objc_msg_forward2's result will be preferred over that
-   of __objc_msg_forward if both are set and return non-NULL.
-
-   TODO: The API should define objc_set_msg_forward_handler () or
-   similar instead of these hooks.  */
+   of __objc_msg_forward if both are set and return non-NULL.  */   
 objc_EXPORT IMP (*__objc_msg_forward)(SEL);
 objc_EXPORT IMP (*__objc_msg_forward2)(id, SEL);

Re: libobjc: header cleanup for new API (11)

[Mike Stump]

On Dec 19, 2010, at 8:06 AM, "Nicola Pero" <nicola.pero@meta-innovation.com> wrote:
> This patch just updates comments in objc/message.h and objc/runtime.h.

I think at some point, it would be nice to have a document for this all, but I don't like the current situation wrt documentation, so I hate to even suggest it.  :-(.  An abi reference generated from source might work.
> 

Re: libobjc: header cleanup for new API (11)

[Nicola Pero]

>> This patch just updates comments in objc/message.h and objc/runtime.h.
>
> I think at some point, it would be nice to have a document for this all,
> but I don't like the current situation wrt documentation, so I hate to
> even suggest it.  :-(.  An abi reference generated from source might work.

Yes.  Suggestions are welcome.

At this stage, the (Modern) GNU Objective-C Runtime API is documented in the header
files; objc/objc.h, objc/runtime.h and objc/message.h.  I like writing documentation
and I documented quite a lot - each function, type, etc. :-)

I added a section in the GCC manual about what the headers are and an explanation that
the API is documented in the headers.  It would be better to have the function/API reference
in the manual itself, but we'd need to sort out how to generate documentation for the manual
from the headers (I wouldn't want to move the reference documentation too far away
from the code otherwise they tend to get out of sync). ;-)

-

The ABI instead is not really documented anywhere; for GCC 4.7 I'd like to have an ABI
document that documents the GNU Objective-C Runtime ABI, at least the "Modern"
one, ie, the new ABI that I'd like to work on in 4.7 (assuming I get the time
to do it).  (by "Objective-C ABI" I mean a description of how the various
Objective-C constructs are compiled, and a description of the module structure
that is passed by the compiler to the runtime for each compilation unit).

I don't expect the ABI document to be very long, probably 5 to 10 pages,
so it may fit well in the GCC manual itself, but other suggestions are welcome.

Thanks

Re: libobjc: header cleanup for new API (11)

[Mike Stump]

On Dec 19, 2010, at 9:18 AM, "Nicola Pero" <nicola.pero@meta-innovation.com> wrote:
> The ABI instead

Sorry, I did mean API...