In libobjc:

        * objc/deprecated/struct_objc_selector.h: New file.  Definition of
        'struct objc_selector' and 'sel_eq' moved here.
        * objc/deprecated/struct_objc_protocol.h: New file.  Definition of
        'struct objc_procotol' moved here.
        * objc/deprecated/struct_objc_class.h: New file.  Definition of
        'struct objc_class' moved here.
        * objc/deprecated/MetaClass.h: New file.  Definition of MetClass
        moved here.
        * objc/deprecated/STR.h: New file.  Definition of STR moved here.       
        * objc/message.h: New file.  Definitions for relval_t, apply_t,
        arglist, arglist_t and objc_msg_lookup were moved here.
        * objc/objc.h: Include the above files instead of defining the
        corresponding structs, types and functions here.  Added new opaque
        definitions for SEL and Class.  Use Class and not 'struct
        objc_class *' in the definition of 'struct objc_object'.
        Commented all types defined in the file.  Removed special
        definition of BOOL as 'int' on __vxworks; use 'unsigned char'
        there as well.
        * objc/deprecated/objc-unexpected-exception.h: Renamed to
        objc_unexpected_exception.h.
        * objc/objc-api.h: Updated include of
        objc-unexpetected-exception.h
        * objc/objc-exception.h: Updated comments.
        * Makefile.in (OBJC_H, OBJC_DEPRECATED_H): Added the new header
        files.  Reindented list of files.


git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@164212 138bc75d-0d04-0410-961f-82ee72b054a4

1 files changed, 101 insertions, 102 deletions

diff --git a/libobjc/objc/objc.h b/libobjc/objc/objc.h
index 08f977dbf1c..17ae49b1747 100644
--- a/libobjc/objc/objc.h
+++ b/libobjc/objc/objc.h
@@ -1,5 +1,6 @@
 /* Basic data types for Objective C.
-   Copyright (C) 1993, 1995, 1996, 2004, 2009 Free Software Foundation, Inc.
+   Copyright (C) 1993, 1995, 1996, 2004, 2009, 
+   2010 Free Software Foundation, Inc.
 
 This file is part of GCC.
 
@@ -22,7 +23,6 @@ a copy of the GCC Runtime Library Exception along with this program;
 see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
 <http://www.gnu.org/licenses/>.  */
 
-
 #ifndef __objc_INCLUDE_GNU
 #define __objc_INCLUDE_GNU
 
