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