[llvm-commits] [PATCH 5/5] [llvm-c] Add LLVMMessageRef for user-owned strings.

[Gregory Szorc]

On 3/19/2012 1:24 PM, Anders Waldenborg wrote:
> 
> Adds a "typedef char *LLVMMessageRef;" to llvm-c.
> 
> This new typedef is used for strings where the user of the API must
> use LLVMDisposeMessage to free the memory.
> 
> This both acts as documentation and simplifies automatic generation
> of bindings.

I'm not in favor of this. If the type provided some additional
functionality over merely wrapping char *, I might be swayed.

C programmers just know what to do with char *. By introducing a wrapper
type, you undermine that accumulated knowledge. All of a sudden people
are like "can I use it in strcmp?," etc.

I believe the problem that needs addressed is documentation. Currently,
not many functions tell you what's going on with memory. Any function
allocating memory, returning a pointer, etc needs to explicitly call out
who owns what memory and (if applicable) the lifetime of that memory. If
the caller is responsible for the memory, the docs need to state the
proper way to dispose of that memory.

In this case, since we're dealing with char * in a C API, I think the
use of free() is implied. Also, with char *, we need to document whether
the allocated buffer is NULL terminated. If a function creates a char *,
it should ideally also take a size_t * which is filled with the length
of the new buffer.