C API design: Who should allocate? [closed]

Answer 1

Both are functionally equivalent. But, in my opinion, method #2 is easier to use. A few reasons for prefering 2 over 1 are:

1. It is more intuitive. Why should I have to call free on the object after I have (apparently) destroyed it using myStruct_Destroy.

2. Hides details of myStruct from user. He does not have to worry about it's size, etc.

3. In method #2, myStruct_init does not have to worry about the initial state of the object.

4. You don't have to worry about memory leaks from user forgetting to call free.

If your API implementation is being shipped as a separate shared library however, method #2 is a must. To isolate your module from any mismatch in implementations of malloc/new and free/delete across compiler versions you should keep memory allocation and de-allocation to yourself. Note, this is more true of C++ than of C.

Answer 2

That could give some element of reflexion:

case #1 mimick the memory allocation scheme of C++, with more or less the same benefits :

• easy allocation of temporaries on stack (or in static arrays or such to write you own struct allocator replacing malloc).
• easy free of memory if anything goes wrong in init

case #2 hides more informations on used structure and can also be used for opaque structures, typically when structure as seen by user is not exactly the same as internally used by the lib (say there could be some more fields hidden at the end of structure).

Mixed API between case#1 and case #2 is also common : there is a field used to pass in a pointer to some already initialized structure, if it is null it is allocated (and pointer is always returned). With such API the free is usually responsibility of caller even if init performed allocation.

In most cases I would probably go for case #1.

Answer 3

I would go for (1) with one simple extension, that is to have your _init function always return the pointer to the object. Your pointer initialization then may just read:

myStruct *s = myStruct_init(malloc(sizeof(myStruct)));

As you can see the right hand side then only has a reference to the type and not to the variable anymore. A simple macro then gives you (2) at least partially

#define NEW(T) (T ## _init(malloc(sizeof(T))))

and your pointer initialization reads

myStruct *s = NEW(myStruct);

Answer 4

See your method #2 says

myStruct *s = myStruct_init();

myStruct_foo(s);

myStruct_destroy(s);

Now see if myStruct_init() needs return some error code for various reason then lets go this way.

myStruct *s;
int ret = myStruct_init(&s);  // int myStruct_init(myStruct **s);

myStruct_foo(s);

myStruct_destroy(s);

Answer 5

Method number 2 every time.

Why? because with method number 1 you have to leak implementation details to the caller. The caller has to know at least how big the struct is. You can't change the internal implementation of the object without recompiling any code that uses it.