From: John McCall <rjmccall@apple.com>
Date: Fri, 20 Jul 2018 05:40:12 +0000 (+0000)
Subject: Document -fobjc-weak as an extension.
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=141ca05e332ab0be507a7325313fe230a9506a7a;p=clang

Document -fobjc-weak as an extension.

Fixes rdar://24091053.

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@337525 91177308-0d34-0410-b5e6-96231b3b80d8
---

diff --git a/docs/LanguageExtensions.rst b/docs/LanguageExtensions.rst
index 1d6c7ec5eb..1aef265a85 100644
--- a/docs/LanguageExtensions.rst
+++ b/docs/LanguageExtensions.rst
@@ -1200,6 +1200,51 @@ Objective-C objects. ``__has_feature(objc_arc_fields)`` indicates that C structs
 are allowed to have fields that are pointers to Objective-C objects managed by
 automatic reference counting.
 
+.. _objc-weak:
+
+Weak references
+---------------
+
+Clang supports ARC-style weak and unsafe references in Objective-C even
+outside of ARC mode.  Weak references must be explicitly enabled with
+the ``-fobjc-weak`` option; use ``__has_feature((objc_arc_weak))``
+to test whether they are enabled.  Unsafe references are enabled
+unconditionally.  ARC-style weak and unsafe references cannot be used
+when Objective-C garbage collection is enabled.
+
+Except as noted below, the language rules for the ``__weak`` and
+``__unsafe_unretained`` qualifiers (and the ``weak`` and
+``unsafe_unretained`` property attributes) are just as laid out
+in the :doc:`ARC specification <AutomaticReferenceCounting>`.
+In particular, note that some classes do not support forming weak
+references to their instances, and note that special care must be
+taken when storing weak references in memory where initialization
+and deinitialization are outside the responsibility of the compiler
+(such as in ``malloc``-ed memory).
+
+Loading from a ``__weak`` variable always implicitly retains the
+loaded value.  In non-ARC modes, this retain is normally balanced
+by an implicit autorelease.  This autorelease can be suppressed
+by performing the load in the receiver position of a ``-retain``
+message send (e.g. ``[weakReference retain]``); note that this performs
+only a single retain (the retain done when primitively loading from
+the weak reference).
+
+For the most part, ``__unsafe_unretained`` in non-ARC modes is just the
+default behavior of variables and therefore is not needed.  However,
+it does have an effect on the semantics of block captures: normally,
+copying a block which captures an Objective-C object or block pointer
+causes the captured pointer to be retained or copied, respectively,
+but that behavior is suppressed when the captured variable is qualified
+with ``__unsafe_unretained``.
+
+Note that the ``__weak`` qualifier formerly meant the GC qualifier in
+all non-ARC modes and was silently ignored outside of GC modes.  It now
+means the ARC-style qualifier in all non-GC modes and is no longer
+allowed if not enabled by either ``-fobjc-arc`` or ``-fobjc-weak``.
+It is expected that ``-fobjc-weak`` will eventually be enabled by default
+in all non-GC Objective-C modes.
+
 .. _objc-fixed-enum:
 
 Enumerations with a fixed underlying type