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 #if !defined ALIGNMENT
  55 # error "ALIGNMENT is not defined"
  56 #endif
  57 #if !((ALIGNMENT) > 0 && ((ALIGNMENT) & ((ALIGNMENT) - 1)) == 0)
  58 # error "ALIGNMENT is not a power of 2"
  59 #endif
  60 #if ((ALIGNMENT) <= MALLOC_ALIGNMENT) || HAVE_POSIX_MEMALIGN || HAVE_ALIGNED_ALLOC || HAVE_MEMALIGN
  61
  62 # if defined aligned_free || __GNUC__ >= 11
  63    /* The caller wants an inline function, not a macro,
  64       or we can use GCC's -Wmismatched-dealloc warning.  */
  65 static inline void
  66 aligned_free (void *q)
  67 {
  68   free (q);
  69 }
  70 # else
  71 #  define aligned_free free
  72 # endif
  73
  74 # if (ALIGNMENT) <= MALLOC_ALIGNMENT
  75 /* Simply use malloc.  */
  76
  77 #  if defined aligned_malloc || __GNUC__ >= 11
  78    /* The caller wants an inline function, not a macro,
  79       or GCC's -Wmismatched-dealloc warning might be in effect.  */
  80 static inline
  81 /*_GL_ATTRIBUTE_DEALLOC (aligned_free, 1)*/
  82 void *
  83 aligned_malloc (size_t size)
  84 {
  85   return malloc (size);
  86 }
  87 #  else
  88 #   define aligned_malloc malloc
  89 #  endif
  90
  91 # elif HAVE_POSIX_MEMALIGN
  92 /* Use posix_memalign.
  93    This is OK since ALIGNMENT > MALLOC_ALIGNMENT >= sizeof (void *).  */
  94
  95 static inline
  96 /*_GL_ATTRIBUTE_DEALLOC (aligned_free, 1)*/
  97 void *
  98 aligned_malloc (size_t size)
  99 {
 100   void *p;
 101   int ret = posix_memalign (&p, (ALIGNMENT), size);
 102   if (ret == 0)
 103     return p;
 104   else
 105     return NULL;
 106 }
 107
 108 # elif HAVE_ALIGNED_ALLOC
 109 /* Use aligned_alloc.  */
 110
 111 static inline
 112 /*_GL_ATTRIBUTE_DEALLOC (aligned_free, 1)*/
 113 void *
 114 aligned_malloc (size_t size)
 115 {
 116   /* Round up SIZE to the next multiple of ALIGNMENT,
 117      namely (SIZE + ALIGNMENT - 1) & ~(ALIGNMENT - 1).  */
 118   size += (ALIGNMENT) - 1;
 119   if (size >= (ALIGNMENT) - 1) /* no overflow? */
 120     {
 121       size &= ~(size_t)((ALIGNMENT) - 1);
 122       return aligned_alloc ((ALIGNMENT), size);
 123     }
 124   return NULL;
 125 }
 126
 127 # elif HAVE_MEMALIGN                    /* HP-UX, IRIX, Solaris <= 10 */
 128 /* Use memalign.  */
 129
 130 static inline
 131 /*_GL_ATTRIBUTE_DEALLOC (aligned_free, 1)*/
 132 void *
 133 aligned_malloc (size_t size)
 134 {
 135   return memalign ((ALIGNMENT), size);
 136 }
 137
 138 # endif
 139
 140 #else
 141 /* Use malloc and waste a bit of memory.  */
 142
 143 static inline void
 144 aligned_free (void *q)
 145 {
 146   if (q != NULL)
 147     {
 148       if ((uintptr_t) q & ((ALIGNMENT) - 1))
 149         /* Argument not aligned as expected.  */
 150         abort ();
 151       else
 152         {
 153           void *p = ((void **) q)[-1];
 154           if (!((uintptr_t) p <= (uintptr_t) q
 155                 && (uintptr_t) q - (uintptr_t) p >= MALLOC_ALIGNMENT
 156                 && (uintptr_t) q - (uintptr_t) p <= (ALIGNMENT)))
 157             abort ();
 158           free (p);
 159         }
 160     }
 161 }
 162
 163 static inline
 164 /*_GL_ATTRIBUTE_DEALLOC (aligned_free, 1)*/
 165 void *
 166 aligned_malloc (size_t size)
 167 {
 168   size += (ALIGNMENT);
 169   if (size >= (ALIGNMENT)) /* no overflow? */
 170     {
 171       void *p = malloc (size);
 172       if (p != NULL)
 173         {
 174           /* Go to the next multiple of ALIGNMENT.  */
 175           void *q =
 176             (void *) (((uintptr_t) p + (ALIGNMENT)) & -(intptr_t)(ALIGNMENT));
 177           /* Now q - p <= ALIGNMENT and
 178              q - p >= MALLOC_ALIGNMENT >= sizeof (void *).
 179              This is enough to store a back pointer to p.  */
 180           ((void **) q)[-1] = p;
 181           return q;
 182         }
 183     }
 184   return NULL;
 185 }
 186
 187 #endif