incubator-nuttx/include/obstack.h

/****************************************************************************
 * 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 */