From 98a48cf99d78b7969b0aedaa8b24dea5cee07fff Mon Sep 17 00:00:00 2001 From: John McCall Date: Sun, 19 Jun 2011 09:36:02 +0000 Subject: [PATCH] Describe the ARC runtime support calls. git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@133385 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/AutomaticReferenceCounting.html | 265 +++++++++++++++++++++++++++ 1 file changed, 265 insertions(+) diff --git a/docs/AutomaticReferenceCounting.html b/docs/AutomaticReferenceCounting.html index 7ee3a154f3..6b0e1bb9ba 100644 --- a/docs/AutomaticReferenceCounting.html +++ b/docs/AutomaticReferenceCounting.html @@ -1488,6 +1488,271 @@ from exceptions.

+ +
+

Runtime support

+ +

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.

+ +
+

id objc_autorelease(id value);

+

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.

+
+ +
+

void objc_autoreleasePoolPop(void *pool);

+

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.

+
+ +
+

void *objc_autoreleasePoolPush(void);

+

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.

+ +
+ +
+

id objc_autoreleaseReturnValue(id value);

+

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.

+
+ +
+

void objc_copyWeak(id *dest, id *src);

+

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.

+
+ +
+

void objc_destroyWeak(id *object);

+

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.

+
+ +
+

id objc_initWeak(id *object, id value);

+

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.

+
+ +
+

id objc_loadWeak(id *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.

+
Rationale: loading weak references would be +inherently prone to race conditions without the retain.
+
+ +
+

id objc_loadWeakRetained(id *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.

+
+ +
+

void objc_moveWeak(id *dest, id *src);

+

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.

+
+ +
+

id objc_retain(id 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 exactly as if the object had been sent +the retain message.

+

Always returns value.

+
+ +
+

id objc_retainAutorelease(id 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.

+
+ +
+

id objc_retainAutoreleaseReturnValue(id 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.

+
+ +
+

id objc_retainAutoreleasedReturnValue(id 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.

+
+ +
+

id objc_retainBlock(id 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.

+
+ +
+

void objc_release(id 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 release operation exactly as if the object had been sent +the release message.

+
+ +
+

id objc_storeStrong(id *object, id value);

+

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.

+
+ +
+

id objc_storeWeak(id *object, id 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.

+
+ +
-- 2.40.0