ucx: ucx/allocator.h@151f5345f303 (annotated)

ucx/allocator.h@151f5345f303 (annotated)

ucx/allocator.h

Wed, 17 Jul 2013 20:03:01 +0200

author: Mike Becker <universe@uap-core.de>
date: Wed, 17 Jul 2013 20:03:01 +0200
changeset 118: 151f5345f303
parent 107: 86b19c98b5fd
child 120: 8170f658f017
permissions: -rw-r--r--

documented allocator + some further documentation for sstr_t

 /*
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
  *
  * Copyright 2013 Olaf Wintermann. All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are met:
  *
  *   1. Redistributions of source code must retain the above copyright
  *      notice, this list of conditions and the following disclaimer.
  *
  *   2. Redistributions in binary form must reproduce the above copyright
  *      notice, this list of conditions and the following disclaimer in the
  *      documentation and/or other materials provided with the distribution.
  *
  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  * 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 <code>malloc(), calloc(), realloc()</code> and <code>free()</code>.
  *
  * 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 UCX_ALLOCATOR_H
 #define	UCX_ALLOCATOR_H
 #include "ucx.h"
 #ifdef	__cplusplus
 extern "C" {
 #endif
 /**
  * A function pointer to the allocators <code>malloc()</code> function.
  * @see UcxAllocator
  */
 typedef void*(*ucx_allocator_malloc)(void *pool, size_t n);
 /**
  * A function pointer to the allocators <code>calloc()</code> function.
  * @see UcxAllocator
  */
 typedef void*(*ucx_allocator_calloc)(void *pool, size_t n, size_t size);
 /**
  * A function pointer to the allocators <code>realloc()</code> function.
  * @see UcxAllocator
  */
 typedef void*(*ucx_allocator_realloc)(void *pool, void *data, size_t n);
 /**
  * A function pointer to the allocators <code>free()</code> 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 <code>malloc()</code> function for this allocator.
      */
     ucx_allocator_malloc  malloc;
     /**
      * The <code>calloc()</code> function for this allocator.
      */
     ucx_allocator_calloc  calloc;
     /**
      * The <code>realloc()</code> function for this allocator.
      */
     ucx_allocator_realloc realloc;
     /**
      * The <code>free()</code> 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 <code>malloc()</code> function.
  * @param ignore ignored (may be used by allocators for pooled memory)
  * @param n argument passed to <code>malloc()</code>
  * @return return value of <code>malloc()</code>
  */
 void *ucx_default_malloc(void *ignore, size_t n);
 /**
  * A wrapper for the standard libc <code>calloc()</code> function.
  * @param ignore ignored (may be used by allocators for pooled memory)
  * @param n argument passed to <code>calloc()</code>
  * @param size  argument passed to <code>calloc()</code>
  * @return return value of <code>calloc()</code>
  */
 void *ucx_default_calloc(void *ignore, size_t n, size_t size);
 /**
  * A wrapper for the standard libc <code>realloc()</code> function.
  * @param ignore ignored (may be used by allocators for pooled memory)
  * @param data argumend passed to <code>realloc()</code>
  * @param n argument passed to <code>realloc()</code>
  * @return return value of <code>realloc()</code>
  */
 void *ucx_default_realloc(void *ignore, void *data, size_t n);
 /**
  * A wrapper for the standard libc <code>free()</code> function.
  * @param ignore ignored (may be used by allocators for pooled memory)
  * @param data argument passed to <code>free()</code>
  * @return return value of <code>free()</code>
  */
 void ucx_default_free(void *ignore, void *data);
 /**
  * Convenient macro for a default allocator <code>struct</code> definition.
  */
 #define UCX_ALLOCATOR_DEFAULT {NULL, \
         ucx_default_malloc, ucx_default_calloc, ucx_default_realloc, \
         ucx_default_free }
 #ifdef	__cplusplus
 }
 #endif
 #endif	/* UCX_ALLOCATOR_H */

Mercurial > hg > ucx / annotate

ucx/allocator.h@151f5345f303 (annotated)

ucx/allocator.h