AutomaticReferenceCounting.html#runtime-support

https://clang.llvm.org/docs/AutomaticReferenceCounting.html#runtime-support

Runtime support

This section describes the interaction between the ARC runtime and the code generated by the ARC compiler. This is not part of the ARC language specification; instead, it is effectively a language-specific ABI supplement, akin to the “Itanium” generic ABI for C++.

Ownership qualification does not alter the storage requirements for objects, except that it is undefined behavior if a __weak object is inadequately aligned for an object of type id. The other qualifiers may be used on explicitly under-aligned memory.

The runtime tracks __weak objects which holds non-null values. It is undefined behavior to direct modify a __weak object which is being tracked by the runtime except through an objc_storeWeak, objc_destroyWeak, or objc_moveWeak call.

The runtime must provide a number of new entrypoints which the compiler may emit, which are described in the remainder of this section.

Rationale

Several of these functions are semantically equivalent to a message send; we emit calls to C functions instead because:

• the machine code to do so is significantly smaller,
• it is much easier to recognize the C functions in the ARC optimizer, and
• a sufficient sophisticated runtime may be able to avoid the message send in common cases.

Several other of these functions are “fused” operations which can be described entirely in terms of other operations. We use the fused operations primarily as a code-size optimization, although in some cases there is also a real potential for avoiding redundant operations in the runtime.

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 autoreleasemessage.

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 toobjc_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 toobjc_copyWeak, or it may be left as null.

Must be atomic with respect to calls to objc_storeWeak on src.

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_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.

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.

[*]	This does not imply that a __strong object of block type is an invalid argument to this function. Rather it implies that an objc_retain and not anobjc_retainBlock operation will be emitted if the argument is a block.

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.