In gcc/:

        * doc/invoke.texi (-fno-nil-receivers): Tidied up line to remove
        underfull hbox in DVI output.
        (-fobjc-class-cxx-cdtors): Same change.
        (-fobjc-exceptions): Tidied up documentation.  Explain what the
        option does, but moved the (lenghty) description of the exception
        syntax into objc.texi.
        (-fobjc-gc): Explain that the option is not useful with the GNU
        runtime.
        (-fzero-link): Explain that the GNU runtime always works in
        "zero-link" mode.
        * doc/objc.texi: All sections: simplified @node declarations
        removing specification of next, previous, up node.
        (Objective-C): Updated introduction.
        (Garbage Collection): Updated.  The bohem-gc library is now
        included in gcc itself.  Mention that this section only applies to
        the GNU Objective-C runtime.
        (compatibility_alias): Small tidy up.
        (Exceptions): New section mostly containing text previously in the
        description of the -fobjc-exception command-line option.
        (Synchronization): Same.

From-SVN: r164586

gcc/ChangeLog

+2010-09-24  Nicola Pero  <nicola.pero@meta-innovation.com>
+
+	* doc/invoke.texi (-fno-nil-receivers): Tidied up line to remove
+	underfull hbox in DVI output.
+	(-fobjc-class-cxx-cdtors): Same change.
+	(-fobjc-exceptions): Tidied up documentation.  Explain what the
+	option does, but moved the (lenghty) description of the exception
+	syntax into objc.texi.
+	(-fobjc-gc): Explain that the option is not useful with the GNU
+	runtime.
+	(-fzero-link): Explain that the GNU runtime always works in
+	"zero-link" mode.
+	* doc/objc.texi: All sections: simplified @node declarations
+	removing specification of next, previous, up node.
+	(Objective-C): Updated introduction.
+	(Garbage Collection): Updated.  The bohem-gc library is now
+	included in gcc itself.  Mention that this section only applies to
+	the GNU Objective-C runtime.
+	(compatibility_alias): Small tidy up.
+	(Exceptions): New section mostly containing text previously in the
+	description of the -fobjc-exception command-line option.
+	(Synchronization): Same.
+	
 2010-09-24  Uros Bizjak  <ubizjak@gmail.com>
 
 	* config/i386/i386.md (ix86_code_end): Move the initialization of

gcc/doc/invoke.texi

@@ -2516,11 +2516,11 @@ used.
 
 @item -fno-nil-receivers
 @opindex fno-nil-receivers
-Assume that all Objective-C message dispatches (e.g.,
-@code{[receiver message:arg]}) in this translation unit ensure that the receiver
-is not @code{nil}.  This allows for more efficient entry points in the runtime
-to be used.  Currently, this option is only available in conjunction with
-the NeXT runtime on Mac OS X 10.3 and later.
+Assume that all Objective-C message dispatches (@code{[receiver
+message:arg]}) in this translation unit ensure that the receiver is
+not @code{nil}.  This allows for more efficient entry points in the
+runtime to be used.  Currently, this option is only available in
+conjunction with the NeXT runtime on Mac OS X 10.3 and later.
 
 @item -fobjc-call-cxx-cdtors
 @opindex fobjc-call-cxx-cdtors
@@ -2533,14 +2533,15 @@ is a C++ object with a non-trivial destructor, and if so, synthesize a
 special @code{- (void) .cxx_destruct} method that will run
 all such default destructors, in reverse order.
 
-The @code{- (id) .cxx_construct} and/or @code{- (void) .cxx_destruct} methods
-thusly generated will only operate on instance variables declared in the
-current Objective-C class, and not those inherited from superclasses.  It
-is the responsibility of the Objective-C runtime to invoke all such methods
-in an object's inheritance hierarchy.  The @code{- (id) .cxx_construct} methods
-will be invoked by the runtime immediately after a new object
-instance is allocated; the @code{- (void) .cxx_destruct} methods will
-be invoked immediately before the runtime deallocates an object instance.
+The @code{- (id) .cxx_construct} and @code{- (void) .cxx_destruct}
+methods thusly generated will only operate on instance variables
+declared in the current Objective-C class, and not those inherited
+from superclasses.  It is the responsibility of the Objective-C
+runtime to invoke all such methods in an object's inheritance
+hierarchy.  The @code{- (id) .cxx_construct} methods will be invoked
+by the runtime immediately after a new object instance is allocated;
+the @code{- (void) .cxx_destruct} methods will be invoked immediately
+before the runtime deallocates an object instance.
 
 As of this writing, only the NeXT runtime on Mac OS X 10.4 and later has
 support for invoking the @code{- (id) .cxx_construct} and
