[API 0.367] Custom memory management functions

spec/example-all-functions.c

@@ -38,8 +38,17 @@ uint8_t * uint8ptrarg;
 uint16_t * uint16ptrarg;
 uint32_t * uint32ptrarg;
 void * arrayarg;
-void allocfunctionarg(size_t foo) {UNUSED_PARAM(foo);}
+void * userarg;
+void * allocfunctionarg(size_t foo) {UNUSED_PARAM(foo); return NULL; }
+void * reallocfunctionarg(void* foo, size_t bar)
+	{UNUSED_PARAM(foo); UNUSED_PARAM(bar); return NULL; }
 void deallocfunctionarg(void* foo) {UNUSED_PARAM(foo);}
+void * extendedallocfunctionarg(void* userarg, size_t foo)
+	{UNUSED_PARAM(userarg); UNUSED_PARAM(foo); return NULL; }
+void * extendedreallocfunctionarg(void* userarg, void* foo, size_t bar)
+	{UNUSED_PARAM(userarg); UNUSED_PARAM(foo); UNUSED_PARAM(bar); return NULL; }
+void extendeddeallocfunctionarg(void* userarg, void* foo)
+	{UNUSED_PARAM(userarg); UNUSED_PARAM(foo);}
 void setcallbackfunctionarg(struct getdns_context *foo1, uint16_t foo2)
 	{UNUSED_PARAM(foo1);UNUSED_PARAM(foo2);}
 
@@ -88,6 +97,23 @@ retregular = getdns_context_create(
   boolarg
 );
 
+retregular = getdns_context_create_with_memory_functions(
+  &contextarg,
+  boolarg,
+  allocfunctionarg,
+  reallocfunctionarg,
+  deallocfunctionarg
+);
+
+retregular = getdns_context_create_with_extended_memory_functions(
+  &contextarg,
+  boolarg,
+  userarg,
+  extendedallocfunctionarg,
+  extendedreallocfunctionarg,
+  extendeddeallocfunctionarg
+);
+
 getdns_context_destroy(
   contextarg
 );
@@ -141,6 +167,18 @@ retregular = getdns_dict_get_bindata(dictarg, charstararg, bindataptrarg);
 retregular = getdns_dict_get_int(dictarg, charstararg, uint32ptrarg);
 
 listarg = getdns_list_create();
+listarg = getdns_list_create_with_context(contextarg);
+listarg = getdns_list_create_with_memory_functions(
+  allocfunctionarg,
+  reallocfunctionarg,
+  deallocfunctionarg
+);
+listarg = getdns_list_create_with_extended_memory_functions(
+  userarg,
+  extendedallocfunctionarg,
+  extendedreallocfunctionarg,
+  extendeddeallocfunctionarg
+);
 getdns_list_destroy(listarg);
 retregular =  getdns_list_set_dict(listarg, sizetarg, dictarg);
 retregular =  getdns_list_set_list(listarg, sizetarg, listarg);
@@ -148,6 +186,18 @@ retregular =  getdns_list_set_bindata(listarg, sizetarg, bindataarg);
 retregular =  getdns_list_set_int(listarg, sizetarg, uint32arg);
 
 dictarg = getdns_dict_create();
+dictarg = getdns_dict_create_with_context(contextarg);
+dictarg = getdns_dict_create_with_memory_functions(
+  allocfunctionarg,
+  reallocfunctionarg,
+  deallocfunctionarg
+);
+dictarg = getdns_dict_create_with_extended_memory_functions(
+  userarg,
+  extendedallocfunctionarg,
+  extendedreallocfunctionarg,
+  extendeddeallocfunctionarg
+);
 getdns_dict_destroy(dictarg);
 retregular =  getdns_dict_set_dict(dictarg, charstararg, dictarg);
 retregular =  getdns_dict_set_list(dictarg, charstararg, listarg);
@@ -270,19 +320,19 @@ retregular = getdns_context_set_edns_do_bit(
   uint8arg
 );
 
