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