/usr/share/doc/camlidl/html/main007.html is in camlidl-doc 1.04-4.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.06-7 of 2001-11-14">
<TITLE>
Release notes
</TITLE>
</HEAD>
<BODY >
<A HREF="main006.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A>
<HR>
<H2><A NAME="htoc33">7</A> Release notes</H2>
Here are some caveats and open issues that apply to the current
release.<BR>
<BR>
<H5>Deallocation of function results and <TT>out</TT> parameters:</H5>
If a C function dynamically allocates some of its outputs (either
returned or stored in <TT>out</TT> parameters), its IDL declaration must
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
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 <TT>[bigarray,managed] </TT><I>ty</I><TT>[]</TT>,
where the Caml garbage collector takes care of deallocation.)<BR>
<BR>
This does not conform to the MIDL and COM specifications, which say
that space for <TT>out</TT> data structures must be allocated
with <TT>CoTaskMemAlloc</TT> by the callee, and automatically freed
using <TT>CoTaskMemFree</TT> 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,
<TT>camlidl</TT> leaves deallocation of outputs entirely under user control.<BR>
<BR>
<H5>Allocation and deallocation of <TT>in,out</TT> parameters:</H5>
For <TT>in,out</TT> 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, <TT>camlidl</TT>-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 <TT>CoTaskMemAlloc</TT>), so the callee may perform an incorrect
free on a stack-allocated argument. The best thing to do is avoid
<TT>in,out</TT> parameters entirely, and split them into one <TT>in</TT> and one
<TT>out</TT> parameter.<BR>
<BR>
<H5>Reference-counting of COM interfaces:</H5>
Caml finalized objects are used to call <TT>Release</TT> automatically on COM
interfaces that become unreachable. The reference counting of
interfaces passed as <TT>in</TT> and <TT>out</TT> parameters is correctly
implemented. However, <TT>in,out</TT> parameters that are interfaces are not
correctly handled. Again, avoid <TT>in,out</TT> parameters.<BR>
<BR>
<H5>COM support:</H5>
The support for COM is currently quite small. COM components
registered in the system registry can be imported via
<TT>Com.create_instance</TT>. 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. <TT>SAFEARRAY</TT>).
<BR>
<BR>
<HR>
<A HREF="main006.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A>
</BODY>
</HTML>
|