@@ -33,130 +33,129 @@ extern "C" {
 #include <stddef.h>
 
 /*
-** Definition of the boolean type.  
+  Definition of the boolean type.
+
+  Compatibility note: the Apple/NeXT runtime defines a BOOL as a
+  'signed char'.  The GNU runtime uses an 'unsigned char'.
+
+  Important: this could change and we could switch to 'typedef bool
+  BOOL' in the future.  Do not depend on the type of BOOL.
 */
-#ifdef __vxworks
-typedef int BOOL;
-#else
 #undef BOOL
 typedef unsigned char  BOOL;
-#endif
+
 #define YES   (BOOL)1
 #define NO    (BOOL)0
 
-/*
-** Definition of a selector.  Selectors themselves are not unique, but
-** the sel_id is a unique identifier.
+/* The basic Objective-C types (SEL, Class, id) are defined as pointer
+   to opaque structures.  The details of the structures are private to
+   the runtime and may potentially change from one version to the
+   other.
 */
-typedef const struct objc_selector 
-{
-  void *sel_id;
-  const char *sel_types;
-} *SEL;
-
-inline static BOOL
-sel_eq (SEL s1, SEL s2)
-{
-  if (s1 == 0 || s2 == 0)
-    return s1 == s2;
-  else
-    return s1->sel_id == s2->sel_id;
-}
-
 
-/*
-** ObjC uses this typedef for untyped instances.
+/* A SEL (selector) represents an abstract method (in the
+   object-oriented sense) and includes all the details of how to
+   invoke the method (which means its name, arguments and return
+   types) but provides no implementation of its own.  You can check
+   whether a class implements a selector or not, and if you have a
+   selector and know that the class implements it, you can use it to
+   call the method for an object in the class.
+ */
+typedef const struct objc_selector *SEL;
+#include "deprecated/struct_objc_selector.h"
+
+/* A Class is a class (in the object-oriented sense).  In Objective-C
+   there is the complication that each Class is an object itself, and
+   so belongs to a class too.  This class that a class belongs to is
+   called its 'meta class'.
 */
-typedef struct objc_object {
-  struct objc_class*  class_pointer;
+typedef struct objc_class *Class;
+#include "deprecated/MetaClass.h"
+#include "deprecated/struct_objc_class.h"
+
+/* An 'id' is an object of an unknown class.  The struct objc_object
+   is private and what you see here is only the beginning of the
+   struct.  In theory, the fact that 'class_pointer' is public means
+   that if you have any object 'object', you can immediately get its
+   class by using '((id)object)->class_pointer', but this is not
+   recommended; you should use object_get_class(object) instead.
+*/
+typedef struct objc_object
+{
+  /* 'class_pointer' is the Class that the object belongs to.  In case
+     of a Class object, this pointer points to the meta class.  */
+  /* Note that the Apple/NeXT runtime calls this variable 'isa'.
+     TODO: Decide if we want to call it 'isa' too.  TODO: Why not
+     simply hide this pointer and force users to use the proper API to
+     get it ?
+  */
+  Class class_pointer;
 } *id;
 
 /*
-** Definition of method type.  When retrieving the implementation of a
-** method, this is type of the pointer returned.  The idea of the
-** definition of IMP is to represent a 'pointer to a general function
-** taking an id, a SEL, followed by other unspecified arguments'.  You
-** must always cast an IMP to a pointer to a function taking the
-** appropriate, specific types for that function, before calling it -
-** to make sure the appropriate arguments are passed to it.  The code
-** generated by the compiler to perform method calls automatically
-** does this cast inside method calls.
+  'IMP' is a C function that implements a method.  When retrieving the
+  implementation of a method from the runtime, this is the type of the
+  pointer returned.  The idea of the definition of IMP is to represent
+  a 'pointer to a general function taking an id, a SEL, followed by
+  other unspecified arguments'.  You must always cast an IMP to a
+  pointer to a function taking the appropriate, specific types for
+  that function, before calling it - to make sure the appropriate
+  arguments are passed to it.  The code generated by the compiler to
+  perform method calls automatically does this cast inside method
+  calls.
 */
 typedef id (*IMP)(id, SEL, ...); 
 
-/*
-** More simple types...
-*/
-#define nil (id)0                               /* id of Nil instance */
-#define Nil (Class)0                            /* id of Nil class */
-typedef char *STR;                              /* String alias */
+/* 'nil' is the null object.  Messages to nil do nothing and always
+   return 0.  */
+#define nil (id)0
 
-/*
-** The compiler generates one of these structures for each class.  
-** 
-** This structure is the definition for classes. 
-** 
-** This structure is generated by the compiler in the executable and used by
-** the run-time during normal messaging operations.  Therefore some members
-** change type. The compiler generates "char* const" and places a string in
-** the following member variables:  super_class. 
+/* 'Nil' is the null class.  Since classes are objects too, this is
+   actually the same object as 'nil' (and behaves in the same way),
+   but it has a type of Class, so it is good to use it instead of
+   'nil' if you are comparing a Class object to nil as it enables the
+   compiler to do some type-checking.  */
+#define Nil (Class)0
+
+#include "deprecated/STR.h"
+
+/* TODO: Move the 'Protocol' declaration into objc/runtime.h.  A
+   Protocol is simply an object, not a basic Objective-C type.  The
+   Apple runtime defines Protocol in objc/runtime.h too, so it's good
+   to move it there for API compatibility.
 */
-typedef struct objc_class *MetaClass;
-typedef struct objc_class *Class;
-struct objc_class {     
-  MetaClass           class_pointer;          /* Pointer to the class's
-                                                meta class. */
-  struct objc_class*  super_class;            /* Pointer to the super 
-                                                class. NULL for class 
-                                                Object. */
-  const char*         name;                   /* Name of the class. */
-  long                version;                /* Unknown. */
-  unsigned long       info;                   /* Bit mask.  See class masks 
-                                                defined above. */
-  long                instance_size;          /* Size in bytes of the class.  
-                                                The sum of the class 
-						definition and all super 
-						class definitions. */
-  struct objc_ivar_list* ivars;               /* Pointer to a structure that
-                                                describes the instance 
-                                                variables in the class
-                                                definition.  NULL indicates
-                                                no instance variables.  Does
-                                                not include super class
-                                                variables. */
-  struct objc_method_list*  methods;          /* Linked list of instance
-                                                methods defined for the 
-                                                class. */
-  struct sarray *    dtable;                  /* Pointer to instance 
-					         method dispatch table. */  
-  struct objc_class* subclass_list;           /* Subclasses */
-  struct objc_class* sibling_class;
-
-  struct objc_protocol_list *protocols;	      /* Protocols conformed to */
-  void* gc_object_type;
-};
 
+/* A 'Protocol' is a formally defined list of selectors (normally
+   created using the @protocol Objective-C syntax).  It is mostly used
+   at compile-time to check that classes implement all the methods
+   that they are supposed to.  Protocols are also available in the
+   runtime system as Protocol objects.
+ */
 #ifndef __OBJC__
-typedef struct objc_protocol {
-  struct objc_class* class_pointer;
-  char *protocol_name;
-  struct objc_protocol_list *protocol_list;
-  struct objc_method_description_list *instance_methods, *class_methods; 
-} Protocol; 
-
+  /* Once we stop including the deprecated struct_objc_protocol.h
+     there is no reason to even define a 'struct objc_protocol'.  As
+     all the structure details will be hidden, a Protocol basically is
+     simply an object (as it should be).
+   */
+  /* typedef struct objc_object Protocol; */
+  #include "deprecated/struct_objc_protocol.h"
 #else /* __OBJC__ */
-@class Protocol;
+  @class Protocol;
 #endif 
 
-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 */
+/* Deprecated include - here temporarily, for backwards-compatibility
+   as reval_t, apply_t, arglist_t and objc_msg_lookup() used to be
+   defined here.  */
+#include "message.h"
 
+/* Compatibility note: the Apple/NeXT runtime defines sel_getName(),
+   sel_registerName(), object_getClassName(), object_getIndexedIvars()
+   in this file while the GNU runtime defines them in runtime.h.
 
-IMP objc_msg_lookup(id receiver, SEL op);
+   The reason the GNU runtime does not define them here is that they
+   are not basic Objective-C types (defined in this file), but are
+   part of the runtime API (defined in runtime.h).
+*/
 
 #ifdef __cplusplus
 }