Purpose¶

The first and primary purpose of this document is to serve as a completetechnical specification of Automatic Reference Counting. Given a coreObjective-C compiler and runtime, it should be possible to write a compiler andruntime which implements these new semantics.

The secondary purpose is to act as a rationale for why ARC was designed in thisway. This should remain tightly focused on the technical design and should notstray into marketing speculation.

Background¶

This document assumes a basic familiarity with C.

Blocks are a C language extension for creating anonymous functions.Users interact with and transfer block objects usingblockpointers, which are represented like a normal pointer. A block may capturevalues from local variables; when this occurs, memory must be dynamicallyallocated. The initial allocation is done on the stack, but the runtimeprovides aBlock_copy function which, given a block pointer, either copiesthe underlying block object to the heap, setting its reference count to 1 andreturning the new block pointer, or (if the block object is already on theheap) increases its reference count by 1. The paired function isBlock_release, which decreases the reference count by 1 and destroys theobject if the count reaches zero and is on the heap.

Objective-C is a set of language extensions, significant enough to beconsidered a different language. It is a strict superset of C. The extensionscan also be imposed on C++, producing a language called Objective-C++. Theprimary feature is a single-inheritance object system; we briefly describe themodern dialect.

Objective-C defines a new type kind, collectively called theobjectpointer types. This kind has two notable builtin members,id andClass;id is the final supertype of all object pointers. The validityof conversions between object pointer types is not checked at runtime. Usersmay defineclasses; each class is a type, and the pointer to thattype is an object pointer type. A class may have a superclass; its pointertype is a subtype of its superclass’s pointer type. A class has a set ofivars, fields which appear on all instances of that class. Forevery classT there’s an associated metaclass; it has no fields, itssuperclass is the metaclass ofT’s superclass, and its metaclass is a globalclass. Every class has a global object whose class is the class’s metaclass;metaclasses have no associated type, so pointers to this object have typeClass.

A class declaration (@interface) declares a set ofmethods. Amethod has a return type, a list of argument types, and aselector:a name likefoo:bar:baz:, where the number of colons corresponds to thenumber of formal arguments. A method may be an instance method, in which caseit can be invoked on objects of the class, or a class method, in which case itcan be invoked on objects of the metaclass. A method may be invoked byproviding an object (called thereceiver) and a list of formalarguments interspersed with the selector, like so:

[receiverfoo:fooArgbar:barArgbaz:bazArg]

This looks in the dynamic class of the receiver for a method with this name,then in that class’s superclass, etc., until it finds something it can execute.The receiver “expression” may also be the name of a class, in which case theactual receiver is the class object for that class, or (within methoddefinitions) it may besuper, in which case the lookup algorithm startswith the static superclass instead of the dynamic class. The actual methodsdynamically found in a class are not those declared in the@interface, butthose defined in a separate@implementation declaration; however, whencompiling a call, typechecking is done based on the methods declared in the@interface.

Method declarations may also be grouped intoprotocols, which are notinherently associated with any class, but which classes may claim to follow.Object pointer types may be qualified with additional protocols that the objectis known to support.

Class extensions are collections of ivars and methods, designed toallow a class’s@interface to be split across multiple files; however,there is still a primary implementation file which must see the@interfaces of all class extensions.Categories allowmethods (but not ivars) to be declaredpost hoc on an arbitrary class; themethods in the category’s@implementation will be dynamically added to thatclass’s method tables which the category is loaded at runtime, replacing thosemethods in case of a collision.

In the standard environment, objects are allocated on the heap, and theirlifetime is manually managed using a reference count. This is done using twoinstance methods which all classes are expected to implement:retainincreases the object’s reference count by 1, whereasrelease decreases itby 1 and calls the instance methoddealloc if the count reaches 0. Tosimplify certain operations, there is also anautorelease pool, athread-local list of objects to callrelease on later; an object can beadded to this pool by callingautorelease on it.

