blob: 3632d566838a6388006430fd5c349e248fde74b4 [file] [log] [blame]
Michael Gottesman822dd4c2012-12-19 18:41:09 +00001
2.. role:: block-term
3
4=================================
5Language Specification for Blocks
6=================================
7
8.. contents::
9 :local:
10
11Revisions
12=========
13
Michael Gottesman3714e752012-12-20 03:23:49 +000014- 2008/2/25 --- created
Dmitri Gribenko7b00b842012-12-20 20:51:59 +000015- 2008/7/28 --- revised, ``__block`` syntax
Michael Gottesman3714e752012-12-20 03:23:49 +000016- 2008/8/13 --- revised, Block globals
17- 2008/8/21 --- revised, C++ elaboration
Dmitri Gribenko7b00b842012-12-20 20:51:59 +000018- 2008/11/1 --- revised, ``__weak`` support
Michael Gottesman3714e752012-12-20 03:23:49 +000019- 2009/1/12 --- revised, explicit return types
Dmitri Gribenko7b00b842012-12-20 20:51:59 +000020- 2009/2/10 --- revised, ``__block`` objects need retain
Michael Gottesman822dd4c2012-12-19 18:41:09 +000021
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
Michael Gottesman0e704ed2012-12-19 18:42:42 +000084 block_decl ::=
Michael Gottesman822dd4c2012-12-19 18:41:09 +000085 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
Dmitri Gribenko7b00b842012-12-20 20:51:59 +0000286Foundation defines (and supplies) ``-copy`` and ``-release`` methods for
Michael Gottesman822dd4c2012-12-19 18:41:09 +0000287Blocks.
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.