-retregular = getdns_context_set_memory_allocator(
+retregular = getdns_context_set_memory_functions(
-  contextarg,
-  allocfunctionarg
-);
-
-retregular = getdns_context_set_memory_deallocator(
   contextarg,
+  allocfunctionarg,
+  reallocfunctionarg,
   deallocfunctionarg
 );
 
-retregular = getdns_context_set_memory_reallocator(
+retregular = getdns_context_set_extended_memory_functions(
   contextarg,
-  deallocfunctionarg
+  userarg,
+  extendedallocfunctionarg,
+  extendedreallocfunctionarg,
+  extendeddeallocfunctionarg
 );
 
 return(0); }  /* End of main() */

spec/getdns_core_only.c

@@ -63,6 +63,31 @@ getdns_context_create(
 )
 { UNUSED_PARAM(context); UNUSED_PARAM(set_from_os); return GETDNS_RETURN_GOOD; }
 
+getdns_return_t
+getdns_context_create_with_memory_functions(
+  struct getdns_context  **context,
+  int                    set_from_os,
+  void                   *(*malloc)(size_t),
+  void                   *(*realloc)(void *, size_t),
+  void                   (*free)(void *)
+)
+{ UNUSED_PARAM(context); UNUSED_PARAM(set_from_os);
+  UNUSED_PARAM(malloc); UNUSED_PARAM(realloc); UNUSED_PARAM(free);
+  return GETDNS_RETURN_GOOD; }
+
+getdns_return_t
+getdns_context_create_with_extended_memory_functions(
+  struct getdns_context  **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 *)
+)
+{ UNUSED_PARAM(context); UNUSED_PARAM(set_from_os); UNUSED_PARAM(userarg);
+  UNUSED_PARAM(malloc); UNUSED_PARAM(realloc); UNUSED_PARAM(free);
+  return GETDNS_RETURN_GOOD; }
+
 void
 getdns_context_destroy(
 	struct getdns_context  *context
@@ -162,6 +187,29 @@ getdns_return_t getdns_dict_get_int(struct getdns_dict *this_dict, char *name, u
 struct getdns_list * getdns_list_create()
 { return NULL; }
 
+struct getdns_list * getdns_list_create_with_context(
+  struct getdns_context *context
+)
+{ UNUSED_PARAM(context); return NULL; }
+
+struct getdns_list * getdns_list_create_with_memory_functions(
+  void *(*malloc)(size_t),
+  void *(*realloc)(void *, size_t),
+  void (*free)(void *)
+)
+{ UNUSED_PARAM(malloc); UNUSED_PARAM(realloc); UNUSED_PARAM(free);
+  return NULL; }
+
+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 *)
+)
+{ UNUSED_PARAM(userarg);
+  UNUSED_PARAM(malloc); UNUSED_PARAM(realloc); UNUSED_PARAM(free);
+  return NULL; }
+
 void getdns_list_destroy(struct getdns_list *this_list)
 { UNUSED_PARAM(this_list); }
 
@@ -180,6 +228,29 @@ getdns_return_t getdns_list_set_int(struct getdns_list *this_list, size_t index,
 struct getdns_dict * getdns_dict_create()
 { return NULL; }
 
+struct getdns_dict * getdns_dict_create_with_context(
+  struct getdns_context *context
+)
+{ UNUSED_PARAM(context); return NULL; }
+
+struct getdns_dict * getdns_dict_create_with_memory_functions(
+  void *(*malloc)(size_t),
+  void *(*realloc)(void *, size_t),
+  void (*free)(void *)
+)
+{ UNUSED_PARAM(malloc); UNUSED_PARAM(realloc); UNUSED_PARAM(free);
+  return NULL; }
+
+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 *)
+)
+{ UNUSED_PARAM(userarg);
+  UNUSED_PARAM(malloc); UNUSED_PARAM(realloc); UNUSED_PARAM(free);
+  return NULL; }
+
 void getdns_dict_destroy(struct getdns_dict *this_dict)
 { UNUSED_PARAM(this_dict); }
 
