Add three more slots to the wmem allocater definition (not yet implemented

by any particular allocator) and better document the entire structure.

svn path=/trunk/; revision=47163

1 files changed, 49 insertions, 11 deletions

diff --git a/doc/README.wmem b/doc/README.wmem
index b21bf01bf2..21d24f2898 100644
--- a/doc/README.wmem
+++ b/doc/README.wmem
@@ -215,7 +215,7 @@ the pool would otherwise be scoped to a single iteration of a loop. For example:
 
 Despite being written in Wireshark's standard C90, wmem follows a fairly
 object-oriented design pattern. Although efficiency is always a concern, the
-primary goals in writing wmem were maintainability, and preventing memory
+primary goals in writing wmem were maintainability and preventing memory
 leaks.
 
 4.1 struct _wmem_allocator_t
@@ -227,21 +227,59 @@ known as an abstract class to those who are more familiar with C++).
 
 Different allocator implementations can provide exactly the same interface by
 assigning their own functions to the members of an instance of the structure.
-The structure currently has five members:
+The structure has eight members in three groups.
+
+4.1.1 Implementation Details
+
+ - private_data
+ - type
+
+The private_data pointer is a void pointer that the allocator implementation can
+use to store whatever internal structures it needs. A pointer to private_data is
+passed to almost all of the other functions that the allocator implementation
+must define.
+
+The type field is an enumeration of type wmem_allocator_type_t (see
+section 3.1). Its value is set by the wmem_allocator_new() function, not
+by the implementation-specific constructor. This field should be considered
+read-only by the allocator implementation.
+
+4.1.2 Consumer Functions
 
  - alloc()
+ - realloc()
+ - free()
+
+These function pointers should be set to functions with semantics obviously
+similar to their standard-library namesakes. Each one takes an extra parameter
+that is a copy of the allocator's private_data pointer.
+
+Note that realloc() and free() are not expected to be called directly by user
+code in most cases - they are primarily optimisations for use by data
+structures that wmem might want to implement (it's hard, for example, to
+implement a dynamically sized array without some form of realloc).
+
+4.1.3 Producer/Manager Functions
+
  - free_all()
+ - gc()
  - destroy()
- - private_data
- - type
 
-The private_data pointer is a void pointer that the implementation can use to
-store whatever internal structures it needs. The type field is an enumeration of
-type wmem_allocator_type_t (see section 3.1) set by the wmem_allocator_new()
-function. This field must NEVER be written to by the allocator implementation,
-although it may be read. The three function pointers should be fairly obvious;
-alloc and free_all are called with pointers to the private_data field, and
-destroy is called with a pointer to the allocator itself.
+The free_all() function takes the private_data pointer and should free all the
+memory currently allocated in the pool. Note that this is not necessarilly
+exactly the same as calling free() on all the allocated blocks - free_all() is
+allowed to do additional cleanup or to make use of optimizations not available
+when freeing one block at a time.
+
+The gc() function takes the private_data pointer and should do whatever it can
+to reduce excess memory usage in the dissector by returning unused blocks to
+the OS, optimizing internal data structures, etc.
+
+The destroy() function does NOT take the private_data pointer - it instead takes
+a pointer to the allocator structure as a whole, since that structure may also
+need freeing. This function can assume that free_all() has been called
+immediately before it (though it can make no assumptions about whether or not
+gc() has ever been called).
 
 4.2 Pool-Agnostic API