diff options
author | Nicola Pero <nicola.pero@meta-innovation.com> | 2010-09-24 08:19:17 +0000 |
---|---|---|
committer | Nicola Pero <nicola@gcc.gnu.org> | 2010-09-24 08:19:17 +0000 |
commit | 35e711d3df0277e462f64368ddb11687bf4bbc64 (patch) | |
tree | aa7dc466862449c069c3df648780fb5daef77333 /gcc/doc | |
parent | f1570cec9ba0489df6027e3f8f8e100b70660473 (diff) | |
download | gcc-35e711d3df0277e462f64368ddb11687bf4bbc64.zip gcc-35e711d3df0277e462f64368ddb11687bf4bbc64.tar.gz gcc-35e711d3df0277e462f64368ddb11687bf4bbc64.tar.bz2 |
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
Diffstat (limited to 'gcc/doc')
-rw-r--r-- | gcc/doc/invoke.texi | 131 | ||||
-rw-r--r-- | gcc/doc/objc.texi | 155 |
2 files changed, 157 insertions, 129 deletions
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index 38233b7..ee62b1b 100644 --- a/gcc/doc/invoke.texi +++ b/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 diff --git a/gcc/doc/objc.texi b/gcc/doc/objc.texi index 43da303..1beb748 100644 --- a/gcc/doc/objc.texi +++ b/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}. |