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