1 2.. role:: block-term 3 4================================= 5Language Specification for Blocks 6================================= 7 8.. contents:: 9 :local: 10 11Revisions 12========= 13 14- 2008/2/25 --- created 15- 2008/7/28 --- revised, ``__block`` syntax 16- 2008/8/13 --- revised, Block globals 17- 2008/8/21 --- revised, C++ elaboration 18- 2008/11/1 --- revised, ``__weak`` support 19- 2009/1/12 --- revised, explicit return types 20- 2009/2/10 --- revised, ``__block`` objects need retain 21 22Overview 23======== 24 25A new derived type is introduced to C and, by extension, Objective-C, 26C++, and Objective-C++ 27 28The Block Type 29============== 30 31Like function types, the :block-term:`Block type` is a pair consisting 32of a result value type and a list of parameter types very similar to a 33function type. Blocks are intended to be used much like functions with 34the key distinction being that in addition to executable code they 35also contain various variable bindings to automatic (stack) or managed 36(heap) memory. 37 38The abstract declarator, 39 40.. code-block:: c 41 42 int (^)(char, float) 43 44describes a reference to a Block that, when invoked, takes two 45parameters, the first of type char and the second of type float, and 46returns a value of type int. The Block referenced is of opaque data 47that may reside in automatic (stack) memory, global memory, or heap 48memory. 49 50Block Variable Declarations 51=========================== 52 53A :block-term:`variable with Block type` is declared using function 54pointer style notation substituting ``^`` for ``*``. The following are 55valid Block variable declarations: 56 57.. code-block:: c 58 59 void (^blockReturningVoidWithVoidArgument)(void); 60 int (^blockReturningIntWithIntAndCharArguments)(int, char); 61 void (^arrayOfTenBlocksReturningVoidWithIntArgument[10])(int); 62 63Variadic ``...`` arguments are supported. [variadic.c] A Block that 64takes no arguments must specify void in the argument list [voidarg.c]. 65An empty parameter list does not represent, as K&R provide, an 66unspecified argument list. Note: both gcc and clang support K&R style 67as a convenience. 68 69A Block reference may be cast to a pointer of arbitrary type and vice 70versa. [cast.c] A Block reference may not be dereferenced via the 71pointer dereference operator ``*``, and thus a Block's size may not be 72computed at compile time. [sizeof.c] 73 74Block Literal Expressions 75========================= 76 77A :block-term:`Block literal expression` produces a reference to a 78Block. It is introduced by the use of the ``^`` token as a unary 79operator. 80 81.. code-block:: c 82 83 Block_literal_expression ::= ^ block_decl compound_statement_body 84 block_decl ::= 85 block_decl ::= parameter_list 86 block_decl ::= type_expression 87 88where type expression is extended to allow ``^`` as a Block reference 89(pointer) where ``*`` is allowed as a function reference (pointer). 90 91The following Block literal: 92 93.. code-block:: c 94 95 ^ void (void) { printf("hello world\n"); } 96 97produces a reference to a Block with no arguments with no return value. 98 99The return type is optional and is inferred from the return 100statements. If the return statements return a value, they all must 101return a value of the same type. If there is no value returned the 102inferred type of the Block is void; otherwise it is the type of the 103return statement value. 104 105If the return type is omitted and the argument list is ``( void )``, 106the ``( void )`` argument list may also be omitted. 107 108So: 109 110.. code-block:: c 111 112 ^ ( void ) { printf("hello world\n"); } 113 114and: 115 116.. code-block:: c 117 118 ^ { printf("hello world\n"); } 119 120are exactly equivalent constructs for the same expression. 121 122The type_expression extends C expression parsing to accommodate Block 123reference declarations as it accommodates function pointer 124declarations. 125 126Given: 127 128.. code-block:: c 129 130 typedef int (*pointerToFunctionThatReturnsIntWithCharArg)(char); 131 pointerToFunctionThatReturnsIntWithCharArg functionPointer; 132 ^ pointerToFunctionThatReturnsIntWithCharArg (float x) { return functionPointer; } 133 134and: 135 136.. code-block:: c 137 138 ^ int ((*)(float x))(char) { return functionPointer; } 139 140are equivalent expressions, as is: 141 142.. code-block:: c 143 144 ^(float x) { return functionPointer; } 145 146[returnfunctionptr.c] 147 148The compound statement body establishes a new lexical scope within 149that of its parent. Variables used within the scope of the compound 150statement are bound to the Block in the normal manner with the 151exception of those in automatic (stack) storage. Thus one may access 152functions and global variables as one would expect, as well as static 153local variables. [testme] 154 155Local automatic (stack) variables referenced within the compound 156statement of a Block are imported and captured by the Block as const 157copies. The capture (binding) is performed at the time of the Block 158literal expression evaluation. 159 160The compiler is not required to capture a variable if it can prove 161that no references to the variable will actually be evaluated. 162Programmers can force a variable to be captured by referencing it in a 163statement at the beginning of the Block, like so: 164 165.. code-block:: c 166 167 (void) foo; 168 169This matters when capturing the variable has side-effects, as it can 170in Objective-C or C++. 171 172The lifetime of variables declared in a Block is that of a function; 173each activation frame contains a new copy of variables declared within 174the local scope of the Block. Such variable declarations should be 175allowed anywhere [testme] rather than only when C99 parsing is 176requested, including for statements. [testme] 177 178Block literal expressions may occur within Block literal expressions 179(nest) and all variables captured by any nested blocks are implicitly 180also captured in the scopes of their enclosing Blocks. 181 182A Block literal expression may be used as the initialization value for 183Block variables at global or local static scope. 184 185The Invoke Operator 186=================== 187 188Blocks are :block-term:`invoked` using function call syntax with a 189list of expression parameters of types corresponding to the 190declaration and returning a result type also according to the 191declaration. Given: 192 193.. code-block:: c 194 195 int (^x)(char); 196 void (^z)(void); 197 int (^(*y))(char) = &x; 198 199the following are all legal Block invocations: 200 201.. code-block:: c 202 203 x('a'); 204 (*y)('a'); 205 (true ? x : *y)('a') 206 207The Copy and Release Operations 208=============================== 209 210The compiler and runtime provide :block-term:`copy` and 211:block-term:`release` operations for Block references that create and, 212in matched use, release allocated storage for referenced Blocks. 213 214The copy operation ``Block_copy()`` is styled as a function that takes 215an arbitrary Block reference and returns a Block reference of the same 216type. The release operation, ``Block_release()``, is styled as a 217function that takes an arbitrary Block reference and, if dynamically 218matched to a Block copy operation, allows recovery of the referenced 219allocated memory. 220 221 222The ``__block`` Storage Qualifier 223================================= 224 225In addition to the new Block type we also introduce a new storage 226qualifier, :block-term:`__block`, for local variables. [testme: a 227__block declaration within a block literal] The ``__block`` storage 228qualifier is mutually exclusive to the existing local storage 229qualifiers auto, register, and static. [testme] Variables qualified by 230``__block`` act as if they were in allocated storage and this storage 231is automatically recovered after last use of said variable. An 232implementation may choose an optimization where the storage is 233initially automatic and only "moved" to allocated (heap) storage upon 234a Block_copy of a referencing Block. Such variables may be mutated as 235normal variables are. 236 237In the case where a ``__block`` variable is a Block one must assume 238that the ``__block`` variable resides in allocated storage and as such 239is assumed to reference a Block that is also in allocated storage 240(that it is the result of a ``Block_copy`` operation). Despite this 241there is no provision to do a ``Block_copy`` or a ``Block_release`` if 242an implementation provides initial automatic storage for Blocks. This 243is due to the inherent race condition of potentially several threads 244trying to update the shared variable and the need for synchronization 245around disposing of older values and copying new ones. Such 246synchronization is beyond the scope of this language specification. 247 248 249Control Flow 250============ 251 252The compound statement of a Block is treated much like a function body 253with respect to control flow in that goto, break, and continue do not 254escape the Block. Exceptions are treated *normally* in that when 255thrown they pop stack frames until a catch clause is found. 256 257 258Objective-C Extensions 259====================== 260 261Objective-C extends the definition of a Block reference type to be 262that also of id. A variable or expression of Block type may be 263messaged or used as a parameter wherever an id may be. The converse is 264also true. Block references may thus appear as properties and are 265subject to the assign, retain, and copy attribute logic that is 266reserved for objects. 267 268All Blocks are constructed to be Objective-C objects regardless of 269whether the Objective-C runtime is operational in the program or 270not. Blocks using automatic (stack) memory are objects and may be 271messaged, although they may not be assigned into ``__weak`` locations 272if garbage collection is enabled. 273 274Within a Block literal expression within a method definition 275references to instance variables are also imported into the lexical 276scope of the compound statement. These variables are implicitly 277qualified as references from self, and so self is imported as a const 278copy. The net effect is that instance variables can be mutated. 279 280The :block-term:`Block_copy` operator retains all objects held in 281variables of automatic storage referenced within the Block expression 282(or form strong references if running under garbage collection). 283Object variables of ``__block`` storage type are assumed to hold 284normal pointers with no provision for retain and release messages. 285 286Foundation defines (and supplies) ``-copy`` and ``-release`` methods for 287Blocks. 288 289In the Objective-C and Objective-C++ languages, we allow the 290``__weak`` specifier for ``__block`` variables of object type. If 291garbage collection is not enabled, this qualifier causes these 292variables to be kept without retain messages being sent. This 293knowingly leads to dangling pointers if the Block (or a copy) outlives 294the lifetime of this object. 295 296In garbage collected environments, the ``__weak`` variable is set to 297nil when the object it references is collected, as long as the 298``__block`` variable resides in the heap (either by default or via 299``Block_copy()``). The initial Apple implementation does in fact 300start ``__block`` variables on the stack and migrate them to the heap 301only as a result of a ``Block_copy()`` operation. 302 303It is a runtime error to attempt to assign a reference to a 304stack-based Block into any storage marked ``__weak``, including 305``__weak`` ``__block`` variables. 306 307 308C++ Extensions 309============== 310 311Block literal expressions within functions are extended to allow const 312use of C++ objects, pointers, or references held in automatic storage. 313 314As usual, within the block, references to captured variables become 315const-qualified, as if they were references to members of a const 316object. Note that this does not change the type of a variable of 317reference type. 318 319For example, given a class Foo: 320 321.. code-block:: c 322 323 Foo foo; 324 Foo &fooRef = foo; 325 Foo *fooPtr = &foo; 326 327A Block that referenced these variables would import the variables as 328const variations: 329 330.. code-block:: c 331 332 const Foo block_foo = foo; 333 Foo &block_fooRef = fooRef; 334 Foo *const block_fooPtr = fooPtr; 335 336Captured variables are copied into the Block at the instant of 337evaluating the Block literal expression. They are also copied when 338calling ``Block_copy()`` on a Block allocated on the stack. In both 339cases, they are copied as if the variable were const-qualified, and 340it's an error if there's no such constructor. 341 342Captured variables in Blocks on the stack are destroyed when control 343leaves the compound statement that contains the Block literal 344expression. Captured variables in Blocks on the heap are destroyed 345when the reference count of the Block drops to zero. 346 347Variables declared as residing in ``__block`` storage may be initially 348allocated in the heap or may first appear on the stack and be copied 349to the heap as a result of a ``Block_copy()`` operation. When copied 350from the stack, ``__block`` variables are copied using their normal 351qualification (i.e. without adding const). In C++11, ``__block`` 352variables are copied as x-values if that is possible, then as l-values 353if not; if both fail, it's an error. The destructor for any initial 354stack-based version is called at the variable's normal end of scope. 355 356References to ``this``, as well as references to non-static members of 357any enclosing class, are evaluated by capturing ``this`` just like a 358normal variable of C pointer type. 359 360Member variables that are Blocks may not be overloaded by the types of 361their arguments. 362