在结构上运行的函数的约定

Question

Let's say I have the following in foo.h :

typedef struct {
    char* my_buf;
    int my_int;
} MyFoo;

/* Creates a foo, allocating memory for my_buf and initializing my_int */
void create_foo(MyFoo *foo);
/* Destroys a foo, freeing the memory for my_buf */
void free_foo(MyFoo *foo);

Now in another module, bar.h let's say I have the following:

#include "foo.h"

/* Do something with a foo */
void do_something(MyFoo *foo, SomeType_t otherType, ...);

As written, it's unclear whether or not the MyFoo provided to do_something should have been initialized with create_foo . Since it's not const , I think it's reasonably clear that a foo (ie space allocated for a foo) should be passed in, it will be modified in some way, and then the user can use the modified foo. But how do I most effectively indicate whether or not that foo should have been 'created'? A common pattern is to do something like

MyFoo stackFoo;
do_something(&stackFoo, ...);

But then, if do_something creates the foo, the user has to know that they're responsible for freeing the foo. On the other hand, there's no way to enforce that the foo should have been created; I'm just asking for a pointer (I admit this is a weak counter argument since it applies to a lot of things in C).

Another option would be to have MyFoo include a "created" flag so that it the function can reject any foos that haven't been created, but this seems like I'm over-engineering things.

I just want to be sure I'm not missing a common convention or standard way of handling this. Maybe I'm forcing OOP too much. Thoughts and comments appreciated!

Edit: It was suggested, and I agree, that a better name for create_foo would be init_foo .

Answer 1

Yes you are forcing OOP, this is no wrong but OOP in C is a matter of orderliness. Whatever, you cannot ensure that a foo hasn't been created on stack.

For:

void do_something(MyFoo *foo, SomeType_t otherType, ...);

it is clear that an existing foo is to be passed, as the argument being passed by value. So, the semantic is clear : an existing foo must be passed.

For:

void create_foo(MyFoo *foo);

something's wrong as the argument is passed by value either this should not be called create_foo but init_foo , or you should pass the argument as an address of a pointer. In case of OOP-like programming you should distinguish allocation and initialization.

void init_foo(MyFoo *);

MyFoo foo; // simple creation
init_foo(&foo); // initialization

or

void init_foo(MyFoo *);
MyFoo *alloc_foo();

MyFoo *pfoo = alloc_foo(); // allocation factory
init_foo(pfoo); // initialization
// or with an idiom like
MyFoo *pfoo;
init_foo(pfoo=alloc_foo());

or:

MyFoo *init_foo(MyFoo *);
MyFoo *alloc_foo();

MyFoo *pfoo = init_foo(alloc_foo());

Now you can also make a single call to a convenient function:

MyFoo *create_foo(); // alloc+initialization factory
MyFoo *pfoo = create_foo();

or with a pass-a-pointer idiom:

void create_foo(MyFoo **f);
MyFoo *pfoo;
create_foo(&pfoo);

If you want you can use an opaque type using modularity, to have a better control of your allocations, but at the end it will not ensure that user is not cheating:

// Module foo.c
struct internal_foo {
  int m;
};
void *create_foo() {
  struct internal_foo *pfoo = malloc(...);
  // init structure
  return pfoo;
}
void delete_foo(void *pf) {
  free(pf);
}
// convenient functions for members
void set_m_foo(void *pf,int v) { ((struct internal_foo *)pf)->m = v; }
int get_m_foo(void *pf) { return ((struct internal_foo *)pf)->m; }

thus from an external point, user can only see a generic pointer. If you want to ensure a much better typing, then you can also encapsulate the generic pointer into a dummy structure: struct MyFoo { void *opaque_foo; } struct MyFoo { void *opaque_foo; } .