include/scratch_buffer.h

   1 /* Variable-sized buffer with on-stack default allocation.
   2    Copyright (C) 2015 Free Software Foundation, Inc.
   3    This file is part of the GNU C Library.
   4
   5    The GNU C Library is free software; you can redistribute it and/or
   6    modify it under the terms of the GNU Lesser General Public
   7    License as published by the Free Software Foundation; either
   8    version 2.1 of the License, or (at your option) any later version.
   9
  10    The GNU C Library 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 GNU
  13    Lesser General Public License for more details.
  14
  15    You should have received a copy of the GNU Lesser General Public
  16    License along with the GNU C Library; if not, see
  17    <http://www.gnu.org/licenses/>.  */
  18
  19 #ifndef _SCRATCH_BUFFER_H
  20 #define _SCRATCH_BUFFER_H
  21
  22 /* Scratch buffers with a default stack allocation and fallback to
  23    heap allocation.  It is expected that this function is used in this
  24    way:
  25
  26      struct scratch_buffer tmpbuf;
  27      scratch_buffer_init (&tmpbuf);
  28
  29      while (!function_that_uses_buffer (tmpbuf.data, tmpbuf.length))
  30        if (!scratch_buffer_grow (&tmpbuf))
  31          return -1;
  32
  33      scratch_buffer_free (&tmpbuf);
  34      return 0;
  35
  36    The allocation functions (scratch_buffer_grow,
  37    scratch_buffer_grow_preserve, scratch_buffer_set_array_size) make
  38    sure that the heap allocation, if any, is freed, so that the code
  39    above does not have a memory leak.  The buffer still remains in a
  40    state that can be deallocated using scratch_buffer_free, so a loop
  41    like this is valid as well:
  42
  43      struct scratch_buffer tmpbuf;
  44      scratch_buffer_init (&tmpbuf);
  45
  46      while (!function_that_uses_buffer (tmpbuf.data, tmpbuf.length))
  47        if (!scratch_buffer_grow (&tmpbuf))
  48          break;
  49
  50      scratch_buffer_free (&tmpbuf);
  51
  52    scratch_buffer_grow and scratch_buffer_grow_preserve are guaranteed
  53    to grow the buffer by at least 512 bytes.  This means that when
  54    using the scratch buffer as a backing store for a non-character
  55    array whose element size, in bytes, is 512 or smaller, the scratch
  56    buffer only has to grow once to make room for at least one more
  57    element.
  58 */
  59
  60 #include <stdbool.h>
  61 #include <stdlib.h>
  62
  63 #include <libc-internal.h>
  64
  65 /* Scratch buffer.  Must be initialized with scratch_buffer_init
  66    before its use.  */
  67 struct scratch_buffer {
  68   void *data;    /* Pointer to the beginning of the scratch area.  */
  69   size_t length; /* Allocated space at the data pointer, in bytes.  */
  70   char __space[1024]
  71     __attribute__ ((aligned (__alignof__ (libc_max_align_t))));
  72 };
  73
  74 /* Initializes *BUFFER so that BUFFER->data points to BUFFER->__space
  75    and BUFFER->length reflects the available space.  */
  76 static inline void
  77 scratch_buffer_init (struct scratch_buffer *buffer)
  78 {
  79   buffer->data = buffer->__space;
  80   buffer->length = sizeof (buffer->__space);
  81 }
  82
  83 /* Deallocates *BUFFER (if it was heap-allocated).  */
  84 static inline void
  85 scratch_buffer_free (struct scratch_buffer *buffer)
  86 {
  87   if (buffer->data != buffer->__space)
  88     free (buffer->data);
  89 }
  90
  91 /* Grow *BUFFER by some arbitrary amount.  The buffer contents is NOT
  92    preserved.  Return true on success, false on allocation failure (in
  93    which case the old buffer is freed).  On success, the new buffer is
  94    larger than the previous size.  On failure, *BUFFER is deallocated,
  95    but remains in a free-able state, and errno is set.  */
  96 bool __libc_scratch_buffer_grow (struct scratch_buffer *buffer);
  97 libc_hidden_proto (__libc_scratch_buffer_grow)
  98
  99 /* Alias for __libc_scratch_buffer_grow.  */
 100 static __always_inline bool
 101 scratch_buffer_grow (struct scratch_buffer *buffer)
 102 {
 103   return __glibc_likely (__libc_scratch_buffer_grow (buffer));
 104 }
 105
 106 /* Like __libc_scratch_buffer_grow, but preserve the old buffer
 107    contents on success, as a prefix of the new buffer.  */
 108 bool __libc_scratch_buffer_grow_preserve (struct scratch_buffer *buffer);
 109 libc_hidden_proto (__libc_scratch_buffer_grow_preserve)
 110
 111 /* Alias for __libc_scratch_buffer_grow_preserve.  */
 112 static __always_inline bool
 113 scratch_buffer_grow_preserve (struct scratch_buffer *buffer)
 114 {
 115   return __glibc_likely (__libc_scratch_buffer_grow_preserve (buffer));
 116 }
 117
 118 /* Grow *BUFFER so that it can store at least NELEM elements of SIZE
 119    bytes.  The buffer contents are NOT preserved.  Both NELEM and SIZE
 120    can be zero.  Return true on success, false on allocation failure
 121    (in which case the old buffer is freed, but *BUFFER remains in a
 122    free-able state, and errno is set).  It is unspecified whether this
 123    function can reduce the array size.  */
 124 bool __libc_scratch_buffer_set_array_size (struct scratch_buffer *buffer,
 125                                            size_t nelem, size_t size);
 126 libc_hidden_proto (__libc_scratch_buffer_set_array_size)
 127
 128 /* Alias for __libc_scratch_set_array_size.  */
 129 static __always_inline bool
 130 scratch_buffer_set_array_size (struct scratch_buffer *buffer,
 131                                size_t nelem, size_t size)
 132 {
 133   return __glibc_likely (__libc_scratch_buffer_set_array_size
 134                          (buffer, nelem, size));
 135 }
 136
 137 #endif /* _SCRATCH_BUFFER_H */