# HG changeset patch # User Mike Becker # Date 1374084181 -7200 # Node ID 151f5345f3034b3980aa05b8a9e8fef53269f457 # Parent ec0ae0c8854e047ad3d080a880e50c64b1fb9f4e documented allocator + some further documentation for sstr_t diff -r ec0ae0c8854e -r 151f5345f303 ucx/allocator.h --- a/ucx/allocator.h Wed Jul 17 16:17:42 2013 +0200 +++ b/ucx/allocator.h Wed Jul 17 20:03:01 2013 +0200 @@ -25,9 +25,32 @@ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. */ +/** + * Allocator for custom memory management. + * + * An UCX allocator consists of a pointer to the memory area / pool and four + * function pointers to memory management functions operating on this memory + * area / pool. These functions shall behave equivalent to the standard libc + * functions malloc(), calloc(), realloc() and free(). + * + * The signature of the memory management functions is based on the signature + * of the respective libc function but each of them takes the pointer to the + * memory area / pool as first argument. + * + * As the pointer to the memory area / pool can be arbitrarily chosen, any data + * can be provided to the memory management functions. An UcxMempool is just + * one example. + * + * @see mempool.h + * @see UcxMap + * + * @file allocator.h + * @author Mike Becker + * @author Olaf Wintermann + */ -#ifndef ALLOCATOR_H -#define ALLOCATOR_H +#ifndef UCX_ALLOCATOR_H +#define UCX_ALLOCATOR_H #include "ucx.h" @@ -35,26 +58,105 @@ extern "C" { #endif +/** + * A function pointer to the allocators malloc() function. + * @see UcxAllocator + */ typedef void*(*ucx_allocator_malloc)(void *pool, size_t n); +/** + * A function pointer to the allocators calloc() function. + * @see UcxAllocator + */ typedef void*(*ucx_allocator_calloc)(void *pool, size_t n, size_t size); +/** + * A function pointer to the allocators realloc() function. + * @see UcxAllocator + */ typedef void*(*ucx_allocator_realloc)(void *pool, void *data, size_t n); +/** + * A function pointer to the allocators free() function. + * @see UcxAllocator + */ typedef void(*ucx_allocator_free)(void *pool, void *data); +/** + * UCX allocator data structure containing memory management functions. + */ typedef struct { + /** Pointer to an area of memory or a complex memory pool. + * This pointer will be passed to any memory management function as first + * argument. + */ void *pool; + /** + * The malloc() function for this allocator. + */ ucx_allocator_malloc malloc; + /** + * The calloc() function for this allocator. + */ ucx_allocator_calloc calloc; + /** + * The realloc() function for this allocator. + */ ucx_allocator_realloc realloc; + /** + * The free() function for this allocator. + */ ucx_allocator_free free; } UcxAllocator; +/** + * Returns a pointer to the default allocator. + * + * The default allocator contains wrappers to the standard libc memory + * management functions. Use this function to get a pointer to a globally + * available allocator. You may also define an own UcxAllocator by assigning + * #UCX_ALLOCATOR_DEFAULT to a variable and pass the address of this variable + * to any function that takes an UcxAllocator as argument. Note that using + * this function is the recommended way of passing a default allocator, thus + * it never runs out of scope. + * + * @return a pointer to the default allocator + * + * @see UCX_ALLOCATOR_DEFAULT + */ UcxAllocator *ucx_default_allocator(); +/** + * A wrapper for the standard libc malloc() function. + * @param ignore ignored (may be used by allocators for pooled memory) + * @param n argument passed to malloc() + * @return return value of malloc() + */ void *ucx_default_malloc(void *ignore, size_t n); +/** + * A wrapper for the standard libc calloc() function. + * @param ignore ignored (may be used by allocators for pooled memory) + * @param n argument passed to calloc() + * @param size argument passed to calloc() + * @return return value of calloc() + */ void *ucx_default_calloc(void *ignore, size_t n, size_t size); +/** + * A wrapper for the standard libc realloc() function. + * @param ignore ignored (may be used by allocators for pooled memory) + * @param data argumend passed to realloc() + * @param n argument passed to realloc() + * @return return value of realloc() + */ void *ucx_default_realloc(void *ignore, void *data, size_t n); +/** + * A wrapper for the standard libc free() function. + * @param ignore ignored (may be used by allocators for pooled memory) + * @param data argument passed to free() + * @return return value of free() + */ void ucx_default_free(void *ignore, void *data); +/** + * Convenient macro for a default allocator struct definition. + */ #define UCX_ALLOCATOR_DEFAULT {NULL, \ ucx_default_malloc, ucx_default_calloc, ucx_default_realloc, \ ucx_default_free } @@ -63,5 +165,5 @@ } #endif -#endif /* ALLOCATOR_H */ +#endif /* UCX_ALLOCATOR_H */ diff -r ec0ae0c8854e -r 151f5345f303 ucx/string.h --- a/ucx/string.h Wed Jul 17 16:17:42 2013 +0200 +++ b/ucx/string.h Wed Jul 17 20:03:01 2013 +0200 @@ -183,12 +183,48 @@ * malloc(). So developers MUST pass the sstr_t.ptr to * free(). * + * The sstr_t.ptr of the return value will always be NULL- + * terminated. + * * @param string the string to duplicate - * @return a duplicate of the argument + * @return a duplicate of the string */ sstr_t sstrdup(sstr_t string); -sstr_t sstrdupa(UcxAllocator *allocator, sstr_t s); + +/** + * Creates a duplicate of the specified string using an UcxAllocator. + * + * The new sstr_t will contain a copy allocated by the allocators + * ucx_allocator_malloc function. So it is implementation depended, whether the + * returned sstr_t.ptr pointer must be passed to the allocators + * ucx_allocator_free function manually. + * + * The sstr_t.ptr of the return value will always be NULL- + * terminated. + * + * @param allocator a valid instance of an UcxAllocator + * @param string the string to duplicate + * @return a duplicate of the string + */ +sstr_t sstrdupa(UcxAllocator *allocator, sstr_t string); +/** + * Omits leading and trailing spaces. + * + * This function returns a new sstr_t containing a trimmed version of the + * specified string. + * + * Note: the new sstr_t references the same memory, thus you + * MUST NOT pass the sstr_t.ptr of the return value to + * free(). It is also highly recommended to avoid assignments like + * mystr = sstrtrim(mystr); as you lose the reference to the + * source string. Assignments of this type are only permitted, if the + * sstr_t.ptr of the source string does not need to be freed or if another + * reference to the source string exists. + * + * @param string the string that shall be trimmed + * @return a new sstr_t containing the trimmed string + */ sstr_t sstrtrim(sstr_t string); #ifdef __cplusplus