libobjc: updated comments in objc/message.h

libobjc: updated comments in objc/message.h

[Nicola Pero]

[-- Attachment #1: Type: text/plain, Size: 360 bytes --]

This patch contains no code changes, only indentations and lots of work on comments.

Committed to trunk.

Thanks

In libobjc/:
2010-12-15  Nicola Pero  <nicola.pero@meta-innovation.com>

        * objc/message.h: Update comments, reindented code and moved
        deprecated types and functions at the end of the file.  No code
        changes.


[-- Attachment #2: patch.txt --]
[-- Type: text/plain, Size: 6887 bytes --]

Index: ChangeLog
===================================================================
--- ChangeLog	(revision 167858)
+++ ChangeLog	(working copy)
@@ -1,5 +1,11 @@
 2010-12-15  Nicola Pero  <nicola.pero@meta-innovation.com>
 
+	* objc/message.h: Update comments, reindented code and moved
+	deprecated types and functions at the end of the file.  No code
+	changes.
+
+2010-12-15  Nicola Pero  <nicola.pero@meta-innovation.com>
+
 	* ivars.c (class_addIvar): Use the 'size' argument instead of
 	trying to calculate it using objc_sizeof_type().
 	* objc/runtime.h (class_addIvar): Updated comments.
Index: objc/message.h
===================================================================
--- objc/message.h	(revision 167858)
+++ objc/message.h	(working copy)
@@ -34,57 +34,108 @@ extern "C" {
 #endif
 
 /* This file includes declarations of the messaging functions and
-   types.
-*/
+   types.  */
 
 /* Compatibility note: the messaging function is one area where the
    GNU runtime and the Apple/NeXT runtime differ significantly.  If
    you can, it is recommended that you use higher-level facilities
    (provided by a Foundation library such as GNUstep Base) to perform
-   forwarding or other advanced messaging tricks.
-*/
+   forwarding or other advanced messaging tricks.  */
 
-typedef void* retval_t;		/* return value */
-typedef void(*apply_t)(void);	/* function pointer */
-typedef union arglist {
-  char *arg_ptr;
-  char arg_regs[sizeof (char*)];
-} *arglist_t;			/* argument frame */
+/* This function returns the IMP (C function implementing a method) to
+   use to invoke the method with selector 'op' of receiver 'receiver'.
 
-objc_EXPORT IMP objc_msg_lookup(id receiver, SEL op);
+   This is the function used by the compiler when compiling method
+   invocations with the GNU runtime.  For example, the method call
 
-/*
- * Structure used when a message is send to a class's super class.
- * The compiler generates one of these structures and passes it to
- * objc_msg_lookup_super.
- */
-typedef struct objc_super {
-  id      self;       /* Id of the object sending the message. */
+     result = [receiver method];
+
+   is compiled by the compiler (with the GNU runtime) into the
+   equivalent of:
+
+   {
+     IMP function = objc_msg_lookup (receiver, @selector (method));
+     result = function (receiver, @selector (method));
+   }
+
+   so, a call to objc_msg_lookup() determines the IMP (the C function
+   implementing the method) to call.  Then, the function is called.
+   If the method takes or returns different arguments, the compiler
+   will cast 'function' to the right type before invoking it, making
+   sure arguments and return value are handled correctly.
+
+   objc_msg_lookup() must always return a valid function that can be
+   called with the required method signature (otherwise the
+   compiler-generated code shown above could segfault).  If 'receiver'
+   is NULL, objc_msg_lookup() returns a C function that does nothing,
+   ignores all its arguments, and returns NULL (see nil_method.c).  If
+   'receiver' does not respond to the selector 'op', objc_msg_lookup()
+   will try to call +resolveClassMethod: or resolveInstanceMethod: as
+   appropriate, and if they return YES, it will try the lookup again
+   (+resolveClassMethod: and +resolveInstanceMethod: can thus install
+   dynamically methods as they are requested).  If
+   +resolveClassMethod: or +resolveInstanceMethod: are either not
+   available, or return NO, or return YES but 'receiver' still doesn't
+   implement the 'selector' after calling them, the runtime returns a
+   generic "forwarding" function that can be called with the required
+   method signature and which can process the method invocation
+   according to the forwarding API.  There are two runtime hooks that
+   allow Foundation libraries (such as GNUstep-Base) to return their
+   own forwarding function in preference to the runtime ones.  When
+   that happens, the Foundation library effectively takes complete
+   control of the forwarding process; any method invocation where the
+   selector is not implemented by the receiver will end up calling a
+   forwarding function chosen by the Foundation library.  */
+objc_EXPORT IMP objc_msg_lookup (id receiver, SEL op);
+
+/* Structure used when a message is send to a class's super class.
+   The compiler generates one of these structures and passes it to
+   objc_msg_lookup_super() when a [super method] call is compiled.  */
+typedef struct objc_super
+{
+  id    self;       /* Id of the object sending the message. */
+
+  /* The new version of the API will always use 'super_class'.  TODO:
+     Use class only if objc-api.h is included, otherwise always use
+     super_class.  */
 #ifdef __cplusplus
-  /* The new version of the API will always use 'super_class'.  */
   Class super_class;
 #else
   Class class;        /* Object's super class. */
 #endif
 } Super, *Super_t;
 
-objc_EXPORT IMP objc_msg_lookup_super(Super_t super, SEL sel);
-
-objc_EXPORT retval_t objc_msg_sendv(id, SEL, arglist_t);
+/* This is used by the compiler instead of objc_msg_lookup () when
+   compiling a call to 'super', such as [super method].  This requires
+   sending a message to super->self, but looking up the method as if
+   super->self was in class super->super_class.  */
+objc_EXPORT IMP objc_msg_lookup_super (Super_t super, SEL sel);
+
+/* Hooks for method forwarding.  They make it easy to substitute the
+   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.
 
-/*
- * Hooks for method forwarding. This makes it easy to substitute a
- * library, such as ffcall, that implements 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.
- */
+   TODO: The API should define objc_set_msg_forward_handler () or
+   similar instead of these hooks.  */
 objc_EXPORT IMP (*__objc_msg_forward)(SEL);
 objc_EXPORT IMP (*__objc_msg_forward2)(id, SEL);
 
+
+/* The following types and functions are provided only for
+   backwards-compatibility and should not be used in new code.  They
+   were deprecated in GCC 4.6 and will be removed in the next
+   release.  */
+typedef void* retval_t;		/* return value */
+typedef void(*apply_t)(void);	/* function pointer */
+typedef union arglist {
+  char *arg_ptr;
+  char arg_regs[sizeof (char*)];
+} *arglist_t;		        /* argument frame */
+
+objc_EXPORT retval_t objc_msg_sendv(id, SEL, arglist_t);
+
 #ifdef __cplusplus
 }
 #endif