Release notes

## 7 Release notes

Here are some caveats and open issues that apply to the current release.

##### Deallocation of function results and `out` parameters:

If a C function dynamically allocates some of its outputs (either returned or stored in `out` parameters), its IDL declaration must contain a `quote(dealloc,` `string` `)` clause to properly free the space occupied by those outputs after they have been converted to Caml. Otherwise, memory leaks will occur. (The only exception is results and output parameters of type `[bigarray,managed]` ty`[]`, where the Caml garbage collector takes care of deallocation.)
This does not conform to the MIDL and COM specifications, which say that space for `out` data structures must be allocated with `CoTaskMemAlloc` by the callee, and automatically freed using `CoTaskMemFree` by the generated stub code. (The specs don't say what happens with the return value of the function.) However, there are many functions in Win32 (not to mention the Unix world) that do not follow this convention, and return data structures (e.g. strings) that are statically allocated, or require special deallocation functions. Hence, `camlidl` leaves deallocation of outputs entirely under user control.

##### Allocation and deallocation of `in,out` parameters:

For `in,out` parameters, the MIDL/COM rules are that the caller (the stub code) should allocate the inputs, the callee should free them and allocate again its outputs, and the caller should free the outputs. As explained above, `camlidl`-generated stubs don't automatically free the outputs. Worse, the inputs passed to the functions are allocated partially on the stack and partially in the heap (using `CoTaskMemAlloc`), so the callee may perform an incorrect free on a stack-allocated argument. The best thing to do is avoid `in,out` parameters entirely, and split them into one `in` and one `out` parameter.

##### Reference-counting of COM interfaces:

Caml finalized objects are used to call `Release` automatically on COM interfaces that become unreachable. The reference counting of interfaces passed as `in` and `out` parameters is correctly implemented. However, `in,out` parameters that are interfaces are not correctly handled. Again, avoid `in,out` parameters.

##### COM support:

The support for COM is currently quite small. COM components registered in the system registry can be imported via `Com.create_instance`. Components written in Caml can be exported as DLLs, but not yet as standalone servers. Preliminary support for dispatch interfaces is available, however many of the data types used in the Automation framework are not supported yet (e.g. `SAFEARRAY`).