/****************************************************************************
* include/obstack.h
*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership. The
* ASF licenses this file to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance with the
* License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations
* under the License.
*
****************************************************************************/
/* This is based on the GlibC API but the implementation is not exactly same.
* The major difference is how required memory is allocated. The GlibC
* implementation starts with 4KB of allocated space. That would make it
* impossible to use this on MCUs. This implementation rather tries to
* allocated only required amount of space and it won't allocate chunk unless
* grow functions are used and even then it uses realloc to release unused
* space. It also in default won't use 4KB per chunk but rather just BUFSIZ.
*
* Not implemented interface:
* obstack_alignment_mask:
* The current implementation does not provide any alignment guaranties.
* obstack_chunk_alloc and obstack_chunk_free:
* Internal implementation uses not only alloc and free but also realloc
* and thus standard implementations are used unconditionally instead of
* requiring users to provide declaration for these functions.
*/
#ifndef __INCLUDE_OBSTACK_H
#define __INCLUDE_OBSTACK_H
/****************************************************************************
* Included Files
****************************************************************************/
#include <stddef.h>
#include <stdarg.h>
/****************************************************************************
* Pre-processor Definitions
****************************************************************************/
/****************************************************************************
* Name: obstack_chunk_size
*
* Description:
* The access to the obstack configuration specifying the size of the
* single chunk used when growing object.
* It is documented t hat this is macro and that it is possible to use
* assignment to change the chunk size (eq.: obstack_chunk_size(h) = 1024).
*
* The default chunk size is set to BUFSIZ.
*
* The chunks size has to be always power of two due to the limitations of
* the obstack_make_room implementation!
*
* Input Parameters:
* h: pointer to the handle used to grow the object.
*
* Returned Value:
* Size of the single chunk.
*
****************************************************************************/
#define obstack_chunk_size(h) ((h)->chunk_size)
/****************************************************************************
* Name: obstack_base
*
* Description:
* Provides access to the tentative starting address of the
* currently growing object.
*
* Input Parameters:
* h: pointer to the handle used to grow the object.
*
* Returned Value:
* Tentative starting address of the currently growing object.
*
****************************************************************************/
#define obstack_base(h) ((h)->object_base)
/****************************************************************************
* Name: obstack_next_free
*
* Description:
* Provides access to the tentative address just after the end of the
* currently growing object.
*
* Input Parameters:
* h: pointer to the handle used to grow the object.
*
* Returned Value:
* Address just after the end of the currently growing object.
*
****************************************************************************/
#define obstack_next_free(h) ((h)->next_free)
/****************************************************************************
* Name: obstack_blank_fast
*
* Description:
* Moves the end of the currently growing object by given size and thus
* adding given number of uninitialized bytes to the growing object.
* There is no check if there is enough room and thus it is easy to cause
* buffer overrun. Use only when you are sure that there is enough room!
*
* Input Parameters:
* h: pointer to the handle used to grow the object.
* size: number of bytes
*
* Returned Value:
* The new address just after the end of the currently growing object.
*
****************************************************************************/
#define obstack_blank_fast(h, size) ((h)->next_free += (size))
/****************************************************************************
* Name: obstack_1grow_fast
*
* Description:
* Adds one byte to the currently growing object.
* There is no check if there is enough room and thus it is easy to cause
* buffer overrun. Use only when you are sure that there is enough room!
*
* Input Parameters:
* h: pointer to the handle used to grow the object.
* data: byte to be added
*
* Returned Value:
* Added byte.
*
****************************************************************************/
#define obstack_1grow_fast(h, data) (*((h)->next_free++) = (data))
/****************************************************************************
* Public Type Definitions
****************************************************************************/
struct _obstack_chunk /* Chunk head. */
{
FAR char *limit; /* Address of char after this chunk */
FAR struct _obstack_chunk *prev; /* Address of prior chunk or NULL */
};
struct obstack
{
size_t chunk_size; /* Preferred size to allocate chunks in */
FAR struct _obstack_chunk *chunk; /* Address of current struct _obstack_chunk */
FAR char *object_base; /* Address of object we are building */
FAR char *next_free; /* Where to add next char to current object */
};
/****************************************************************************
* Public Function Prototypes
****************************************************************************/
#undef EXTERN
#if defined(__cplusplus)
#define EXTERN extern "C"
extern "C"
{
#else
#define EXTERN extern
#endif
/****************************************************************************
* Name: obstack_init
*
* Description:
* Initialize obstack for allocation of objects.
* Compared to the GlibC version this won't initialize a first chunk.
*
* Input Parameters:
* h: pointer to the handle to initialize
*
****************************************************************************/
void obstack_init(FAR struct obstack *h);
/****************************************************************************
* Name: obstack_alloc
*
* Description:
* Allocate an object of given size with uninitialized bytes.
* Compared to the GlibC version this uses malloc to allocate exactly
* required space (plus overhead) and nothing more.
*
* Input Parameters:
* h: pointer to the handle to allocate an object in
* size: number of bytes to allocate
*
****************************************************************************/
FAR void *obstack_alloc(FAR struct obstack *h, size_t size);
/****************************************************************************
* Name: obstack_copy
*
* Description:
* Allocate an object of given size with contents copied from address.
* The same remarks regarding the allocation apply here as for
* obstack_alloc.
*
* Input Parameters:
* h: pointer to the handle to allocate an object in
* address: pointer to the bytes to be used to initialize new object
* size: number of bytes to allocate
*
****************************************************************************/
FAR void *obstack_copy(FAR struct obstack *h,
FAR const void *address, size_t size);
/****************************************************************************
* Name: obstack_copy0
*
* Description:
* Allocate an object of given size+1 with contents copied from address and
* append null byte at the end.
* The same remarks regarding the allocation apply here as for
* obstack_alloc.
*
* Input Parameters:
* h: pointer to the handle to allocate an object in
* address: pointer to the bytes to be used to initialize new object
* size: number of bytes to allocate (excluding the null byte)
*
****************************************************************************/
FAR void *obstack_copy0(FAR struct obstack *h,
FAR const void *address, size_t size);
/****************************************************************************
* Name: obstack_free
*
* Description:
* Free objects (and everything allocated in the specified obstack more
* recently than object). You can pass NULL to free everything.
* The buffer the allocated object was preset is kept and thus can be
* immediately reused for growing. The only exception for this is when NULL
* is passed as in such case even the last buffer is freed.
*
* Input Parameters:
* h: pointer to the handle object belongs to
* object: the pointer to the object or NULL
*
****************************************************************************/
void obstack_free(FAR struct obstack *h, FAR void *object);
/****************************************************************************
* Name: obstack_make_room
*
* Description:
* This is non-standard function that is probably available only on NuttX!
* Make sure that there is room in the buffer to fit object with given
* size. The allocation performed is in multiples of chunk_size specified
* for the obstack.
*
* Input Parameters:
* h: pointer to the handle where room should be made
* size: number of bytes to be free for growth
*
* Assumptions/Limitations:
* The obstack's chunk_size is expected to be power of two. This helps to
* eliminate division that might not be implemented in the HW and thus
* inefficient.
*
****************************************************************************/
void obstack_make_room(struct obstack *h, size_t size);
/****************************************************************************
* Name: obstack_blank
*
* Description:
* Grow object by given size. The bytes are uninitialized.
*
* Input Parameters:
* h: pointer to the handle to allocated object to
* size: number of bytes to grow object
*
****************************************************************************/
void obstack_blank(FAR struct obstack *h, size_t size);
/****************************************************************************
* Name: obstack_grow
*
* Description:
* Grow object by given size and allocated it with bytes from address.
*
* Input Parameters:
* h: pointer to the handle to allocated object to
* address: pointer to the bytes to be used to initialize the new object
* size: number of bytes to grow object
*
****************************************************************************/
void obstack_grow(FAR struct obstack *h,
FAR const void *address, size_t size);
/****************************************************************************
* Name: obstack_grow0
*
* Description:
* Grow object by given size+1 and allocated it with bytes from address
* plus null byte at the end.
*
* Input Parameters:
* h: pointer to the handle to allocated object to
* address: pointer to the bytes to be used to initialize the new object
* size: number of bytes to grow object (excluding the null byte)
*
****************************************************************************/
void obstack_grow0(FAR struct obstack *h,
FAR const void *address, size_t size);
/****************************************************************************
* Name: obstack_1grow
*
* Description:
* Grow object by single data byte.
*
* Input Parameters:
* h: pointer to the handle to allocated object to
* data: byte to be added to the growing object
*
****************************************************************************/
void obstack_1grow(FAR struct obstack *h, char data);
/****************************************************************************
* Name: obstack_finish
*
* Description:
* Finish growing object and receive address to it.
* Compared to the GlibC version this uses realloc to reduce buffer size to
* only allocated amount. The non-standard obstack_finish_norealloc can be
* used if you want the standard behavior for ever reason.
*
* Input Parameters:
* h: pointer to the handle used to grow the object.
*
* Returned Value:
* Permanent address to the object.
*
****************************************************************************/
FAR void *obstack_finish(FAR struct obstack *h);
/****************************************************************************
* Name: obstack_finish_norealloc
*
* Description:
* Finish growing object and receive address to it without reallocating
* buffer to fit the object (keeping space for more growth).
*
* Input Parameters:
* h: pointer to the handle used to grow the object.
*
* Returned Value:
* Permanent address to the object.
*
****************************************************************************/
FAR void *obstack_finish_norealloc(FAR struct obstack *h);
/****************************************************************************
* Name: obstack_object_size
*
* Description:
* Calculate the size of the currently growing object.
*
* Input Parameters:
* h: pointer to the handle used to grow the object.
*
* Returned Value:
* Size of the object.
*
****************************************************************************/
size_t obstack_object_size(FAR struct obstack *h);
/****************************************************************************
* Name: obstack_room
*
* Description:
* Calculate the number of bytes available for growth before reallocation
* is required.
*
* Input Parameters:
* h: pointer to the handle used to grow the object.
*
* Returned Value:
* Number of free bytes.
*
****************************************************************************/
size_t obstack_room(FAR struct obstack *h);
/****************************************************************************
* Name: obstack_printf
*
* Description:
* This is similar to the asprintf except it uses obstack to allocate
* string on. The characters are written onto the end of the currently
* growing object and terminated by null byte.
*
* This function is defined in stdio.h in GlibC. There is no definition
* that would be in stdio.h required for these here and thus it is easier
* to just keep these functions here as user has to include obstack anyway
* to get the full functionality.
*
* Input Parameters:
* h: pointer to the handle used to grow the object.
* fmt: format string with its format inputs followed.
*
* Returned Value:
* Number of characters added to the obstack excluding the null byte.
*
****************************************************************************/
int obstack_printf(FAR struct obstack *h, FAR const char *fmt, ...)
printf_like(2, 3);
/****************************************************************************
* Name: obstack_vprintf
*
* Description:
* This is similar to the vasprintf except it uses obstack to allocate
* string on. The characters are written onto the end of the currently
* growing object and terminated by null byte.
*
* The same remarks are applied here as for obstack_printf regarding the
* definition location in GlibC.
*
* Input Parameters:
* h: pointer to the handle used to grow the object.
* fmt: format string
* ap: format string input as a variable argument list
*
* Returned Value:
* Number of characters added to the obstack excluding the null byte.
*
****************************************************************************/
int obstack_vprintf(FAR struct obstack *h, FAR const char *fmt, va_list ap)
printf_like(2, 0);
/****************************************************************************
* Name: obstack_alloc_failed_handler
*
* Description:
* Error handler called when 'obstack_chunk_alloc' failed to allocate more
* memory. This can be set to a user defined function which should either
* abort gracefully or use longjump - but shouldn't return. The default
* action is to print a message and abort.
*
****************************************************************************/
extern void (*obstack_alloc_failed_handler) (void);
#undef EXTERN
#ifdef __cplusplus
}
#endif
#endif /* __INCLUDE_OBSTACK_H */