lib/aligned-malloc.h

   1 /* Allocate memory with indefinite extent and specified alignment.
   2
   3    Copyright (C) 2020-2024 Free Software Foundation, Inc.
   4
   5    This file is free software: you can redistribute it and/or modify
   6    it under the terms of the GNU Lesser General Public License as
   7    published by the Free Software Foundation; either version 2.1 of the
   8    License, or (at your option) any later version.
   9
  10    This file is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13    GNU Lesser General Public License for more details.
  14
  15    You should have received a copy of the GNU Lesser General Public License
  16    along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
  17
  18 /* Written by Bruno Haible <bruno@clisp.org>, 2020.  */
  19
  20 /* Before including this file, you need to define the following macro:
  21
  22    ALIGNMENT      A constant expression that evaluates to the desired alignment
  23                   (a power of 2).
  24
  25    And you also need to #include <stdint.h> and <stdlib.h>.  */
  26
  27 /* aligned_malloc allocates a block of memory of SIZE bytes, aligned on a
  28    boundary of ALIGNMENT bytes.
  29    The block can be freed through aligned_free(), NOT through free().
  30    Upon failure, it returns NULL.  */
  31
  32 /* This module exists instead of a posix_memalign(), aligned_alloc(), or
  33    memalign() emulation, because we can't reasonably emulate posix_memalign(),
  34    aligned_alloc(), or memalign():
  35    If malloc() returned p, only free (p) is allowed, not free (p + 1),
  36    free (p + 2), free (p + 4), free (p + 8), or similar.
  37
  38    We can use posix_memalign(), a POSIX function.
  39
  40    We can also use aligned_alloc(), an ISO C11 and POSIX function.  But it's
  41    a bit more awkward to use.
  42
  43    On older systems, we can alternatively use memalign() instead.  In the
  44    Solaris documentation of memalign() it is not specified how a memory block
  45    returned by memalign() can be freed, but it actually can be freed with
  46    free().  */
  47
  48 /* This file uses MALLOC_ALIGNMENT, HAVE_POSIX_MEMALIGN, HAVE_ALIGNED_ALLOC,
  49    HAVE_MEMALIGN.  */
  50 #if !_GL_CONFIG_H_INCLUDED
  51  #error "Please include config.h first."
  52 #endif
  53
  54 #ifdef __cplusplus
  55 extern "C" {
  56 #endif
  57
  58
  59 #if !defined ALIGNMENT
  60 # error "ALIGNMENT is not defined"
  61 #endif
  62 #if !((ALIGNMENT) > 0 && ((ALIGNMENT) & ((ALIGNMENT) - 1)) == 0)
  63 # error "ALIGNMENT is not a power of 2"
  64 #endif
  65 #if ((ALIGNMENT) <= MALLOC_ALIGNMENT) || HAVE_POSIX_MEMALIGN || HAVE_ALIGNED_ALLOC || HAVE_MEMALIGN
  66
  67 # if defined aligned_free || __GNUC__ >= 11
  68    /* The caller wants an inline function, not a macro,
  69       or we can use GCC's -Wmismatched-dealloc warning.  */
  70 static inline void
  71 aligned_free (void *q)
  72 {
  73   free (q);
  74 }
  75 # else
  76 #  define aligned_free free
  77 # endif
  78
  79 # if (ALIGNMENT) <= MALLOC_ALIGNMENT
  80 /* Simply use malloc.  */
  81
  82 #  if defined aligned_malloc || __GNUC__ >= 11
  83    /* The caller wants an inline function, not a macro,
  84       or GCC's -Wmismatched-dealloc warning might be in effect.  */
  85 static inline
  86 /*_GL_ATTRIBUTE_DEALLOC (aligned_free, 1)*/
  87 void *
  88 aligned_malloc (size_t size)
  89 {
  90   return malloc (size);
  91 }
  92 #  else
  93 #   define aligned_malloc malloc
  94 #  endif
  95
  96 # elif HAVE_POSIX_MEMALIGN
  97 /* Use posix_memalign.
  98    This is OK since ALIGNMENT > MALLOC_ALIGNMENT >= sizeof (void *).  */
  99
 100 static inline
 101 /*_GL_ATTRIBUTE_DEALLOC (aligned_free, 1)*/
 102 void *
 103 aligned_malloc (size_t size)
 104 {
 105   void *p;
 106   int ret = posix_memalign (&p, (ALIGNMENT), size);
 107   if (ret == 0)
 108     return p;
 109   else
 110     return NULL;
 111 }
 112
 113 # elif HAVE_ALIGNED_ALLOC
 114 /* Use aligned_alloc.  */
 115
 116 static inline
 117 /*_GL_ATTRIBUTE_DEALLOC (aligned_free, 1)*/
 118 void *
 119 aligned_malloc (size_t size)
 120 {
 121   /* Round up SIZE to the next multiple of ALIGNMENT,
 122      namely (SIZE + ALIGNMENT - 1) & ~(ALIGNMENT - 1).  */
 123   size += (ALIGNMENT) - 1;
 124   if (size >= (ALIGNMENT) - 1) /* no overflow? */
 125     {
 126       size &= ~(size_t)((ALIGNMENT) - 1);
 127       return aligned_alloc ((ALIGNMENT), size);
 128     }
 129   return NULL;
 130 }
 131
 132 # elif HAVE_MEMALIGN                    /* HP-UX, IRIX, Solaris <= 10 */
 133 /* Use memalign.  */
 134
 135 static inline
 136 /*_GL_ATTRIBUTE_DEALLOC (aligned_free, 1)*/
 137 void *
 138 aligned_malloc (size_t size)
 139 {
 140   return memalign ((ALIGNMENT), size);
 141 }
 142
 143 # endif
 144
 145 #else
 146 /* Use malloc and waste a bit of memory.  */
 147
 148 static inline void
 149 aligned_free (void *q)
 150 {
 151   if (q != NULL)
 152     {
 153       if ((uintptr_t) q & ((ALIGNMENT) - 1))
 154         /* Argument not aligned as expected.  */
 155         abort ();
 156       else
 157         {
 158           void *p = ((void **) q)[-1];
 159           if (!((uintptr_t) p <= (uintptr_t) q
 160                 && (uintptr_t) q - (uintptr_t) p >= MALLOC_ALIGNMENT
 161                 && (uintptr_t) q - (uintptr_t) p <= (ALIGNMENT)))
 162             abort ();
 163           free (p);
 164         }
 165     }
 166 }
 167
 168 static inline
 169 /*_GL_ATTRIBUTE_DEALLOC (aligned_free, 1)*/
 170 void *
 171 aligned_malloc (size_t size)
 172 {
 173   size += (ALIGNMENT);
 174   if (size >= (ALIGNMENT)) /* no overflow? */
 175     {
 176       void *p = malloc (size);
 177       if (p != NULL)
 178         {
 179           /* Go to the next multiple of ALIGNMENT.  */
 180           void *q =
 181             (void *) (((uintptr_t) p + (ALIGNMENT)) & -(intptr_t)(ALIGNMENT));
 182           /* Now q - p <= ALIGNMENT and
 183              q - p >= MALLOC_ALIGNMENT >= sizeof (void *).
 184              This is enough to store a back pointer to p.  */
 185           ((void **) q)[-1] = p;
 186           return q;
 187         }
 188     }
 189   return NULL;
 190 }
 191
 192 #endif
 193
 194
 195 #ifdef __cplusplus
 196 }
 197 #endif