From patchwork Thu Sep 23 21:20:46 2010 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Nicola Pero X-Patchwork-Id: 65602 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) by ozlabs.org (Postfix) with SMTP id 7EFCDB70EF for ; Fri, 24 Sep 2010 08:27:50 +1000 (EST) Received: (qmail 10016 invoked by alias); 23 Sep 2010 22:27:47 -0000 Received: (qmail 10003 invoked by uid 22791); 23 Sep 2010 22:27:43 -0000 X-SWARE-Spam-Status: No, hits=-1.4 required=5.0 tests=AWL, BAYES_00, RCVD_IN_DNSWL_LOW, TW_BJ, TW_CX X-Spam-Check-By: sourceware.org Received: from smtp151.iad.emailsrvr.com (HELO smtp151.iad.emailsrvr.com) (207.97.245.151) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Thu, 23 Sep 2010 22:27:35 +0000 Received: from relay15.relay.iad.mlsrvr.com (localhost [127.0.0.1]) by relay15.relay.iad.mlsrvr.com (SMTP Server) with ESMTP id 37D441B413F for ; Thu, 23 Sep 2010 17:20:46 -0400 (EDT) Received: from dynamic9.wm-web.iad.mlsrvr.com (dynamic9.wm-web.iad.mlsrvr.com [192.168.2.216]) by relay15.relay.iad.mlsrvr.com (SMTP Server) with ESMTP id 32B801B414B for ; Thu, 23 Sep 2010 17:20:46 -0400 (EDT) Received: from meta-innovation.com (localhost [127.0.0.1]) by dynamic9.wm-web.iad.mlsrvr.com (Postfix) with ESMTP id 24604320088 for ; Thu, 23 Sep 2010 17:20:46 -0400 (EDT) Received: by www2.webmail.us (Authenticated sender: nicola.pero@meta-innovation.com, from: nicola.pero@meta-innovation.com) with HTTP; Thu, 23 Sep 2010 23:20:46 +0200 (CEST) Date: Thu, 23 Sep 2010 23:20:46 +0200 (CEST) Subject: ObjC documentation update From: "Nicola Pero" To: gcc-patches@gcc.gnu.org MIME-Version: 1.0 X-Type: plain Message-ID: <1285276846.147516539@192.168.2.230> X-IsSubscribed: yes Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Delivered-To: mailing list gcc-patches@gcc.gnu.org This patch updates the Objective-C documentation. OK to apply ? Thanks Index: gcc/doc/objc.texi =================================================================== --- gcc/doc/objc.texi (revision 164569) +++ gcc/doc/objc.texi (working copy) @@ -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 @@ * 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 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}. Index: gcc/doc/invoke.texi =================================================================== --- gcc/doc/invoke.texi (revision 164569) +++ gcc/doc/invoke.texi (working copy) @@ -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 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. +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). -@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. - @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 t 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 Index: gcc/ChangeLog =================================================================== --- gcc/ChangeLog (revision 164569) +++ gcc/ChangeLog (working copy) @@ -1,3 +1,26 @@ +2010-09-23 Nicola Pero + + * 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-23 Anatoly Sokolov * config/arm/arm.h (OUTPUT_ADDR_CONST_EXTRA): Remove.