Re: PATCH: Merge objc-improvements-branch to mainline

[Ziemowit Laski <zlaski at apple dot com>]

On Wednesday, Sep 24, 2003, at 12:09 US/Pacific, Ziemowit Laski wrote:

> On Wednesday, Sep 24, 2003, at 10:48 US/Pacific, Alexander Malmberg 
> wrote:
> > The documentation for these does not seem to be correct, or at least 
> > not
> > consistent with the implementation. It seems that -fzero-link does 
> > what
> > -freplace-objc-classes is documented to do, and -freplace-objc-classes
> > emits a marker that tells the runtime that the implementations in the
> > file should override any earlier implementations.
>
> Quite possibly, I've switched those around. :-)  I'll double-check; 
> thanks
> for noticing this.

Indeed, they were switched around. :-(
> > (Additionally, the documentation for @synchronize is very vague.)
>
> I'm certainly open to suggestions as to how to improve this.

Well, it occurred to me that one obvious way of improving things is to 
describe
_what_ @synchronized acutally does :-) :-), and so I added a paragraph.

So, here is the improved documentation:

Index: gcc/doc/invoke.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/invoke.texi,v
retrieving revision 1.338
diff -c -3 -p -r1.338 invoke.texi
*** gcc/doc/invoke.texi 15 Sep 2003 23:17:13 -0000      1.338
--- gcc/doc/invoke.texi 24 Sep 2003 20:02:19 -0000
*************** in the following sections.
*** 193,200 ****

  @item Objective-C Language Options
  @xref{Objective-C Dialect Options,,Options Controlling Objective-C 
Dialect}.
! @gccoptlist{-fconstant-string-class=@var{class-name} @gol
! -fgnu-runtime  -fnext-runtime  -gen-decls @gol
  -Wno-protocol  -Wselector -Wundeclared-selector}

  @item Language Independent Options
--- 193,206 ----

  @item Objective-C Language Options
  @xref{Objective-C Dialect Options,,Options Controlling Objective-C 
Dialect}.
! @gccoptlist{
! -fconstant-string-class=@var{class-name} @gol
! -fgnu-runtime  -fnext-runtime @gol
! -fno-nil-receivers @gol
! -fobjc-exceptions @gol
! -freplace-objc-classes @gol
! -fzero-link @gol
! -gen-decls @gol
  -Wno-protocol  -Wselector -Wundeclared-selector}

  @item Language Independent Options
*************** In this example, G++ will synthesize a d
*** 1743,1748 ****
--- 1749,1757 ----
  @cindex compiler options, Objective-C
  @cindex Objective-C options, command line
  @cindex options, Objective-C
+ (NOTE: This manual does not describe the Objective-C language itself. 
 See
+ @w{@uref{http://gcc.gnu.org/readings.html}} for references.)
+
  This section describes the command-line options that are only 
meaningful
  for Objective-C programs, but you can also use most of the GNU 
compiler
  options regardless of what language your program is in.  For example,
*************** programs:
*** 1765,1771 ****
  @opindex fconstant-string-class
  Use @var{class-name} as the name of the class to instantiate for each
  literal string specified with the syntax @code{@@"@dots{}"}.  The 
default
! class name is @code{NXConstantString}.

  @item -fgnu-runtime
  @opindex fgnu-runtime
--- 1774,1784 ----
  @opindex fconstant-string-class
  Use @var{class-name} as the name of the class to instantiate for each
  literal string specified with the syntax @code{@@"@dots{}"}.  The 
default
! class name is @code{NXConstantString} if the GNU runtime is being 
used, and
! @code{NSConstantString} if the NeXT runtime is being used (see 
below).  The
! @option{-fconstant-cfstrings} option, if also present, will override 
the
! @option{-fconstant-string-class} setting and cause @code{@@"@dots{}"} 
literals
! to be laid out as constant CoreFoundation strings.

  @item -fgnu-runtime
  @opindex fgnu-runtime
*************** Generate output compatible with the NeXT
*** 1778,1783 ****
--- 1791,1917 ----
  for NeXT-based systems, including Darwin and Mac OS X@.  The macro
  @code{__NEXT_RUNTIME__} is predefined if (and only if) this option is
  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 conjunciton with
+ the NeXT runtime on Mac OS X 10.3 and later.
+
+ @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.  Currently, this option 
is only
+ available in conjunciton with the NeXT runtime on Mac OS X 10.3 and 
later.
+
+ @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 -freplace-objc-classes
+ @opindex -freplace-objc-classes
+ Emit a special marker instructing @command{ld(1)} not to statically 
link in
+ the resulting object file, and allow @command{dyld(1)} to load it in 
at
+ run time instead.  This is used in conjunction with the 
Fix-and-Continue
+ debugging mode, where the object file in question may be recompiled 
and
+ dynamically reloaded in the course of program execution, without the 
need
+ to restart the program itself.  Currently, Fix-and-Continue 
functionality
+ is only available in conjunciton withthe NeXT runtime on Mac OS X 10.3
+ and later.
+
+ @item -fzero-link
+ @opindex -fzero-link
+ When compiling for the NeXT runtime, the compiler ordinarily replaces 
calls
+ to @code{objc_getClass("@dots{}")} (when the name of the class is 
known at
+ compile time) with static class references that get initialized at 
load time,
+ 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.

  @item -gen-decls
  @opindex gen-decls
--------------------------------------------------------------
Ziemowit Laski                 1 Infinite Loop, MS 301-2K
Mac OS X Compiler Group        Cupertino, CA USA  95014-2083
Apple Computer, Inc.           +1.408.974.6229  Fax .5477