@@ -2553,100 +2554,20 @@ accomplished via the comm page.
 
 @item -fobjc-exceptions
 @opindex fobjc-exceptions
-Enable syntactic support for structured exception handling in Objective-C,
-similar to what is offered by C++ and Java.  This option is
-unavailable in conjunction with the NeXT runtime on Mac OS X 10.2 and
-earlier.
-
-@smallexample
-  @@try @{
-    @dots{}
-       @@throw expr;
-    @dots{}
-  @}
-  @@catch (AnObjCClass *exc) @{
-    @dots{}
-      @@throw expr;
-    @dots{}
-      @@throw;
-    @dots{}
-  @}
-  @@catch (AnotherClass *exc) @{
-    @dots{}
-  @}
-  @@catch (id allOthers) @{
-    @dots{}
-  @}
-  @@finally @{
-    @dots{}
-      @@throw expr;
-    @dots{}
-  @}
-@end smallexample
-
-The @code{@@throw} statement may appear anywhere in an Objective-C or
-Objective-C++ program; when used inside of a @code{@@catch} block, the
-@code{@@throw} may appear without an argument (as shown above), in which case
-the object caught by the @code{@@catch} will be rethrown.
-
-Note that only (pointers to) Objective-C objects may be thrown and
-caught using this scheme.  When an object is thrown, it will be caught
-by the nearest @code{@@catch} clause capable of handling objects of that type,
-analogously to how @code{catch} blocks work in C++ and Java.  A
-@code{@@catch(id @dots{})} clause (as shown above) may also be provided to catch
-any and all Objective-C exceptions not caught by previous @code{@@catch}
-clauses (if any).
-
-The @code{@@finally} clause, if present, will be executed upon exit from the
-immediately preceding @code{@@try @dots{} @@catch} section.  This will happen
-regardless of whether any exceptions are thrown, caught or rethrown
-inside the @code{@@try @dots{} @@catch} section, analogously to the behavior
-of the @code{finally} clause in Java.
-
-There are several caveats to using the new exception mechanism:
-
-@itemize @bullet
-@item
-Although currently designed to be binary compatible with @code{NS_HANDLER}-style
-idioms provided by the @code{NSException} class, the new
-exceptions can only be used on Mac OS X 10.3 (Panther) and later
-systems, due to additional functionality needed in the (NeXT) Objective-C
-runtime.
-
-@item
-As mentioned above, the new exceptions do not support handling
-types other than Objective-C objects.   Furthermore, when used from
-Objective-C++, the Objective-C exception model does not interoperate with C++
-exceptions at this time.  This means you cannot @code{@@throw} an exception
-from Objective-C and @code{catch} it in C++, or vice versa
-(i.e., @code{throw @dots{} @@catch}).
-@end itemize
-
-The @option{-fobjc-exceptions} switch also enables the use of synchronization
-blocks for thread-safe execution:
-
-@smallexample
-  @@synchronized (ObjCClass *guard) @{
-    @dots{}
-  @}
-@end smallexample
-
-Upon entering the @code{@@synchronized} block, a thread of execution shall
-first check whether a lock has been placed on the corresponding @code{guard}
-object by another thread.  If it has, the current thread shall wait until
-the other thread relinquishes its lock.  Once @code{guard} becomes available,
-the current thread will place its own lock on it, execute the code contained in
-the @code{@@synchronized} block, and finally relinquish the lock (thereby
-making @code{guard} available to other threads).
-
-Unlike Java, Objective-C does not allow for entire methods to be marked
-@code{@@synchronized}.  Note that throwing exceptions out of
-@code{@@synchronized} blocks is allowed, and will cause the guarding object
-to be unlocked properly.
+Enable syntactic support for structured exception handling in
+Objective-C, similar to what is offered by C++ and Java.  This option
+is required to use the Objective-C keywords @code{@@try},
+@code{@@throw}, @code{@@catch}, @code{@@finally} and
+@code{@@synchronized}.  This option is available with both the GNU
+runtime and the NeXT runtime (but not available in conjunction with
+the NeXT runtime on Mac OS X 10.2 and earlier).
 
 @item -fobjc-gc
 @opindex fobjc-gc
-Enable garbage collection (GC) in Objective-C and Objective-C++ programs.
+Enable garbage collection (GC) in Objective-C and Objective-C++
+programs.  This option is only available with the NeXT runtime; the
+GNU runtime has a different garbage collection implementation that
+does not require special compiler flags.
 
 @item -freplace-objc-classes
 @opindex freplace-objc-classes
@@ -2668,6 +2589,8 @@ which improves run-time performance.  Specifying the @option{-fzero-link} flag
 suppresses this behavior and causes calls to @code{objc_getClass("@dots{}")}
 to be retained.  This is useful in Zero-Link debugging mode, since it allows
 for individual class implementations to be modified during program execution.
+The GNU runtime currently always retains calls to @code{objc_get_class("@dots{}")}
+regardless of command line options.
 
 @item -gen-decls
 @opindex gen-decls

gcc/doc/objc.texi

@@ -6,13 +6,11 @@
 @node Objective-C
 @comment  node-name,  next,  previous,  up
 
-@chapter GNU Objective-C runtime features
+@chapter GNU Objective-C features
 
-This document is meant to describe some of the GNU Objective-C runtime
-features.  It is not intended to teach you Objective-C, there are several
-resources on the Internet that present the language.  Questions and
-comments about this document to Ovidiu Predescu
-@email{ovidiu@@cup.hp.com}.
+This document is meant to describe some of the GNU Objective-C
+features.  It is not intended to teach you Objective-C, there are
+several resources on the Internet that present the language.
 
 @menu
 * Executing code before main::
@@ -20,9 +18,11 @@ comments about this document to Ovidiu Predescu
 * Garbage Collection::
 * Constant string objects::
 * compatibility_alias::
+* Exceptions::
+* Synchronization::
 @end menu
 
-@node Executing code before main, Type encoding, Objective-C, Objective-C
+@node Executing code before main
 @section @code{+load}: Executing code before main
 
 The GNU Objective-C runtime provides a way that allows you to execute
@@ -103,7 +103,7 @@ instead of @code{+initialize}.
 @end menu
 
 
-@node What you can and what you cannot do in +load,  , Executing code before main, Executing code before main
+@node What you can and what you cannot do in +load
 @subsection What you can and what you cannot do in @code{+load}
 
 The @code{+load} implementation in the GNU runtime guarantees you the following
@@ -167,7 +167,7 @@ above apply to classes defined in bundle.
 
 
 
-@node Type encoding, Garbage Collection, Executing code before main, Objective-C
+@node Type encoding
 @section Type encoding
 
 The Objective-C compiler generates type encodings for all the
@@ -311,21 +311,19 @@ however, the type specifiers are only encoded when they appear in method
 argument types.
 
 
-@node Garbage Collection, Constant string objects, Type encoding, Objective-C
+@node Garbage Collection
 @section Garbage Collection
 
