From cf1667022fec6f94a3178d92cb8a719e971d63bc Mon Sep 17 00:00:00 2001 From: John McCall Date: Fri, 22 Jul 2011 08:53:00 +0000 Subject: Document the existing objc_precise_lifetime attribute. Introduce and document a new objc_returns_inner_pointer attribute, and consume it by performing a retain+autorelease on message receivers when they're not immediately loaded from an object with precise lifetime. llvm-svn: 135764 --- clang/docs/AutomaticReferenceCounting.html | 83 ++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) (limited to 'clang/docs/AutomaticReferenceCounting.html') diff --git a/clang/docs/AutomaticReferenceCounting.html b/clang/docs/AutomaticReferenceCounting.html index 5090fa2b795..bc784578e4c 100644 --- a/clang/docs/AutomaticReferenceCounting.html +++ b/clang/docs/AutomaticReferenceCounting.html @@ -1315,6 +1315,39 @@ and only if the value is not demonstrably already retained.

The complete optimization rules are quite complicated, but it would still be useful to document them here.

+
+

Precise lifetime semantics

+ +

In general, ARC maintains an invariant that a retainable object +pointer held in a __strong object will be retained for the +full formal lifetime of the object. Objects subject to this invariant +have precise lifetime semantics.

+ +

By default, local variables of automatic storage duration do not +have precise lifetime semantics. Such objects are simply strong +references which hold values of retainable object pointer type, and +these values are still fully subject to the optimizations on values +under local control.

+ +

Rationale: applying these precise-lifetime +semantics strictly would be prohibitive. Many useful optimizations +that might theoretically decrease the lifetime of an object would be +rendered impossible. Essentially, it promises too much.

+ +

A local variable of retainable object owner type and automatic +storage duration may be annotated with the objc_precise_lifetime +attribute to indicate that it should be considered to be an object +with precise lifetime semantics.

+ +

Rationale: nonetheless, it is sometimes +useful to be able to force an object to be released at a precise time, +even if that object does not appear to be used. This is likely to be +uncommon enough that the syntactic weight of explicitly requesting +these semantics will not be burdensome, and may even make the code +clearer.

+ +
+
@@ -1562,6 +1595,56 @@ from exceptions.

+
+

Interior pointers

+ +

An Objective-C method returning a non-retainable pointer may be +annotated with the objc_returns_inner_pointer attribute to +indicate that it returns a handle to the internal data of an object, +and that this reference will be invalidated if the object is +destroyed. When such a message is sent to an object, the object's +lifetime will be extended until at least the earliest of:

+ + + +

Rationale: not all memory and resources are +managed with reference counts; it is common for objects to manage +private resources in their own, private way. Typically these +resources are completely encapsulated within the object, but some +classes offer their users direct access for efficiency. If ARC is not +aware of methods that return such interior pointers, its +optimizations can cause the owning object to be reclaimed too soon. +This attribute informs ARC that it must tread lightly.

+ +

The extension rules are somewhat intentionally vague. The +autorelease pool limit is there to permit a simple implementation to +simply retain and autorelease the receiver. The other limit permits +some amount of optimization. The phrase derived from is +intended to encompass the results both of pointer transformations, +such as casts and arithmetic, and of loading from such derived +pointers; furthermore, it applies whether or not such derivations are +applied directly in the calling code or by other utility code (for +example, the C library routine strchr). However, the +implementation never need account for uses after a return from the +code which calls the method returning an interior pointer.

+ +

As an exception, no extension is required if the receiver is loaded +directly from a __strong object +with precise lifetime semantics.

+ +

Rationale: implicit autoreleases carry the +risk of significantly inflating memory use, so it's important to +provide users a way of avoiding these autoreleases. Tying this to +precise lifetime semantics is ideal, as for local variables this +requires a very explicit annotation, which allows ARC to trust the +user with good cheer.

+ +
+
-- cgit v1.2.3