Block pointers may be converted to typeid; block objects are laid out in away that makes them compatible with Objective-C objects. There is a builtinclass that all block objects are considered to be objects of; this classimplementsretain by adjusting the reference count, not by callingBlock_copy.

Evolution¶

ARC is under continual evolution, and this document must be updated as thelanguage progresses.

If a change increases the expressiveness of the language, for example bylifting a restriction or by adding new syntax, the change will be annotatedwith a revision marker, like so:

ARC applies to Objective-C pointer types, block pointer types, and[beginning Apple 8.0, LLVM 3.8]BPTRs declaredwithinextern"BCPL" blocks.

For now, it is sensible to version this document by the releases of its soleimplementation (and its host project), clang. “LLVM X.Y” refers to anopen-source release of clang from the LLVM project. “Apple X.Y” refers to anApple-provided release of the Apple LLVM Compiler. Other organizations thatprepare their own, separately-versioned clang releases and wish to maintainsimilar information in this document should send requests to cfe-dev.

If a change decreases the expressiveness of the language, for example byimposing a new restriction, this should be taken as an oversight in theoriginal specification and something to be avoided in all versions. Suchchanges are generally to be avoided.

Retain count semantics¶

A retainable object pointer is either anull pointer or a pointerto a valid object. Furthermore, if it has block pointer type and is notnull then it must actually be a pointer to a block object, and if it hasClass type (possibly protocol-qualified) then it must actually be a pointerto a class object. Otherwise ARC does not enforce the Objective-C type systemas long as the implementing methods follow the signature of the static type.It is undefined behavior if ARC is exposed to an invalid pointer.

For ARC’s purposes, a valid object is one with “well-behaved” retainingoperations. Specifically, the object must be laid out such that theObjective-C message send machinery can successfully send it the followingmessages:

• retain, taking no arguments and returning a pointer to the object.

• release, taking no arguments and returningvoid.

• autorelease, taking no arguments and returning a pointer to the object.

The behavior of these methods is constrained in the following ways. The termhigh-level semantics is an intentionally vague term; the intent isthat programmers must implement these methods in a way such that the compiler,modifying code in ways it deems safe according to these constraints, will notviolate their requirements. For example, if the user puts logging statementsinretain, they should not be surprised if those statements are executedmore or less often depending on optimization settings. These constraints arenot exhaustive of the optimization opportunities: values held in localvariables are subject to additional restrictions, described later in thisdocument.

It is undefined behavior if a computation history featuring a send ofretain followed by a send ofrelease to the same object, with nointerveningrelease on that object, is not equivalent under the high-levelsemantics to a computation history in which these sends are removed. Note thatthis implies that these methods may not raise exceptions.

It is undefined behavior if a computation history features any use whatsoeverof an object following the completion of a send ofrelease that is notpreceded by a send ofretain to the same object.

The behavior ofautorelease must be equivalent to sendingrelease whenone of the autorelease pools currently in scope is popped. It may not throw anexception.

When the semantics call for performing one of these operations on a retainableobject pointer, if that pointer isnull then the effect is a no-op.

All of the semantics described in this document are subject to additionaloptimization rules which permit the removal oroptimization of operations based on local knowledge of data flow. Thesemantics describe the high-level behaviors that the compiler implements, notan exact sequence of operations that a program will be compiled into.

Retainable object pointers as operands and arguments¶

In general, ARC does not perform retain or release operations when simply usinga retainable object pointer as an operand within an expression. This includes:

• loading a retainable pointer from an object with non-weakownership,

• passing a retainable pointer as an argument to a function or method, and

• receiving a retainable pointer as the result of a function or method call.

The remainder of this section describes exceptions to these rules, how thoseexceptions are detected, and what those exceptions imply semantically.

voidfoo(__attribute((ns_consumed))idx);-(void)foo:(id)__attribute((ns_consumed))x;

idfoo(void)__attribute((ns_returns_retained));-(id)foo__attribute((ns_returns_retained));