-Support for a new memory management policy has been added by using a
-powerful conservative garbage collector, known as the
-Boehm-Demers-Weiser conservative garbage collector.  It is available from
-@uref{http://www.hpl.hp.com/@/personal/@/Hans_Boehm/@/gc/}.
+Support for garbage collection with the GNU runtime has been added by
+using a powerful conservative garbage collector, known as the
+Boehm-Demers-Weiser conservative garbage collector.
 
-To enable the support for it you have to configure the compiler using an
-additional argument, @w{@option{--enable-objc-gc}}.  You need to have
-garbage collector installed before building the compiler.  This will
-build an additional runtime library which has several enhancements to
-support the garbage collector.  The new library has a new name,
-@file{libobjc_gc.a} to not conflict with the non-garbage-collected
-library.
+To enable the support for it you have to configure the compiler using
+an additional argument, @w{@option{--enable-objc-gc}}.  This will
+build the boehm-gc library, and build an additional runtime library
+which has several enhancements to support the garbage collector.  The
+new library has a new name, @file{libobjc_gc.a} to not conflict with
+the non-garbage-collected library.
 
 When the garbage collector is used, the objects are allocated using the
 so-called typed memory allocation mechanism available in the
@@ -452,10 +450,6 @@ restrictions in doing this.
 @node compatibility_alias
 @section compatibility_alias
 
-This is a feature of the Objective-C compiler rather than of the
-runtime, anyway since it is documented nowhere and its existence was
-forgotten, we are documenting it here.
-
 The keyword @code{@@compatibility_alias} allows you to define a class name
 as equivalent to another class name.  For example:
 
@@ -476,3 +470,114 @@ There are some constraints on how this can be used---
 @item @code{GSWApplication} (the real class) must be an existing class.
 
 @end itemize
+
+@c =========================================================================
+@node Exceptions
+@section Exceptions
+
+GNU Objective-C provides exception support built into the language, as
+in the following example:
+
+@smallexample
+  @@try @{
+    @dots{}
+       @@throw expr;
+    @dots{}
+  @}
+  @@catch (AnObjCClass *exc) @{
+    @dots{}
+      @@throw expr;
+    @dots{}
+      @@throw;
+    @dots{}
+  @}
+  @@catch (AnotherClass *exc) @{
+    @dots{}
+  @}
+  @@catch (id allOthers) @{
+    @dots{}
+  @}
+  @@finally @{
+    @dots{}
+      @@throw expr;
+    @dots{}
+  @}
+@end smallexample
+
+The @code{@@throw} statement may appear anywhere in an Objective-C or
+Objective-C++ program; when used inside of a @code{@@catch} block, the
+@code{@@throw} may appear without an argument (as shown above), in
+which case the object caught by the @code{@@catch} will be rethrown.
+
+Note that only (pointers to) Objective-C objects may be thrown and
+caught using this scheme.  When an object is thrown, it will be caught
+by the nearest @code{@@catch} clause capable of handling objects of
+that type, analogously to how @code{catch} blocks work in C++ and
+Java.  A @code{@@catch(id @dots{})} clause (as shown above) may also
+be provided to catch any and all Objective-C exceptions not caught by
+previous @code{@@catch} clauses (if any).
+
+The @code{@@finally} clause, if present, will be executed upon exit
+from the immediately preceding @code{@@try @dots{} @@catch} section.
+This will happen regardless of whether any exceptions are thrown,
+caught or rethrown inside the @code{@@try @dots{} @@catch} section,
+analogously to the behavior of the @code{finally} clause in Java.
+
+There are several caveats to using the new exception mechanism:
+
+@itemize @bullet
+@item
+The @option{-fobjc-exceptions} command line option must be used when
+compiling Objective-C files that use exceptions.
+
+@item
+With the GNU runtime, exceptions are always implemented as ``native''
+exceptions and it is recommended that the @option{-fexceptions} and
+@option{-shared-libgcc} options are used when linking.
+
+@item
+With the NeXT runtime, although currently designed to be binary
+compatible with @code{NS_HANDLER}-style idioms provided by the
+@code{NSException} class, the new exceptions can only be used on Mac
+OS X 10.3 (Panther) and later systems, due to additional functionality
+needed in the NeXT Objective-C runtime.
+
+@item
+As mentioned above, the new exceptions do not support handling
+types other than Objective-C objects.   Furthermore, when used from
+Objective-C++, the Objective-C exception model does not interoperate with C++
+exceptions at this time.  This means you cannot @code{@@throw} an exception
+from Objective-C and @code{catch} it in C++, or vice versa
+(i.e., @code{throw @dots{} @@catch}).
+@end itemize
+
+@c =========================================================================
+@node Synchronization
+@section Synchronization
+
+GNU Objective-C provides support for synchronized blocks:
+
+@smallexample
+  @@synchronized (ObjCClass *guard) @{
+    @dots{}
+  @}
+@end smallexample
+
+Upon entering the @code{@@synchronized} block, a thread of execution
+shall first check whether a lock has been placed on the corresponding
+@code{guard} object by another thread.  If it has, the current thread
+shall wait until the other thread relinquishes its lock.  Once
+@code{guard} becomes available, the current thread will place its own
+lock on it, execute the code contained in the @code{@@synchronized}
+block, and finally relinquish the lock (thereby making @code{guard}
+available to other threads).
+
+Unlike Java, Objective-C does not allow for entire methods to be
+marked @code{@@synchronized}.  Note that throwing exceptions out of
+@code{@@synchronized} blocks is allowed, and will cause the guarding
+object to be unlocked properly.
+
+Because of the interactions between synchronization and exception
+handling, you can only use @code{@@synchronized} when compiling with
+exceptions enabled, that is with the command line option
+@option{-fobjc-exceptions}.