[getdns-api] Custom memory management functions again

[Willem Toorop]

>From talking to people involved in the getdns-api design at the IETF-88,
we learned that custom memory functions configured per context are an
essential part of the design.  They really did *not* want custom memory
functions to be global.  They did agree that setting all memory
functions in one go is the better method.

We propose to replace getdns_context_set_allocator,
getdns_context_set_reallocator and getdns_context_set_deallocator with
the following signature for setting them:

getdns_return_t
getdns_context_set_memory_functions(getdns_context_t context,
    void *(*malloc) (size_t),
    void *(*realloc) (void *, size_t),
    void (*free) (void *)
    );

Now the creation of the context itself should also be possible with
those custom memory function.  Therefore I propose to have this extra
context constructor:

getdns_return_t
getdns_context_create_with_memory_functions(
    getdns_context_t * context,
    int set_from_os,
    void *(*malloc) (size_t),
    void *(*realloc) (void *, size_t),
    void (*free) (void *)
    );

Dicts and lists that were generated as a result of actions done by the
library will inherit the custom memory functions from the context.

But the user is able to create dicts and lists on its own. We propose to
add the following signatures to facilitate creation of dicts and lists
by the user with custom memory functions:

struct getdns_list *
getdns_list_create_with_context(getdns_context_t context);

struct getdns_list *
getdns_list_create_with_memory_functions(
    void *(*malloc) (size_t),
    void *(*realloc) (void *, size_t),
    void (*free) (void *));

struct getdns_dict *
getdns_dict_create_with_context(getdns_context_t context);

struct getdns_dict *
getdns_dict_create_with_memory_functions(
    void *(*malloc) (size_t),
    void *(*realloc) (void *, size_t),
    void (*free) (void *));


Now custom memory functions might be even more useful if they have the
possibility to have state (i.e. the region with Region-based memory
management etc.).  This is best accomplished with a "user argument" that
will be passed to the custom memory management functions.
We propose four more API functions to allow for this:

void
getdns_context_set_extended_memory_functions(getdns_context_t context,
    void *userarg,
    void *(*malloc)(void *userarg, size_t sz),
    void *(*realloc)(void *userarg, void *ptr, size_t sz),
    void (*free)(void *userarg, void *ptr));

getdns_return_t
getdns_context_create_with_extended_memory_functions(
    getdns_context_t * context,
    int set_from_os,
    void *userarg,
    void *(*malloc) (void *userarg, size_t),
    void *(*realloc) (void *userarg, void *, size_t),
    void (*free) (void *userarg, void *)
    );

struct getdns_list *
getdns_list_create_with_extended_memory_functions(
    void *userarg,
    void *(*malloc) (void *userarg, size_t),
    void *(*realloc) (void *userarg, void *, size_t),
    void (*free) (void *userarg, void *));


struct getdns_dict *
getdns_dict_create_with_extended_memory_functions(
    void *userarg,
    void *(*malloc) (void *userarg, size_t),
    void *(*realloc) (void *userarg, void *, size_t),
    void (*free) (void *userarg, void *));


What do you think? Is it too much? Should we choose one type of custom
memory functions and if so, which one (extended or not)? Should we hide
the dict_create_* and list_create_* functions?

-- Willem