src/libcaptive/include/captive/macros.h

   1 /* $Id$
   2  * Include file with general macros and typedefs used through Captive project
   3  * Copyright (C) 2002 Jan Kratochvil <project-captive@jankratochvil.net>
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; exactly version 2 of June 1991 is required
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with this program; if not, write to the Free Software
  16  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  17  */
  18
  19
  20 #ifndef _CAPTIVE_MACROS_H
  21 #define _CAPTIVE_MACROS_H 1
  22
  23
  24 #include <glib/gmacros.h>
  25 #include <glib/gmem.h>
  26 #include <stdarg.h>
  27 #include <string.h>     /* for memset() */
  28 #include <glib/galloca.h>
  29
  30
  31 G_BEGIN_DECLS
  32
  33 /**
  34  * CAPTIVE_FAKEUSE:
  35  *
  36  * Prevent 'might be used uninitialized' warning.
  37  * Macro will fakes the use of the variable as sometimes GCC can't code flow
  38  * analyse #C correctly.
  39  *
  40  * <informalexample>
  41  * <programlisting>
  42  * g_some_type some_variable CAPTIVE_FAKEUSE;
  43  * </programlisting>
  44  * </informalexample>
  45  */
  46 #define CAPTIVE_FAKEUSE =0
  47
  48
  49 /**
  50  * captive_newn:
  51  * @objp: Variable with the pointer to the objects wished to be allocated.
  52  * Original value is discarded.
  53  * @n: Numbers of objects to be allocated. Value %0 is permitted (%NULL assignment effect).
  54  *
  55  * Macro to allocate @n objects of type *@objp and to assign the resulting pointer to @objp.
  56  * Allocated memory may contain garbage.
  57  *
  58  * @Returns: Initialized @objp value as the memory of size #sizeof(typeof(*objp))*n.
  59  * Value %NULL is returned iff @n==%0;
  60  */
  61 #define captive_newn(objp,n) ((objp)=g_new(typeof(*(objp)),(n)))
  62
  63
  64 /**
  65  * captive_new0n:
  66  * @objp: Variable with the pointer to the objects wished to be allocated and precleared.
  67  * Original value is discarded.
  68  * @n: Numbers of objects to be allocated. Value %0 is permitted (%NULL assignment effect).
  69  *
  70  * Macro to allocate @n objects of type *@objp and to assign the resulting pointer to @objp.
  71  * Allocated memory is precleared.
  72  *
  73  * @Returns: Initialized @objp value as the cleared memory of size #sizeof(typeof(*objp))*n.
  74  * Value %NULL is returned iff @n==%0;
  75  */
  76 #define captive_new0n(objp,n) ((objp)=g_new0(typeof(*(objp)),(n)))
  77
  78
  79 /**
  80  * captive_renewn:
  81  * @objp: Variable with the pointer to the objects wished to be reallocated.
  82  * Value %NULL is permitted (g_malloc() effect).
  83  * @n: Numbers of objects to be allocated. Value %0 is permitted (g_free() effect).
  84  *
  85  * Macro to reallocate the original memory stored in @objp
  86  * to the size @n objects of type *@objp and to assign the resulting pointer to @objp.
  87  * New allocated space may contain garbage. Both @objp and @n can be nonexclusively
  88  * passed as zero.
  89  *
  90  * @Returns: Initialized @objp value as the memory of size #sizeof(typeof(*objp))*n.
  91  * Value %NULL is returned iff @n==%0;
  92  */
  93 #define captive_renewn(objp,n) ({ \
  94                 typeof(&(objp)) _captive_renewn_objpp=&(objp); \
  95                 *_captive_renewn_objpp=g_renew(typeof(*(objp)),*_captive_renewn_objpp,(n)); \
  96                 (*_captive_renewn_objpp); \
  97                 })
  98
  99
 100 /**
 101  * captive_new:
 102  * @objp: Variable with the pointer to the object wished to be allocated.
 103  * Original value is discarded.
 104  *
 105  * Macro to allocate one object of type *@objp and to assign the resulting pointer to @objp.
 106  * Allocated memory may contain garbage. Equivalent to captive_newn(objp,1) call.
 107  *
 108  * @Returns: Initialized @objp value as the memory of size #sizeof(typeof(*objp)).
 109  * Value %NULL is never returned.
 110  */
 111 #define captive_new(objp) (captive_newn((objp),1))
 112
 113
 114 /**
 115  * captive_new0:
 116  * @objp: Variable with the pointer to the object wished to be allocated and precleared.
 117  * Original value is discarded.
 118  *
 119  * Macro to allocate one object of type *@objp and to assign the resulting pointer to @objp.
 120  * Allocated memory is precleared. Equivalent to captive_new0n(objp,1) call.
 121  *
 122  * @Returns: Initialized @objp value as the cleared memory of size #sizeof(typeof(*objp)).
 123  * Value %NULL is never returned.
 124  */
 125 #define captive_new0(objp) (captive_new0n((objp),1))
 126
 127
 128 /**
 129  * captive_newn_alloca:
 130  * @objp: Variable with the pointer to the objects wished to be allocated.
 131  * Original value is discarded.
 132  * @n: Numbers of objects to be allocated. Value %0 is permitted (%NULL assignment effect).
 133  *
 134  * Macro to allocate @n objects of type *@objp and to assign the resulting pointer to @objp.
 135  * Allocated memory may contain garbage.
 136  *
 137  * Memory is allocated on the stack frame by g_alloca() and it will be automatically deallocated
 138  * during exit of current function (or current block if variable sized variables present there).
 139  * You cannot deallocate or reallocate such memory in any other way.
 140  *
 141  * @Returns: Initialized @objp value as the memory of size #sizeof(typeof(*objp))*n.
 142  * Value %NULL is returned iff @n==%0;
 143  */
 144 #define captive_newn_alloca(objp,n) ({ \
 145                 size_t _captive_newn_alloca_n=(n); \
 146                 /* Fix 'g_alloca(0)!=NULL': */ \
 147                 ((objp)=(!_captive_newn_alloca_n ? NULL : g_alloca(sizeof(*(objp))*_captive_newn_alloca_n))); \
 148                 })
 149
 150
 151 /**
 152  * captive_new0n_alloca:
 153  * @objp: Variable with the pointer to the objects wished to be allocated and precleared.
 154  * Original value is discarded.
 155  * @n: Numbers of objects to be allocated. Value %0 is permitted (%NULL assignment effect).
 156  *
 157  * Macro to allocate @n objects of type *@objp and to assign the resulting pointer to @objp.
 158  * Allocated memory is precleared.
 159  *
 160  * Memory is allocated on the stack frame by g_alloca() and it will be automatically deallocated
 161  * during exit of current function (or current block if variable sized variables present there).
 162  * You cannot deallocate or reallocate such memory in any other way.
 163  *
 164  * @Returns: Initialized @objp value as the cleared memory of size #sizeof(typeof(*objp))*n.
 165  * Value %NULL is returned iff @n==%0;
 166  */
 167 #define captive_new0n_alloca(objp,n) ({ \
 168                 typeof(&(objp)) _captive_new0n_alloca_objpp=&(objp); \
 169                 captive_newn_alloca(*_captive_new0n_alloca_objpp,(n)); \
 170                 CAPTIVE_MEMZERO(*_captive_new0n_alloca_objpp); \
 171                 (*_captive_new0n_alloca_objpp); \
 172                 })
 173
 174
 175 /**
 176  * captive_new_alloca:
 177  * @objp: Variable with the pointer to the object wished to be allocated.
 178  * Original value is discarded.
 179  *
 180  * Macro to allocate one object of type *@objp and to assign the resulting pointer to @objp.
 181  * Allocated memory may contain garbage. Equivalent to captive_newn_alloca(objp,1) call.
 182  *
 183  * Memory is allocated on the stack frame by g_alloca() and it will be automatically deallocated
 184  * during exit of current function (or current block if variable sized variables present there).
 185  * You cannot deallocate or reallocate such memory in any other way.
 186  *
 187  * @Returns: Initialized @objp value as the memory of size #sizeof(typeof(*objp)).
 188  * Value %NULL is never returned.
 189  */
 190 #define captive_new_alloca(objp) (captive_newn_alloca((objp),1))
 191
 192
 193 /**
 194  * captive_new0_alloca:
 195  * @objp: Variable with the pointer to the object wished to be allocated and precleared.
 196  * Original value is discarded.
 197  *
 198  * Macro to allocate one object of type *@objp and to assign the resulting pointer to @objp.
 199  * Allocated memory is precleared. Equivalent to captive_new0n_alloca(objp,1) call.
 200  *
 201  * @Returns: Initialized @objp value as the cleared memory of size #sizeof(typeof(*objp)).
 202  */
 203 #define captive_new0_alloca(objp) (captive_new0n_alloca((objp),1))
 204
 205
 206 /**
 207  * captive_va_arg:
 208  * @objp: Variable to be filled from the next argument of @ap.
 209  * @ap: Initialized #va_list type.
 210  *
 211  * Automatically determines the size of @objp.
 212  * Equivalent to objp=va_arg(ap,typeof(objp)) call.
 213  *
 214  * @Returns: Initialized @objp value.
 215  */
 216 #define captive_va_arg(objp,ap) ((objp)=va_arg((ap),typeof(objp)))
 217
 218
 219 /**
 220  * CAPTIVE_MEMZERO:
 221  * @objp: Pointer to the variable to be cleared.
 222  *
 223  * Clears the sizeof(*@objp) bytes of the given pointer with memset().
 224  * Pass _pointer_ to the object to be cleared.
 225  */
 226 #define CAPTIVE_MEMZERO(objp) (memset((objp),0,sizeof(*(objp))))
 227
 228 G_END_DECLS
 229
 230
 231 #endif /* _CAPTIVE_MACROS_H */