Author: rjmccall Date: Thu Jul 19 22:40:12 2018 New Revision: 337525 URL: http://llvm.org/viewvc/llvm-project?rev=337525&view=rev Log: Document -fobjc-weak as an extension.
Fixes rdar://24091053. Modified: cfe/trunk/docs/LanguageExtensions.rst Modified: cfe/trunk/docs/LanguageExtensions.rst URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/LanguageExtensions.rst?rev=337525&r1=337524&r2=337525&view=diff ============================================================================== --- cfe/trunk/docs/LanguageExtensions.rst (original) +++ cfe/trunk/docs/LanguageExtensions.rst Thu Jul 19 22:40:12 2018 @@ -1200,6 +1200,51 @@ Objective-C objects. ``__has_feature(obj 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 _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits