From: John McCall Date: Sat, 18 Jun 2011 07:31:30 +0000 (+0000) Subject: A couple of minor changes to the ARC spec, plus a new section X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=f3d08a6882810bae3644aae2eab05e121fb7bc3a;p=clang A couple of minor changes to the ARC spec, plus a new section specifying that retain/release/autorelease/retainCount are forbidden, plus a section talking about the behavior of dealloc. git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@133340 91177308-0d34-0410-b5e6-96231b3b80d8 --- diff --git a/docs/AutomaticReferenceCounting.html b/docs/AutomaticReferenceCounting.html index d094d74125..1150614254 100644 --- a/docs/AutomaticReferenceCounting.html +++ b/docs/AutomaticReferenceCounting.html @@ -14,6 +14,10 @@ div.rationale { font-style: italic } +div.rationale em { + font-style: normal +} + div h1 { font-size: 2em; margin: .67em 0 } div div h1 { font-size: 1.5em; margin: .75em 0 } div div div h1 { font-size: 1.17em; margin: .83em 0 } @@ -1136,7 +1140,7 @@ or more calls to init methods on the same object, except that each init method invocation may perform at most one delegate init call.

- +

Related result types

@@ -1212,6 +1216,96 @@ still be useful to document them here.

Miscellaneous

+
+

Special methods

+ +
+

Memory management methods

+ +

A program is ill-formed if it contains a method definition, message +send, or @selector expression for any of the following +selectors: +

    +
  • autorelease
    • +
  • release
    • +
  • retain
    • +
  • retainCount
    • +
+

+ +

Rationale: retainCount is banned +because ARC robs it of consistent semantics. The others were banned +after weighing three options for how to deal with message sends:

+ +

Honoring them would work out very poorly if a programmer +naively or accidentally tried to incorporate code written for manual +retain/release code into an ARC program. At best, such code would do +twice as much work as necessary; quite frequently, however, ARC and +the explicit code would both try to balance the same retain, leading +to crashes. The cost is losing the ability to perform unrooted +retains, i.e. retains not logically corresponding to a strong +reference in the object graph.

+ +

Ignoring them would badly violate user expectations about their +code. While it would make it easier to develop code simultaneously +for ARC and non-ARC, there is very little reason to do so except for +certain library developers. ARC and non-ARC translation units share +an execution model and can seamlessly interoperate. Within a +translation unit, a developer who faithfully maintains their code in +non-ARC mode is suffering all the restrictions of ARC for zero +benefit, while a developer who isn't testing the non-ARC mode is +likely to be unpleasantly surprised if they try to go back to it.

+ +

Banning them has the disadvantage of making it very awkward +to migrate existing code to ARC. The best answer to that, given a +number of other changes and restrictions in ARC, is to provide a +specialized tool to assist users in that migration.

+ +

Implementing these methods was banned because they are too integral +to the semantics of ARC; many tricks which worked tolerably under +manual reference counting will misbehave if ARC performs an ephemeral +extra retain or two. If absolutely required, it is still possible to +implement them in non-ARC code, for example in a category; the +implementations must obey the semantics +laid out elsewhere in this document.

+ +
+
+ +
+

dealloc

+ +

A program is ill-formed if it contains a message send +or @selector expression for the selector dealloc.

+ +

Rationale: there are no legitimate reasons +to call dealloc directly.

+ +

A class may provide a method definition for an instance method +named dealloc. This method will be called after the final +release of the object but before it is deallocated or any of +its instance variables are destroyed. The superclass's implementation +of dealloc will be called automatically when the method +returns.

+ +

Rationale: even though ARC destroys instance +variables automatically, there are still legitimate reasons to write +a dealloc method, such as freeing non-retainable resources. +Failing to call [super dealloc] in such a method is nearly +always a bug. Sometimes, the object is simply trying to prevent +itself from being destroyed, but dealloc is really far too +late for the object to be raising such objections. Somewhat more +legitimately, an object may have been pool-allocated and should not be +deallocated with free; for now, this can only be supported +with a dealloc implementation outside of ARC. Such an +implementation must be very careful to do all the other work +that NSObject's dealloc would, which is outside the +scope of this document to describe.

+ +
+ +
+

@autoreleasepool

@@ -1226,6 +1320,9 @@ as return or break), the autorelease pool is restored to the saved state, releasing all the objects in it. When the block is exited with an exception, the pool is not drained.

+

@autoreleasepool may be used in non-ARC translation units, +with equivalent semantics.

+

A program is ill-formed if it refers to the NSAutoreleasePool class.