include/sphinxbase/ckd_alloc.h

   1 /* -*- c-basic-offset: 4; indent-tabs-mode: nil -*- */
   2 /* ====================================================================
   3  * Copyright (c) 1999-2004 Carnegie Mellon University.  All rights
   4  * reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions
   8  * are met:
   9  *
  10  * 1. Redistributions of source code must retain the above copyright
  11  *    notice, this list of conditions and the following disclaimer.
  12  *
  13  * 2. Redistributions in binary form must reproduce the above copyright
  14  *    notice, this list of conditions and the following disclaimer in
  15  *    the documentation and/or other materials provided with the
  16  *    distribution.
  17  *
  18  * This work was supported in part by funding from the Defense Advanced
  19  * Research Projects Agency and the National Science Foundation of the
  20  * United States of America, and the CMU Sphinx Speech Consortium.
  21  *
  22  * THIS SOFTWARE IS PROVIDED BY CARNEGIE MELLON UNIVERSITY ``AS IS'' AND
  23  * ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  24  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  25  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY
  26  * NOR ITS EMPLOYEES BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  27  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  28  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  29  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  30  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  31  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  32  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  33  *
  34  * ====================================================================
  35  *
  36  */
  37 /*
  38  * ckd_alloc.h -- Memory allocation package.
  39  *
  40  * **********************************************
  41  * CMU ARPA Speech Project
  42  *
  43  * Copyright (c) 1999 Carnegie Mellon University.
  44  * ALL RIGHTS RESERVED.
  45  * **********************************************
  46  *
  47  * HISTORY
  48  * $Log: ckd_alloc.h,v $
  49  * Revision 1.10  2005/06/22 02:59:25  arthchan2003
  50  * Added  keyword
  51  *
  52  * Revision 1.3  2005/03/30 01:22:48  archan
  53  * Fixed mistakes in last updates. Add
  54  *
  55  *
  56  * 19-Jun-97    M K Ravishankar (rkm@cs.cmu.edu) at Carnegie Mellon University
  57  *              Removed file,line arguments from free functions.
  58  *
  59  * 01-Jan-96    M K Ravishankar (rkm@cs.cmu.edu) at Carnegie Mellon University
  60  *              Created.
  61  */
  62
  63
  64 /*********************************************************************
  65  *
  66  * $Header: /cvsroot/cmusphinx/sphinx3/src/libutil/ckd_alloc.h,v 1.10 2005/06/22 02:59:25 arthchan2003 Exp $
  67  *
  68  * Carnegie Mellon ARPA Speech Group
  69  *
  70  * Copyright (c) 1994 Carnegie Mellon University.
  71  * All rights reserved.
  72  *
  73  *********************************************************************
  74  *
  75  * file: ckd_alloc.h
  76  *
  77  * traceability:
  78  *
  79  * description:
  80  *
  81  * author:
  82  *
  83  *********************************************************************/
  84
  85
  86 #ifndef _LIBUTIL_CKD_ALLOC_H_
  87 #define _LIBUTIL_CKD_ALLOC_H_
  88
  89 #include <stdlib.h>
  90 #include <setjmp.h>
  91
  92 /* Win32/WinCE DLL gunk */
  93 #include <sphinxbase/sphinxbase_export.h>
  94 #include <sphinxbase/prim_type.h>
  95
  96 /** \file ckd_alloc.h
  97  *\brief Sphinx's memory allocation/deallocation routines.
  98  *
  99  *Implementation of efficient memory allocation deallocation for
 100  *multiple dimensional arrays.
 101  *
 102  */
 103
 104 #ifdef __cplusplus
 105 extern "C" {
 106 #endif
 107 #if 0
 108 /* Fool Emacs. */
 109 }
 110 #endif
 111
 112 /**
 113  * Control behaviour of the program when allocation fails.
 114  *
 115  * Although your program is probably toast when memory allocation
 116  * fails, it is also probably a good idea to be able to catch these
 117  * errors and alert the user in some way.  Either that, or you might
 118  * want the program to call abort() so that you can debug the failed
 119  * code.  This function allows you to control that behaviour.
 120  *
 121  * @param env Pointer to a <code>jmp_buf</code> initialized with
 122  * setjmp(), or NULL to remove a previously set jump target.
 123  * @param abort If non-zero, the program will call abort() when
 124  * allocation fails rather than exiting or calling longjmp().
 125  * @return Pointer to a previously set <code>jmp_buf</code>, if any.
 126  */
 127 jmp_buf *ckd_set_jump(jmp_buf *env, int abort);
 128
 129 /**
 130  * Fail (with a message) according to behaviour specified by ckd_set_jump().
 131  */
 132 void ckd_fail(char *format, ...);
 133
 134 /*
 135  * The following functions are similar to the malloc family, except
 136  * that they have two additional parameters, caller_file and
 137  * caller_line, for error reporting.  All functions print a diagnostic
 138  * message if any error occurs, with any other behaviour determined by
 139  * ckd_set_jump(), above.
 140  */
 141
 142 SPHINXBASE_EXPORT
 143 void *__ckd_calloc__(size_t n_elem, size_t elem_size,
 144                      const char *caller_file, int caller_line);
 145
 146 SPHINXBASE_EXPORT
 147 void *__ckd_malloc__(size_t size,
 148                      const char *caller_file, int caller_line);
 149
 150 SPHINXBASE_EXPORT
 151 void *__ckd_realloc__(void *ptr, size_t new_size,
 152                       const char *caller_file, int caller_line);
 153
 154 /**
 155  * Like strdup, except that if an error occurs it prints a diagnostic message
 156  * and exits.
 157  */
 158 SPHINXBASE_EXPORT
 159 char *__ckd_salloc__(const char *origstr,
 160                      const char *caller_file, int caller_line);
 161
 162 /**
 163  * Allocate a 2-D array and return ptr to it (ie, ptr to vector of ptrs).
 164  * The data area is allocated in one block so it can also be treated as a 1-D array.
 165  */
 166 SPHINXBASE_EXPORT
 167 void *__ckd_calloc_2d__(size_t d1, size_t d2,   /* In: #elements in the 2 dimensions */
 168                         size_t elemsize,        /* In: Size (#bytes) of each element */
 169                         const char *caller_file, int caller_line);      /* In */
 170
 171 /**
 172  * Allocate a 3-D array and return ptr to it.
 173  * The data area is allocated in one block so it can also be treated as a 1-D array.
 174  */
 175 SPHINXBASE_EXPORT
 176 void *__ckd_calloc_3d__(size_t d1, size_t d2, size_t d3,        /* In: #elems in the dims */
 177                         size_t elemsize,                /* In: Size (#bytes) per element */
 178                         const char *caller_file, int caller_line);      /* In */
 179
 180 /**
 181  * Allocate a 34D array and return ptr to it.
 182  * The data area is allocated in one block so it can also be treated as a 1-D array.
 183  */
 184 SPHINXBASE_EXPORT
 185 void ****__ckd_calloc_4d__(size_t d1,
 186                            size_t d2,
 187                            size_t d3,
 188                            size_t d4,
 189                            size_t elem_size,
 190                            char *caller_file,
 191                            int caller_line);
 192
 193 /**
 194  * Overlay a 3-D array over a previously allocated storage area.
 195  **/
 196 SPHINXBASE_EXPORT
 197 void * __ckd_alloc_3d_ptr(size_t d1,
 198                           size_t d2,
 199                           size_t d3,
 200                           void *store,
 201                           size_t elem_size,
 202                           char *caller_file,
 203                           int caller_line);
 204
 205 /**
 206  * Overlay a s-D array over a previously allocated storage area.
 207  **/
 208 SPHINXBASE_EXPORT
 209 void *__ckd_alloc_2d_ptr(size_t d1,
 210                          size_t d2,
 211                          void *store,
 212                          size_t elem_size,
 213                          char *caller_file,
 214                          int caller_line);
 215
 216 /**
 217  * Test and free a 1-D array
 218  */
 219 SPHINXBASE_EXPORT
 220 void ckd_free(void *ptr);
 221
 222 /**
 223  * Free a 2-D array (ptr) previously allocated by ckd_calloc_2d
 224  */
 225 SPHINXBASE_EXPORT
 226 void ckd_free_2d(void *ptr);
 227
 228 /**
 229  * Free a 3-D array (ptr) previously allocated by ckd_calloc_3d
 230  */
 231 SPHINXBASE_EXPORT
 232 void ckd_free_3d(void *ptr);
 233
 234 /**
 235  * Free a 4-D array (ptr) previously allocated by ckd_calloc_4d
 236  */
 237 SPHINXBASE_EXPORT
 238 void ckd_free_4d(void *ptr);
 239
 240 /**
 241  * Macros to simplify the use of above functions.
 242  * One should use these, rather than target functions directly.
 243  */
 244
 245 /**
 246  * Macro for __ckd_calloc__
 247  */
 248 #define ckd_calloc(n,sz)        __ckd_calloc__((n),(sz),__FILE__,__LINE__)
 249
 250 /**
 251  * Macro for __ckd_malloc__
 252  */
 253 #define ckd_malloc(sz)          __ckd_malloc__((sz),__FILE__,__LINE__)
 254
 255 /**
 256  * Macro for __ckd_realloc__
 257  */
 258 #define ckd_realloc(ptr,sz)     __ckd_realloc__(ptr,(sz),__FILE__,__LINE__)
 259
 260 /**
 261  * Macro for __ckd_salloc__
 262  */
 263
 264 #define ckd_salloc(ptr)         __ckd_salloc__(ptr,__FILE__,__LINE__)
 265
 266 /**
 267  * Macro for __ckd_calloc_2d__
 268  */
 269
 270 #define ckd_calloc_2d(d1,d2,sz) __ckd_calloc_2d__((d1),(d2),(sz),__FILE__,__LINE__)
 271
 272 /**
 273  * Macro for __ckd_calloc_3d__
 274  */
 275
 276 #define ckd_calloc_3d(d1,d2,d3,sz) __ckd_calloc_3d__((d1),(d2),(d3),(sz),__FILE__,__LINE__)
 277
 278 /**
 279  * Macro for __ckd_calloc_4d__
 280  */
 281 #define ckd_calloc_4d(d1, d2, d3, d4, s)  __ckd_calloc_4d__((d1), (d2), (d3), (d4), (s), __FILE__, __LINE__)
 282
 283 /**
 284  * Macro for __ckd_alloc_2d_ptr__
 285  */
 286
 287 #define ckd_alloc_2d_ptr(d1, d2, bf, sz)    __ckd_alloc_2d_ptr((d1), (d2), (bf), (sz), __FILE__, __LINE__)
 288
 289 /**
 290  * Free only the pointer arrays allocated with ckd_alloc_2d_ptr().
 291  */
 292 #define ckd_free_2d_ptr(bf) ckd_free(bf)
 293
 294 /**
 295  * Macro for __ckd_alloc_3d_ptr__
 296  */
 297
 298 #define ckd_alloc_3d_ptr(d1, d2, d3, bf, sz) __ckd_alloc_3d_ptr((d1), (d2), (d3), (bf), (sz), __FILE__, __LINE__)
 299
 300 /**
 301  * Free only the pointer arrays allocated with ckd_alloc_3d_ptr().
 302  */
 303 #define ckd_free_3d_ptr(bf) ckd_free_2d(bf)
 304
 305
 306 #ifdef __cplusplus
 307 }
 308 #endif
 309
 310 #endif