#ifndef SALLOC_H_
#define SALLOC_H_

#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif
/** Sequntial memory allocator
 *
 * Allocates bigger chunks of memory at a time, to save the amount of malloc call,
 * and enables you to free all that memory in one sweep.
 *
 * This means that once allocated, a piece of memory obtained from the 
 * allocator cannot be free'd individually, only the entire SAlloc can be free'd.
 *
 * Memory is allocated using the underlying malloc() in chunk sizes.
 * Once a particular SAlloc has given out all memory in a chunk, a new chunk
 * is allocated again, using the underlying malloc().
 *
 */

/** Opaque handle to a SAlloc */
typedef struct SAlloc SAlloc;

/** Create a new SAlloc with the given size for each chunk.
 *  e.g. uc_new_salloc(sizeof(struct Foo) * 1000); will immedeatly
 *  allocate memory to hold 1000 struct Foo's. Once all that memory is
 *  handed out from this SAlloc, another piece of memory is allocaterd 
 *  for another 1000 struct Foo's.. All these memory pieces are released
 *  when the uc_free_salloc() is called.
 *
 *  @param chunksz Size of each piece of memory block allocated.
 *  @return A new handle for a SAlloc, or NULL.
 */
SAlloc *uc_new_salloc(size_t chunksz);

/** Allocate memory from a SAlloc.
 * @param sz  size of the memory. This must be <= the chunksz the SAlloc was
 *      created with.
 * @return The new memory, or NULL if sz > chunksz or an underlying
 *         malloc call fails.
 */
void * uc_s_alloc(SAlloc *p,size_t sz);

/** Just like uc_s_alloc, but zero out the memory before returning it.
 */
void * uc_s_allocz(SAlloc *p,size_t sz);
/** Free the SAlloc and all memory associated with this SAlloc.
 * The SAlloc is not usable any more after this call.
 *
 * @param p The SAlloc to free.
 */
void uc_free_salloc(SAlloc *p);

/** Reset this SAlloc, effectivly releasing all the memory obtained.
 * The SAlloc is still usable after this call.
 * The actual memory previously allocated from this SAlloc is cached,
 * and will be reused by subsequent uc_s_alloc calls.
 *
 * @param p The SAlloc to reset.
 */
void uc_reset_salloc(SAlloc *p);

#ifdef __cplusplus
}
#endif


#endif