@@ -370,25 +441,28 @@ getdns_context_set_edns_do_bit(
 { UNUSED_PARAM(context); UNUSED_PARAM(value); return GETDNS_RETURN_GOOD; }
 
 getdns_return_t
-getdns_context_set_memory_allocator(
+getdns_context_set_memory_functions(
   struct getdns_context *context,
-  void                   (*value)(size_t somesize)
+  void                  *(*malloc) (size_t),
+  void                  *(*realloc) (void *, size_t),
+  void                  (*free) (void *)
 )
-{ UNUSED_PARAM(context); UNUSED_PARAM(value); return GETDNS_RETURN_GOOD; }
+{ UNUSED_PARAM(context); 
+  UNUSED_PARAM(malloc); UNUSED_PARAM(realloc); UNUSED_PARAM(free);
+  return GETDNS_RETURN_GOOD; }
 
 getdns_return_t
-getdns_context_set_memory_deallocator(
+getdns_context_set_extended_memory_functions(
   struct getdns_context *context,
-  void                   (*value)(void*)
+  void                  *userarg,
+  void                  *(*malloc)(void *userarg, size_t sz),
+  void                  *(*realloc)(void *userarg, void *ptr, size_t sz),
+  void                  (*free)(void *userarg, void *ptr)
 )
-{ UNUSED_PARAM(context); UNUSED_PARAM(value); return GETDNS_RETURN_GOOD; }
+{ UNUSED_PARAM(context); UNUSED_PARAM(userarg);
+  UNUSED_PARAM(malloc); UNUSED_PARAM(realloc); UNUSED_PARAM(free);
+  return GETDNS_RETURN_GOOD; }
 
-getdns_return_t
-getdns_context_set_memory_reallocator(
-  struct getdns_context  *context,
-  void                   (*value)(void*)
-)
-{ UNUSED_PARAM(context); UNUSED_PARAM(value); return GETDNS_RETURN_GOOD; }
 
 getdns_return_t
 getdns_extension_set_libevent_base(

spec/getdns_core_only.h

@@ -1,4 +1,4 @@
-/* Created at 2013-12-04-16-46-17*/
+/* Created at 2013-12-04-16-47-24*/
 #ifndef GETDNS_H
 #define GETDNS_H
 
@@ -279,6 +279,20 @@ getdns_return_t getdns_dict_get_int(struct getdns_dict *this_dict, char *name, u
 
 /* Lists: create, destroy, and set the data at a given position */
 struct getdns_list * getdns_list_create();
+struct getdns_list * getdns_list_create_with_context(
+  struct getdns_context *context
+);
+struct getdns_list * getdns_list_create_with_memory_functions(
+  void *(*malloc)(size_t),
+  void *(*realloc)(void *, size_t),
+  void (*free)(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 *)
+);
 void getdns_list_destroy(struct getdns_list *this_list);
 getdns_return_t getdns_list_set_dict(struct getdns_list *this_list, size_t index, struct getdns_dict *child_dict);
 getdns_return_t getdns_list_set_list(struct getdns_list *this_list, size_t index, struct getdns_list *child_list);
@@ -287,6 +301,20 @@ getdns_return_t getdns_list_set_int(struct getdns_list *this_list, size_t index,
 
 /* Dicts: create, destroy, and set the data at a given name */
 struct getdns_dict * getdns_dict_create();
+struct getdns_dict * getdns_dict_create_with_context(
+  struct getdns_context *context
+);
+struct getdns_dict * getdns_dict_create_with_memory_functions(
+  void *(*malloc)(size_t),
+  void *(*realloc)(void *, size_t),
+  void (*free)(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 *)
+);
 void getdns_dict_destroy(struct getdns_dict *this_dict);
 getdns_return_t getdns_dict_set_dict(struct getdns_dict *this_dict, char *name, struct getdns_dict *child_dict);
 getdns_return_t getdns_dict_set_list(struct getdns_dict *this_dict, char *name, struct getdns_list *child_list);
@@ -347,6 +375,24 @@ getdns_context_create(
   int                    set_from_os
 );
 
+getdns_return_t
+getdns_context_create_with_memory_functions(
+  struct getdns_context  **context,
+  int                    set_from_os,
+  void                   *(*malloc)(size_t),
+  void                   *(*realloc)(void *, size_t),
+  void                   (*free)(void *)
+);
+getdns_return_t
+getdns_context_create_with_extended_memory_functions(
+  struct getdns_context  **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 *)
+);
+
 void
 getdns_context_destroy(
   struct getdns_context   *context
@@ -532,21 +578,20 @@ getdns_context_set_edns_do_bit(
 );
 
 getdns_return_t
-getdns_context_set_memory_allocator(
+getdns_context_set_memory_functions(
   struct getdns_context *context,
-  void                   (*value)(size_t somesize)
+  void                  *(*malloc) (size_t),
+  void                  *(*realloc) (void *, size_t),
+  void                  (*free) (void *)
 );
 
 getdns_return_t
-getdns_context_set_memory_deallocator(
+getdns_context_set_extended_memory_functions(
   struct getdns_context *context,
-  void                   (*value)(void*)
+  void                  *userarg,
-);
+  void                  *(*malloc)(void *userarg, size_t sz),
-
+  void                  *(*realloc)(void *userarg, void *ptr, size_t sz),
-getdns_return_t
+  void                  (*free)(void *userarg, void *ptr)
-getdns_context_set_memory_reallocator(
-  struct getdns_context  *context,
-  void                   (*value)(void*)
 );
 
 #endif /* GETDNS_H */

spec/index.html

@@ -332,6 +332,25 @@ getdns_context_create(
 be used with other API calls; that context contains the API's default values. Most applications will
 want <code>set_from_os</code> set to <code>1</code>.</p>
 
+<div class=forh>getdns_return_t
+getdns_context_create_with_memory_functions(
+  struct getdns_context  **context,
+  int                    set_from_os,
+  void                   *(*malloc)(size_t),
+  void                   *(*realloc)(void *, size_t),
+  void                   (*free)(void *)
+);
+getdns_return_t
+getdns_context_create_with_extended_memory_functions(
+  struct getdns_context  **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 *)
+);
+</div>
+
 <p>To clean up the context, including cleaning up all outstanding transactions that were called
 using this context, use the function:</p>
 
@@ -418,7 +437,7 @@ Definition of main()
 specifically designed to allow an application that wants to process results in polling instead of in
 callbacks to be able to create its own polling interface fairly trivially. Such a program would
 create a data structure for the calls, including their <code>transaction_id</code> and
-<code>userag</code>. The <code>userarg</code> could be the polling data structure or have a pointer to it.
+<code>userarg</code>. The <code>userarg</code> could be the polling data structure or have a pointer to it.
 The application would have just
 one callback function for all requests, and that function would copy the <code>response</code> into
 application memory, update the data structure based on the <code>transaction_id</code> index,
@@ -542,6 +561,20 @@ you need to create a dict. The requisite functions are:</p>
 <div class=forh id="datasetters">
 /* Lists: create, destroy, and set the data at a given position */
 struct getdns_list * getdns_list_create();
+struct getdns_list * getdns_list_create_with_context(
+  struct getdns_context *context
+);
+struct getdns_list * getdns_list_create_with_memory_functions(
+  void *(*malloc)(size_t),
+  void *(*realloc)(void *, size_t),
+  void (*free)(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 *)
+);
 void getdns_list_destroy(struct getdns_list *this_list);
 getdns_return_t getdns_list_set_dict(struct getdns_list *this_list, size_t index, struct getdns_dict *child_dict);
 getdns_return_t getdns_list_set_list(struct getdns_list *this_list, size_t index, struct getdns_list *child_list);
@@ -550,6 +583,20 @@ getdns_return_t getdns_list_set_int(struct getdns_list *this_list, size_t index,
 
 /* Dicts: create, destroy, and set the data at a given name */
 struct getdns_dict * getdns_dict_create();
+struct getdns_dict * getdns_dict_create_with_context(
+  struct getdns_context *context
+);
+struct getdns_dict * getdns_dict_create_with_memory_functions(
+  void *(*malloc)(size_t),
+  void *(*realloc)(void *, size_t),
+  void (*free)(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 *)
+);
 void getdns_dict_destroy(struct getdns_dict *this_dict);
 getdns_return_t getdns_dict_set_dict(struct getdns_dict *this_dict, char *name, struct getdns_dict *child_dict);
 getdns_return_t getdns_dict_set_list(struct getdns_dict *this_dict, char *name, struct getdns_list *child_list);
@@ -2042,34 +2089,32 @@ getdns_context_set_edns_do_bit(
 <p class=cont>The value is between 0 and 1; the default
 is <span class=default>0</span>.</p>
 
-<h2>8.9 Context Use of C Functions</h2>
+<h2>8.9 Context use of custom memory management functions</h2>
 
 <div class=forh>
 getdns_return_t
-getdns_context_set_memory_allocator(
+getdns_context_set_memory_functions(
   struct getdns_context *context,
-  void                   (*value)(size_t somesize)
+  void                  *(*malloc) (size_t),
+  void                  *(*realloc) (void *, size_t),
+  void                  (*free) (void *)
 );</div>
-<p class=cont>The value is a function pointer to the memory allocator; the
+<p class=cont>The given memory management functions will be used for creating the response dicts.
-default is the <span class=default>malloc</span> function.</p>
+The response dicts inherit the custom memory management functions from the context and will deallocate themselves (and their members) with the custom deallocator.
+By default the system <span class=default>malloc</span>, <span class=default>realloc</span> and <span>free</span> are used.</p>
 
 <div class=forh>
 getdns_return_t
-getdns_context_set_memory_deallocator(
+getdns_context_set_extended_memory_functions(
   struct getdns_context *context,
-  void                   (*value)(void*)
+  void                  *userarg,
+  void                  *(*malloc)(void *userarg, size_t sz),
+  void                  *(*realloc)(void *userarg, void *ptr, size_t sz),
+  void                  (*free)(void *userarg, void *ptr)
 );</div>
-<p class=cont>The value is a function pointer to the memory deallocator; the
+<p class=cont><p class=cont>The given extended memory management functions will be used for creating the response dicts.
-default is the <span class=default>free</span> function.</p>
+The value of <code>userarg</code> argument will be passed to the custom <code>malloc<code>, <code>realloc</code> and <code>free</code>.
-
+The response dicts inherit the custom memory management functions and the value for <code>userarg</code> from the context and will deallocate themselves (and their members) with the custom deallocator.</p>
-<div class=forh>
-getdns_return_t
-getdns_context_set_memory_reallocator(
-  struct getdns_context  *context,
-  void                   (*value)(void*)
-);</div>
-<p class=cont>The value is a function pointer to the memory reallocator; the
-default is the <span class=default>realloc</span> function.</p>
 
 <h2>8.10 <a id="ContextCodes">Context Codes</a></h2>
 
@@ -2115,7 +2160,7 @@ default is the <span class=default>realloc</span> function.</p>
 
 <h1>9. The Generated Files</h1>
 
-<p>There is <a href="getdns-0.366.tgz">a tarball</a> that includes the .h files,
+<p>There is <a href="getdns-0.367.tgz">a tarball</a> that includes the .h files,
 the examples, and so on. The examples all make, even though there is no API implementation, based
 on a pseudo-implementation in the tarball; see make-examples-PLATFORM.sh. Note that this currently builds fine
 on the Macintosh and Ubuntu; help is definitely appreciated on making the build process