Restrictions¶

Spelling¶

The names of the ownership qualifiers are reserved for the implementation. Aprogram may not assume that they are or are not implemented with macros, orwhat those macros expand to.

An ownership qualifier may be written anywhere that any other type qualifiermay be written.

If an ownership qualifier appears in thedeclaration-specifiers, thefollowing rules apply:

• if the type specifier is a retainable object owner type, the qualifierinitially applies to that type;

• otherwise, if the outermost non-array declarator is a pointeror block pointer declarator, the qualifier initially applies tothat type;

• otherwise the program is ill-formed.

• If the qualifier is so applied at a position in the declarationwhere the next-innermost declarator is a function declarator, andthere is an block declarator within that function declarator, thenthe qualifier applies instead to that block declarator and this ruleis considered afresh beginning from the new position.

If an ownership qualifier appears on the declarator name, or on the declaredobject, it is applied to the innermost pointer or block-pointer type.

If an ownership qualifier appears anywhere else in a declarator, it applies tothe type there.

Semantics¶

There are fivemanaged operations which may be performed on anobject of retainable object pointer type. Each qualifier specifies differentsemantics for each of these operations. It is still undefined behavior toaccess an object outside of its lifetime.

A load or store with “primitive semantics” has the same semantics as therespective operation would have on anvoid* lvalue with the same alignmentand non-ownership qualification.

Reading occurs when performing a lvalue-to-rvalue conversion on anobject lvalue.

