| 1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" |
| 2 |
"http://www.w3.org/TR/REC-html40/loose.dtd"> |
| 3 |
<HTML> |
| 4 |
<HEAD> |
| 5 |
|
| 6 |
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| 7 |
<META name="GENERATOR" content="hevea 1.06-7 of 2001-11-14"> |
| 8 |
<TITLE> |
| 9 |
Release notes |
| 10 |
</TITLE> |
| 11 |
</HEAD> |
| 12 |
<BODY > |
| 13 |
<A HREF="main006.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A> |
| 14 |
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A> |
| 15 |
<HR> |
| 16 |
|
| 17 |
<H2><A NAME="htoc33">7</A> Release notes</H2> |
| 18 |
Here are some caveats and open issues that apply to the current |
| 19 |
release.<BR> |
| 20 |
<BR> |
| 21 |
|
| 22 |
<H5>Deallocation of function results and <TT>out</TT> parameters:</H5> |
| 23 |
If a C function dynamically allocates some of its outputs (either |
| 24 |
returned or stored in <TT>out</TT> parameters), its IDL declaration must |
| 25 |
contain a <TT><FONT COLOR=blue>quote(dealloc,</FONT></TT> <TT><I><FONT COLOR=maroon>string</FONT></I></TT> <TT><FONT COLOR=blue>)</FONT></TT> clause to properly free the |
| 26 |
space occupied by those outputs after they have been converted to |
| 27 |
Caml. Otherwise, memory leaks will occur. (The only exception is |
| 28 |
results and output parameters of type <TT>[bigarray,managed] </TT><I>ty</I><TT>[]</TT>, |
| 29 |
where the Caml garbage collector takes care of deallocation.)<BR> |
| 30 |
<BR> |
| 31 |
This does not conform to the MIDL and COM specifications, which say |
| 32 |
that space for <TT>out</TT> data structures must be allocated |
| 33 |
with <TT>CoTaskMemAlloc</TT> by the callee, and automatically freed |
| 34 |
using <TT>CoTaskMemFree</TT> by the generated stub code. (The specs don't |
| 35 |
say what happens with the return value of the function.) |
| 36 |
However, there are many functions in Win32 (not to mention the |
| 37 |
Unix world) that do not follow this convention, and |
| 38 |
return data structures (e.g. strings) that are statically |
| 39 |
allocated, or require special deallocation functions. Hence, |
| 40 |
<TT>camlidl</TT> leaves deallocation of outputs entirely under user control.<BR> |
| 41 |
<BR> |
| 42 |
|
| 43 |
<H5>Allocation and deallocation of <TT>in,out</TT> parameters:</H5> |
| 44 |
For <TT>in,out</TT> parameters, the MIDL/COM rules are that the caller (the |
| 45 |
stub code) should allocate the inputs, the callee should free them |
| 46 |
and allocate again its outputs, and the caller should free the outputs. |
| 47 |
As explained above, <TT>camlidl</TT>-generated stubs don't automatically free |
| 48 |
the outputs. Worse, the inputs passed to the functions are allocated |
| 49 |
partially on the stack and partially in the heap |
| 50 |
(using <TT>CoTaskMemAlloc</TT>), so the callee may perform an incorrect |
| 51 |
free on a stack-allocated argument. The best thing to do is avoid |
| 52 |
<TT>in,out</TT> parameters entirely, and split them into one <TT>in</TT> and one |
| 53 |
<TT>out</TT> parameter.<BR> |
| 54 |
<BR> |
| 55 |
|
| 56 |
<H5>Reference-counting of COM interfaces:</H5> |
| 57 |
Caml finalized objects are used to call <TT>Release</TT> automatically on COM |
| 58 |
interfaces that become unreachable. The reference counting of |
| 59 |
interfaces passed as <TT>in</TT> and <TT>out</TT> parameters is correctly |
| 60 |
implemented. However, <TT>in,out</TT> parameters that are interfaces are not |
| 61 |
correctly handled. Again, avoid <TT>in,out</TT> parameters.<BR> |
| 62 |
<BR> |
| 63 |
|
| 64 |
<H5>COM support:</H5> |
| 65 |
The support for COM is currently quite small. COM components |
| 66 |
registered in the system registry can be imported via |
| 67 |
<TT>Com.create_instance</TT>. Components written in Caml can be exported as |
| 68 |
DLLs, but not yet as standalone servers. Preliminary support for |
| 69 |
dispatch interfaces is available, however many of the data types used |
| 70 |
in the Automation framework are not supported yet (e.g. <TT>SAFEARRAY</TT>). |
| 71 |
<BR> |
| 72 |
<BR> |
| 73 |
<HR> |
| 74 |
<A HREF="main006.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A> |
| 75 |
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A> |
| 76 |
</BODY> |
| 77 |
</HTML> |