1/* Variable-sized buffer with on-stack default allocation.
2 Copyright (C) 2015-2017 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 <stddef.h>
62#include <stdlib.h>
63
64/* Scratch buffer. Must be initialized with scratch_buffer_init
65 before its use. */
66struct scratch_buffer {
67 void *data; /* Pointer to the beginning of the scratch area. */
68 size_t length; /* Allocated space at the data pointer, in bytes. */
69 char __space[1024]
70 __attribute__ ((aligned (__alignof__ (max_align_t))));
71};
72
73/* Initializes *BUFFER so that BUFFER->data points to BUFFER->__space
74 and BUFFER->length reflects the available space. */
75static inline void
76scratch_buffer_init (struct scratch_buffer *buffer)
77{
78 buffer->data = buffer->__space;
79 buffer->length = sizeof (buffer->__space);
80}
81
82/* Deallocates *BUFFER (if it was heap-allocated). */
83static inline void
84scratch_buffer_free (struct scratch_buffer *buffer)
85{
86 if (buffer->data != buffer->__space)
87 free (buffer->data);
88}
89
90/* Grow *BUFFER by some arbitrary amount. The buffer contents is NOT
91 preserved. Return true on success, false on allocation failure (in
92 which case the old buffer is freed). On success, the new buffer is
93 larger than the previous size. On failure, *BUFFER is deallocated,
94 but remains in a free-able state, and errno is set. */
95bool __libc_scratch_buffer_grow (struct scratch_buffer *buffer);
96libc_hidden_proto (__libc_scratch_buffer_grow)
97
98/* Alias for __libc_scratch_buffer_grow. */
99static __always_inline bool
100scratch_buffer_grow (struct scratch_buffer *buffer)
101{
102 return __glibc_likely (__libc_scratch_buffer_grow (buffer));
103}
104
105/* Like __libc_scratch_buffer_grow, but preserve the old buffer
106 contents on success, as a prefix of the new buffer. */
107bool __libc_scratch_buffer_grow_preserve (struct scratch_buffer *buffer);
108libc_hidden_proto (__libc_scratch_buffer_grow_preserve)
109
110/* Alias for __libc_scratch_buffer_grow_preserve. */
111static __always_inline bool
112scratch_buffer_grow_preserve (struct scratch_buffer *buffer)
113{
114 return __glibc_likely (__libc_scratch_buffer_grow_preserve (buffer));
115}
116
117/* Grow *BUFFER so that it can store at least NELEM elements of SIZE
118 bytes. The buffer contents are NOT preserved. Both NELEM and SIZE
119 can be zero. Return true on success, false on allocation failure
120 (in which case the old buffer is freed, but *BUFFER remains in a
121 free-able state, and errno is set). It is unspecified whether this
122 function can reduce the array size. */
123bool __libc_scratch_buffer_set_array_size (struct scratch_buffer *buffer,
124 size_t nelem, size_t size);
125libc_hidden_proto (__libc_scratch_buffer_set_array_size)
126
127/* Alias for __libc_scratch_set_array_size. */
128static __always_inline bool
129scratch_buffer_set_array_size (struct scratch_buffer *buffer,
130 size_t nelem, size_t size)
131{
132 return __glibc_likely (__libc_scratch_buffer_set_array_size
133 (buffer, nelem, size));
134}
135
136#endif /* _SCRATCH_BUFFER_H */
137