4.8.3 Scope of invocation

In principle, in the general case each of these is not defined:

• The time at which the code that the block encapsulates is invoked. In particular, even after a block is released (freed), the same code may be invoked by a copy of the block.
• In which thread the code is invoked.
• How many invocations can occur in parallel. In other words, whether it is invoked serially or concurrently.

The implementation of foreign blocks copes with all of these, that is it can work concurrently on any thread and after the block was released/freed, as long as there are live copies of it (except with blocks created by with-local-foreign-block). However, whether the code inside the block can cope with it is dependent on the code. This needs to be considered when creating blocks.

Specific foreign functions that take blocks as argument should be documented to state the scope of invocation. Apple's documentation commonly states whether the code is invoked concurrently or serially. In some functions the caller can decide when it calls the function whether the code can be executed concurrently or not. If you pass the block to a function that is documented to execute it serially, or you can tell it to do it, then you can assume that function that you made the block with is not going to be called concurrently from the block. Otherwise it must be able to cope with concurrent calls from the blocks.

Whether the code may be invoked on another thread or after the function that took the block returned is not normally documented. In many cases it can be deduced with confidence: when you dispatch a block to a queue (for example dispatch_after and similar functions, see the Apple documentation) it clearly can be invoked from another threads after the function returns. In the case of qsort_b (see Apple documentation and the example in (sys:example-file "misc/foreign-blocks.lisp") ) we can be sure that the code will not be invoked after qsort_b returned, because the arguments to the block are based on the data (first argument to qsort_b ), and qsort_b and its callees cannot be guaranteed that the data is still valid once qsort_b returned. On the other hand, we cannot be sure that the block is not invoked on another thread(s) before qsort_b returns. Currently it is probably always called in the same thread where qsort_b was called, but the interface does not guarantee it.

Thus when you create a foreign block in Lisp, the following considerations apply to the Lisp function function that you supply:

• In most cases, function needs to cope with being called in any thread, and hence cannot rely on the dynamic environment. Normally it is impossible to deduce that function will not be called on another thead, so it can be guaranteed only when the function to which the block is passed is documented to guarantee it.

Note: that is the only situation in which it is really valid to use with-local-foreign-block.

• function may need to be able to cope with being called at any time, unless it is documented or deducible from the interface that it can be called only within the scope of the caller. It may be possible to deduce the time limit on a call from the way the block is used.
• The function needs to be able to cope with being called concurrently, unless the documentation of the user of the blocks says that it does not, or you can tell that it is going to be called only on one thread.

LispWorks Foreign Language Interface User Guide and Reference Manual - 7 Dec 2011