• For__weak objects, the current pointee is retained and then released atthe end of the current full-expression. In particular, messaging a__weakobject keeps the object retained until the end of the full expression.

  __weakMyObject*weakObj;voidfoo(){// weakObj is retained before the message send and released at the end of// the full expression.[weakObjm];}

  This must execute atomically with respect to assignments and to the finalrelease of the pointee.

• For all other objects, the lvalue is loaded with primitive semantics.

Assignment occurs when evaluating an assignment operator. Thesemantics vary based on the qualification:

• For__strong objects, the new pointee is first retained; second, thelvalue is loaded with primitive semantics; third, the new pointee is storedinto the lvalue with primitive semantics; and finally, the old pointee isreleased. This is not performed atomically; external synchronization must beused to make this safe in the face of concurrent loads and stores.

• For__weak objects, the lvalue is updated to point to the new pointee,unless the new pointee is an object currently undergoing deallocation, inwhich case the lvalue is updated to a null pointer. This must executeatomically with respect to other assignments to the object, to reads from theobject, and to the final release of the new pointee.

• For__unsafe_unretained objects, the new pointee is stored into thelvalue using primitive semantics.

• For__autoreleasing objects, the new pointee is retained, autoreleased,and stored into the lvalue using primitive semantics.

Initialization occurs when an object’s lifetime begins, whichdepends on its storage duration. Initialization proceeds in two stages:

1. First, a null pointer is stored into the lvalue using primitive semantics.This step is skipped if the object is__unsafe_unretained.

2. Second, if the object has an initializer, that expression is evaluated andthen assigned into the object using the usual assignment semantics.

Destruction occurs when an object’s lifetime ends. In all cases itis semantically equivalent to assigning a null pointer to the object, with theproviso that of course the object cannot be legally read after the object’slifetime ends.

Moving occurs in specific situations where an lvalue is “movedfrom”, meaning that its current pointee will be used but the object may be leftin a different (but still valid) state. This arises with__block variablesand rvalue references in C++. For__strong lvalues, moving is equivalentto loading the lvalue with primitive semantics, writing a null pointer to itwith primitive semantics, and then releasing the result of the load at the endof the current full-expression. For all other lvalues, moving is equivalent toreading the object.

Restrictions¶

Ownership inference¶

Explicit method family control¶

A method may be annotated with theobjc_method_family attribute toprecisely control which method family it belongs to. If a method in an@implementation does not have this attribute, but there is a methoddeclared in the corresponding@interface that does, then the attribute iscopied to the declaration in the@implementation. The attribute isavailable outside of ARC, and may be tested for with the preprocessor query__has_attribute(objc_method_family).

The attribute is spelled__attribute__((objc_method_family(family))). Iffamily isnone, the method has no family, even if it would otherwise be considered tohave one based on its selector and type. Otherwise,family must be one ofalloc,copy,init,mutableCopy, ornew, in which case themethod is considered to belong to the corresponding family regardless of itsselector. It is an error if a method that is explicitly added to a family inthis way does not meet the requirements of the family other than the selectornaming convention.

Semantics of method families¶

A method’s membership in a method family may imply non-standard semantics forits parameters and return type.

Methods in thealloc,copy,mutableCopy, andnew families —that is, methods in all the currently-defined families exceptinit —implicitlyreturn a retained object as if they were annotated withthens_returns_retained attribute. This can be overridden by annotatingthe method with either of thens_returns_autoreleased orns_returns_not_retained attributes.

Properties also follow same naming rules as methods. This means that those inthealloc,copy,mutableCopy, andnew families provide accesstoretained objects. Thiscan be overridden by annotating the property withns_returns_not_retainedattribute.

Object liveness¶

ARC may not allow a retainable objectX to be deallocated at atimeT in a computation history if:

• X is the value stored in a__strong objectS withprecise lifetime semantics, or

• X is the value stored in a__strong objectS withimprecise lifetime semantics and, at some point afterT butbefore the next store toS, the computation history features aload fromS and in some way depends on the value loaded, or

• X is a value described as being released at the end of thecurrent full-expression and, at some point afterT but beforethe end of the full-expression, the computation history dependson that value.

A computation history depends on a pointer valueP if it:

• performs a pointer comparison withP,

• loads fromP,

• stores toP,

• depends on a pointer valueQ derived via pointer arithmeticfromP (including an instance-variable or field access), or

• depends on a pointer valueQ loaded fromP.

Dependency applies only to values derived directly or indirectly froma particular expression result and does not occur merely because aseparate pointer value dynamically aliasesP. Furthermore, thisdependency is not carried by values that are stored to objects.

No object lifetime extension¶

If, in the formal computation history of the program, an objectXhas been deallocated by the time of an observable side-effect, thenARC must causeX to be deallocated by no later than the occurrenceof that side-effect, except as influenced by the re-ordering of thedestruction of objects.

Precise lifetime semantics¶

In general, ARC maintains an invariant that a retainable object pointer held ina__strong object will be retained for the full formal lifetime of theobject. Objects subject to this invariant haveprecise lifetimesemantics.

By default, local variables of automatic storage duration do not have preciselifetime semantics. Such objects are simply strong references which holdvalues of retainable object pointer type, and these values are still fullysubject to the optimizations on values under local control.

A local variable of retainable object owner type and automatic storage durationmay be annotated with theobjc_precise_lifetime attribute to indicate thatit should be considered to be an object with precise lifetime semantics.

Special methods¶

@autoreleasepool¶

To simplify the use of autorelease pools, and to bring them under the controlof the compiler, a new kind of statement is available in Objective-C. It iswritten@autoreleasepool followed by acompound-statement, i.e. by a newscope delimited by curly braces. Upon entry to this block, the current stateof the autorelease pool is captured. When the block is exited normally,whether by fallthrough or directed control flow (such asreturn orbreak), the autorelease pool is restored to the saved state, releasing allthe objects in it. When the block is exited with an exception, the pool is notdrained.

@autoreleasepool may be used in non-ARC translation units, with equivalentsemantics.

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

Externally-Retained Variables¶

In some situations, variables with strong ownership are consideredexternally-retained by the implementation. This means that the variable isretained elsewhere, and therefore the implementation can elide retaining andreleasing its value. Such a variable is implicitlyconst for safety. Incontrast with__unsafe_unretained, an externally-retained variable stillbehaves as a strong variable outside of initialization and destruction. Forinstance, when an externally-retained variable is captured in a block the valueof the variable is retained and released on block capture and destruction. Italso affects C++ features such as lambda capture,decltype, and templateargument deduction.

Implicitly, the implementation assumes that theself parameter in anon-init method and thevariable in a for-in loop are externally-retained.

Externally-retained semantics can also be opted into with theobjc_externally_retained attribute. This attribute can apply to strong localvariables, functions, methods, or blocks:

@classWobbleAmount;@interfaceWidget :NSObject-(void)wobble:(WobbleAmount*)amount;@end@implementationWidget-(void)wobble:(WobbleAmount*)amount__attribute__((objc_externally_retained)){// 'amount' and 'alias' aren't retained on entry, nor released on exit.__attribute__((objc_externally_retained))WobbleAmount*alias=amount;}@end

Annotating a function with this attribute makes every parameter with strongretainable object pointer type externally-retained, unless the variable wasexplicitly qualified with__strong. For instance,first_param isexternally-retained (and thereforeconst) below, but notsecond_param:

__attribute__((objc_externally_retained))voidf(NSArray*first_param,__strongNSArray*second_param){// ...}

You can test if your compiler has support forobjc_externally_retained with__has_attribute:

#if __has_attribute(objc_externally_retained)// Use externally retained...#endif

self¶

Theself parameter variable of an non-init Objective-C method is consideredexternally-retained by the implementation.It is undefined behavior, or at least dangerous, to cause an object to bedeallocated during a message send to that object. In an init method,selffollows the :ref:initfamilyrules<arc.family.semantics.init>.

Fast enumeration iteration variables¶

If a variable is declared in the condition of an Objective-C fast enumerationloop, and the variable has no explicit ownership qualifier, then it isimplicitlyexternally-retained so thatobjects encountered during the enumeration are not actually retained andreleased.

Blocks¶

The implicitconst capture variables created when evaluating a blockliteral expression have the same ownership semantics as the local variablesthey capture. The capture is performed by reading from the captured variableand initializing the capture variable with that value; the capture variable isdestroyed when the block literal is, i.e. at the end of the enclosing scope.

Theinference rules apply equally to__block variables, which is a shift in semantics from non-ARC, where__block variables did not implicitly retain during capture.

__block variables of retainable object owner type are moved off the stackby initializing the heap copy with the result of moving from the stack copy.

With the exception of retains done as part of initializing a__strongparameter variable or reading a__weak variable, whenever these semanticscall for retaining a value of block-pointer type, it has the effect of aBlock_copy. The optimizer may remove such copies when it sees that theresult is used only as an argument to a call.

When a block pointer type is converted to a non-block pointer type (such asid),Block_copy is called. This is necessary because a block allocatedon the stack won’t get copied to the heap when the non-block pointer escapes.A block pointer is implicitly converted toid when it is passed to afunction as a variadic argument.

Exceptions¶

By default in Objective C, ARC is not exception-safe for normal releases:

• It does not end the lifetime of__strong variables when their scopes areabnormally terminated by an exception.

• It does not perform releases which would occur at the end of afull-expression if that full-expression throws an exception.

A program may be compiled with the option-fobjc-arc-exceptions in order toenable these, or with the option-fno-objc-arc-exceptions to explicitlydisable them, with the last such argument “winning”.

In Objective-C++,-fobjc-arc-exceptions is enabled by default.

ARC does end the lifetimes of__weak objects when an exception terminatestheir scope unless exceptions are disabled in the compiler.

Interior pointers¶

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

• the last use of the returned pointer, or any pointer derived from it, in thecalling function or

• the autorelease pool is restored to a previous state.

As an exception, no extension is required if the receiver is loaded directlyfrom a__strong object withprecise lifetime semantics.

C retainable pointer types¶

A type is aC retainable pointer type if it is a pointer to(possibly qualified)void or a pointer to a (possibly qualifier)structorclass type.

#pragma clang arc_cf_code_audited begin...#pragma clang arc_cf_code_audited end

idobjc_autorelease(idvalue);¶

Precondition:value is null or a pointer to a valid object.

Ifvalue is null, this call has no effect. Otherwise, it adds the objectto the innermost autorelease pool exactly as if the object had been sent theautorelease message.

Always returnsvalue.

voidobjc_autoreleasePoolPop(void*pool);¶

Precondition:pool is the result of a previous call toobjc_autoreleasePoolPush on thecurrent thread, where neitherpool nor any enclosing pool have previouslybeen popped.

Releases all the objects added to the given autorelease pool and anyautorelease pools it encloses, then sets the current autorelease pool to thepool directly enclosingpool.

void*objc_autoreleasePoolPush(void);¶

Creates a new autorelease pool that is enclosed by the current pool, makes thatthe current pool, and returns an opaque “handle” to it.

idobjc_autoreleaseReturnValue(idvalue);¶

Precondition:value is null or a pointer to a valid object.

Ifvalue is null, this call has no effect. Otherwise, it makes a besteffort to hand off ownership of a retain count on the object to a call toobjc_retainAutoreleasedReturnValue (orobjc_unsafeClaimAutoreleasedReturnValue) for the same object inan enclosing call frame. If this is not possible, the object is autoreleased asabove.

Always returnsvalue.

voidobjc_copyWeak(id*dest,id*src);¶

Precondition:src is a valid pointer which either contains a null pointeror has been registered as a__weak object.dest is a valid pointerwhich has not been registered as a__weak object.

dest is initialized to be equivalent tosrc, potentially registering itwith the runtime. Equivalent to the following code:

voidobjc_copyWeak(id*dest,id*src){objc_release(objc_initWeak(dest,objc_loadWeakRetained(src)));}

Must be atomic with respect to calls toobjc_storeWeak onsrc.

voidobjc_destroyWeak(id*object);¶

Precondition:object is a valid pointer which either contains a nullpointer or has been registered as a__weak object.

object is unregistered as a weak object, if it ever was. The current valueofobject is left unspecified; otherwise, equivalent to the following code:

voidobjc_destroyWeak(id*object){objc_storeWeak(object,nil);}

Does not need to be atomic with respect to calls toobjc_storeWeak onobject.

idobjc_initWeak(id*object,idvalue);¶

Precondition:object is a valid pointer which has not been registered asa__weak object.value is null or a pointer to a valid object.

Ifvalue is a null pointer or the object to which it points has begundeallocation,object is zero-initialized. Otherwise,object isregistered as a__weak object pointing tovalue. Equivalent to thefollowing code:

idobjc_initWeak(id*object,idvalue){*object=nil;returnobjc_storeWeak(object,value);}

Returns the value ofobject after the call.

Does not need to be atomic with respect to calls toobjc_storeWeak onobject.

idobjc_loadWeak(id*object);¶

Precondition:object is a valid pointer which either contains a nullpointer or has been registered as a__weak object.

Ifobject is registered as a__weak object, and the last value storedintoobject has not yet been deallocated or begun deallocation, retains andautoreleases that value and returns it. Otherwise returns null. Equivalent tothe following code:

idobjc_loadWeak(id*object){returnobjc_autorelease(objc_loadWeakRetained(object));}

Must be atomic with respect to calls toobjc_storeWeak onobject.

idobjc_loadWeakRetained(id*object);¶

Precondition:object is a valid pointer which either contains a nullpointer or has been registered as a__weak object.

Ifobject is registered as a__weak object, and the last value storedintoobject has not yet been deallocated or begun deallocation, retainsthat value and returns it. Otherwise returns null.

Must be atomic with respect to calls toobjc_storeWeak onobject.

voidobjc_moveWeak(id*dest,id*src);¶

Precondition:src is a valid pointer which either contains a null pointeror has been registered as a__weak object.dest is a valid pointerwhich has not been registered as a__weak object.

dest is initialized to be equivalent tosrc, potentially registering itwith the runtime.src may then be left in its original state, in whichcase this call is equivalent toobjc_copyWeak, or it may be left as null.

Must be atomic with respect to calls toobjc_storeWeak onsrc.

voidobjc_release(idvalue);¶

Precondition:value is null or a pointer to a valid object.

Ifvalue is null, this call has no effect. Otherwise, it performs arelease operation exactly as if the object had been sent thereleasemessage.

idobjc_retain(idvalue);¶

Precondition:value is null or a pointer to a valid object.

Ifvalue is null, this call has no effect. Otherwise, it performs a retainoperation exactly as if the object had been sent theretain message.

Always returnsvalue.

idobjc_retainAutorelease(idvalue);¶

Precondition:value is null or a pointer to a valid object.

Ifvalue is null, this call has no effect. Otherwise, it performs a retainoperation followed by an autorelease operation. Equivalent to the followingcode:

idobjc_retainAutorelease(idvalue){returnobjc_autorelease(objc_retain(value));}

Always returnsvalue.

idobjc_retainAutoreleaseReturnValue(idvalue);¶

Precondition:value is null or a pointer to a valid object.

Ifvalue is null, this call has no effect. Otherwise, it performs a retainoperation followed by the operation described inobjc_autoreleaseReturnValue.Equivalent to the following code:

idobjc_retainAutoreleaseReturnValue(idvalue){returnobjc_autoreleaseReturnValue(objc_retain(value));}

Always returnsvalue.

idobjc_retainAutoreleasedReturnValue(idvalue);¶

Precondition:value is null or a pointer to a valid object.

Ifvalue is null, this call has no effect. Otherwise, it attempts toaccept a hand off of a retain count from a call toobjc_autoreleaseReturnValue onvalue in a recently-called function or something it tail-calls. If thatfails, it performs a retain operation exactly likeobjc_retain.

Always returnsvalue.

idobjc_retainBlock(idvalue);¶

Precondition:value is null or a pointer to a valid block object.

Ifvalue is null, this call has no effect. Otherwise, if the block pointedto byvalue is still on the stack, it is copied to the heap and the addressof the copy is returned. Otherwise a retain operation is performed on theblock exactly as if it had been sent theretain message.

voidobjc_storeStrong(id*object,idvalue);¶

Precondition:object is a valid pointer to a__strong object which isadequately aligned for a pointer.value is null or a pointer to a validobject.

Performs the complete sequence for assigning to a__strong object ofnon-block type[*]. Equivalent to the following code:

voidobjc_storeStrong(id*object,idvalue){idoldValue=*object;value=[valueretain];*object=value;[oldValuerelease];}

This does not imply that a__strong object of block type is aninvalid argument to this function. Rather it implies that anobjc_retainand not anobjc_retainBlock operation will be emitted if the argument isa block.

idobjc_storeWeak(id*object,idvalue);¶

Precondition:object is a valid pointer which either contains a nullpointer or has been registered as a__weak object.value is null or apointer to a valid object.

Ifvalue is a null pointer or the object to which it points has begundeallocation,object is assigned null and unregistered as a__weakobject. Otherwise,object is registered as a__weak object or has itsregistration updated to point tovalue.

Returns the value ofobject after the call.

idobjc_unsafeClaimAutoreleasedReturnValue(idvalue);¶

Precondition:value is null or a pointer to a valid object.

Ifvalue is null, this call has no effect. Otherwise, it attempts toaccept a hand off of a retain count from a call toobjc_autoreleaseReturnValue onvalue in a recently-called function or something it tail-calls (in a mannersimilar toobjc_retainAutoreleasedReturnValue). If that succeeds,it performs a release operation exactly likeobjc_release. If the handoff fails, this call has no effect.

Always returnsvalue.