Re: [Lzip-bug] Restarting an lzip member at any time

[John Reiser]

On 12/11/2009 01:02 PM, Jacob Rief wrote:
> for the API, in the header file I would do a simple forward declaration such as
>
> struct LZ_EncoderImpl;
> typedef LZ_EncoderImpl* LZ_Encoder;
>
> struct LZ_DecoderImpl;
> typedef LZ_DecoderImpl* LZ_Decoder;
>
>
> so that the prototypes of your API look like
>
> void LZ_compress_foo(LZ_Encoder encoder, otherargs);
> void LZ_decompress_foo(LZ_Decoder decoder, otherargs);
>
> and don't take a pointer onto something (no *), but an opaque and
> typesafe handle.

Please think ABI (Application Binary Interface), not only API (Application
Programming Interface.)  A library which has an ABI can be built,
distributed, and used in binary form.  A library which has only an API
(and no ABI) probably does not have that useful property.

One of the requirements for an effective ABI is that the parameter passing
rules for each externally-visible subroutine must be known by every compiler
of code which uses the library.  An interface definition which consists of only

   void LZ_compress_foo(LZ_Encoder encoder, otherargs);

is not useful for an ABI.  The other parts

   struct LZ_EncoderImpl;
   typedef LZ_EncoderImpl* LZ_Encoder;

must be part of the interface, in order that a client may know that
the first parameter is a pointer to a struct.  Because the client must
know this in order for separate compilation to be effective, then it is
impossible to hide the fact that the first argument is a pointer to
a struct.  Therefore, do not try to hide this fact:

   void LZ_compress_foo(struct LZ_Encoder *const encoder, otherargs);

--