1===========================
2PyObjC support for "Blocks"
3===========================
4
5Introduction
6------------
7
8Objective-C has the concept of "blocks", which are basically anonymous inline
9functions. The syntax for them is like this:
10
11.. sourcecode:: objective-c
12
13	^{ printf("x is %d\n", 42); }
14
15This is a literal for a block that takes no arguments and prints a value when
16called.
17
18Blocks are only suppored when PyObjC is compiled using an Objective-C compiler
19that also supports blocks. 
20
21Calling blocks from Python
22--------------------------
23
24The Python representation for a block is a callable object, that is you can
25call the block just like you call any other function object.
26
27PyObjC manages the memory for blocks, it is not necessary to manage the reference
28counts of blocks in your code.
29
30Limitations
31...........
32
33It is not possible to call arbitrary blocks because PyObjC needs to store some
34additional metadata for a block. This means it is only possible to call blocks
35where the bridge knows the call signature, which means:
36
37* Block was returned from a method for which we know the signature of 
38  returned blocks. PyObjC ships with metadata that covers all of Cocoa.
39
40* When a block is stored in a Cocoa datastructure, such as an NSArray, and that
41  is the only reference to the block PyObjC will loose the additional information
42  that is needed to call the block.
43
44It is possible to retrieve and set the call signature of a block using the 
45``__block_signature__`` attribute on blocks.
46
47
48Implementing blocks in Python
49-----------------------------
50
51It is very easy to use Objective-C methods that have a block as one of their
52arguments: just pass an arbitrary callable. PyObjC will automaticly wrap your
53callable in the right low-level datastructure.
54
55One of the side-effects of this is that the variour storage classes that are
56defined for block-related variables are not relevant for Python users. Blocks
57behave just like regular functions.
58
59Metadata for blocks
60-------------------
61
62The current implementation of blocks doesn't allow for full introspection, which means
63that PyObjC must be taught about the signatures of blocks. This section how that
64is done, but note that you only have to do this for your own code that defines methods 
65that have block arguments or return values. The PyObjC wrappers for the various frameworks
66already contain the required metadata. 
67
68FIXME: The last two sentences aren't very clear.
69
70This metadata is an extension to the "bridgesupport" format as defined by Apple.
71
72If an argument or return value is a block the metadata should contain an "block_pointer"
73attribute, with a value of "true". The element then has subelements describing the 
74signature of block (excluding the implicit block parameter). 
75
76As an example:
77
78.. sourcecode:: xml
79
80   <arg index="0" block_pointer="true">
81      <retval type="v" />
82      <arg type="@" />
83      <arg type="B" />
84   </arg>
85
86This metadata describes an argument that is a block of type ``(void(^)(id,BOOL)``.
87