From 98a48cf99d78b7969b0aedaa8b24dea5cee07fff Mon Sep 17 00:00:00 2001
From: John McCall
This section describes the requirements of the current ARC +implementation in Clang on the Objective-C runtime. It is not part of +the ARC language specification; instead, it is effectively a +language-specific ABI supplement, akin to the Itanium ABI for C++.
+ +Ownership qualification does not alter the storage requirements for +an object, except that __weak objects must always be +appropriately aligned for an object of type id.
+ +The runtime tracks __weak objects which holds non-null +values. It is undefined behavior to modify a __weak object +which is being tracked by the runtime except through an +objc_storeWeak or +objc_destroyWeak +call.
+ +Precondition: value is null or a pointer to a +valid object.
+If value is null, this call has no effect. Otherwise, it +adds the object to the innermost autorelease pool exactly as if the +object had been sent the autorelease message.
+Always returns value.
+Precondition: pool is the result of a previous call to +objc_autoreleasePoolPush +on the current thread, where neither pool nor any enclosing +pool have previously been popped.
+Releases all the objects added to the given autorelease pool and +any autorelease pools it encloses, then sets the current autorelease +pool to the pool directly enclosing pool.
+Creates a new autorelease pool that is enclosed by the current
+pool, makes that the current pool, and returns an opaque handle
+to it.
Rationale: while the interface is described +as an explicit hierarchy of pools, the rules allow the implementation +to just keep a stack of objects, using the stack depth as the opaque +pool handle.
Precondition: value is null or a pointer to a +valid object.
+If value is null, this call has no effect. Otherwise, it +makes a best effort to hand off ownership of a retain count on the +object to a call +to objc_retainAutoreleasedReturnValue +for the same object in an enclosing call frame. If this is not +possible, the object is autoreleased as above.
+Always returns value.
+Precondition: src is a valid pointer which either +contains a null pointer or has been registered as a __weak +object. dest is a valid pointer which has not been +registered as a __weak object.
+dest is initialized to be equivalent to src, +potentially registering it with the runtime. Equivalent to the +following code:
+void objc_copyWeak(id *dest, id *src) { + objc_release(objc_initWeak(dest, objc_loadWeakRetained(src))); +}+
Must be atomic with respect to calls to objc_storeWeak +on src.
+Precondition: object is a valid pointer which +either contains a null pointer or has been registered as +a __weak object.
+object is unregistered as a weak object, if it ever was. +The current value of object is left unspecified; otherwise, +equivalent to the following code:
+void objc_destroyWeak(id *object) { + objc_storeWeak(object, nil); +}+
Does not need to be atomic with respect to calls +to objc_storeWeak on object.
+Precondition: object is a valid pointer which has +not been registered as a __weak object. value is +null or a pointer to a valid object.
+If value is a null pointer or the object to which it +points has begun deallocation, object is zero-initialized. +Otherwise, object is registered as a __weak object +pointing to value. Equivalent to the following code:
+id objc_initWeak(id *object, id value) { + *object = nil; + return objc_storeWeak(object, value); +}+
Returns the value of object after the call.
+Does not need to be atomic with respect to calls +to objc_storeWeak on object.
+Precondition: object is a valid pointer which +either contains a null pointer or has been registered as +a __weak object.
+If object is registered as a __weak object, and +the last value stored into object has not yet been +deallocated or begun deallocation, retains and autoreleases that value +and returns it. Otherwise returns null. Equivalent to the following +code:
+id objc_loadWeak(id *object) { + return objc_autorelease(objc_loadWeakRetained(object)); +}+
Must be atomic with respect to calls to objc_storeWeak +on object.
+Precondition: object is a valid pointer which +either contains a null pointer or has been registered as +a __weak object.
+If object is registered as a __weak object, and +the last value stored into object has not yet been +deallocated or begun deallocation, retains that value and returns it. +Otherwise returns null.
+Must be atomic with respect to calls to objc_storeWeak +on object.
+Precondition: src is a valid pointer which either +contains a null pointer or has been registered as a __weak +object. dest is a valid pointer which has not been +registered as a __weak object.
+dest is initialized to be equivalent to src, +potentially registering it with the runtime. src may then be +left in its original state, in which case this call is equivalent +to objc_copyWeak, or it +may be left as null.
+Must be atomic with respect to calls to objc_storeWeak +on src.
+Precondition: value is null or a pointer to a +valid object.
+If value is null, this call has no effect. Otherwise, it +performs a retain operation exactly as if the object had been sent +the retain message.
+Always returns value.
+Precondition: value is null or a pointer to a +valid object.
+If value is null, this call has no effect. Otherwise, it +performs a retain operation followed by an autorelease operation. +Equivalent to the following code:
+id objc_retainAutorelease(id value) { + return objc_autorelease(objc_retain(value)); +}+
Always returns value.
+Precondition: value is null or a pointer to a +valid object.
+If value is null, this call has no effect. Otherwise, it +performs a retain operation followed by the operation described in +objc_autoreleaseReturnValue. +Equivalent to the following code:
+id objc_retainAutoreleaseReturnValue(id value) { + return objc_autoreleaseReturnValue(objc_retain(value)); +}+
Always returns value.
+Precondition: value is null or a pointer to a +valid object.
+If value is null, this call has no effect. Otherwise, it +attempts to accept a hand off of a retain count from a call to +objc_autoreleaseReturnValue +on value in a recently-called function or something it +calls. If that fails, it performs a retain operation exactly +like objc_retain.
+Always returns value.
+Precondition: value is null or a pointer to a +valid block object.
+If value is null, this call has no effect. Otherwise, if +the block pointed to by value is still on the stack, it is +copied to the heap and the address of the copy is returned. Otherwise +a retain operation is performed on the block exactly as if it had been +sent the retain message.
+Precondition: value is null or a pointer to a +valid object.
+If value is null, this call has no effect. Otherwise, it +performs a release operation exactly as if the object had been sent +the release message.
+Precondition: object is a valid pointer to +a __strong object which is adequately aligned for a +pointer. value is null or a pointer to a valid object.
+Performs the complete sequence for assigning to a __strong +object of non-block type. Equivalent to the following code:
+id objc_storeStrong(id *object, id value) { + value = [value retain]; + id oldValue = *object; + *object = value; + [oldValue release]; + return value; +}+
Always returns value.
+Precondition: object is a valid pointer which +either contains a null pointer or has been registered as +a __weak object. value is null or a pointer to a +valid object.
+If value is a null pointer or the object to which it +points has begun deallocation, object is assigned null +and unregistered as a __weak object. Otherwise, +object is registered as a __weak object or has its +registration updated to point to value.
+Returns the value of object after the call.
+