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