0.1.1 abort() on failures (#1)

* feat: 0.1.1 abort() on failures

Adds some documentation lines. Thanks to u/skeeto for the help.

README.md

@@ -14,12 +14,14 @@
   This is a C library for an arena allocator, whose arenas are named Koliseo.
   It offers a basic API to perform initalisation, push/pop, reset and free of a Koliseo.
 
+  Thanks to [skeeto](https://www.reddit.com/user/skeeto/) for showing me the implementation.
+
 ## Prerequisites <a name = "prerequisites"></a>
 
   To build the `demo` binary, you need:
   * `automake` and `autoconf` to generate the needed `Makefile`
   * `make` to build the binary
-  * `gcc`, for building `demo`
+  * `gcc` or `clang`, for building `demo`
 
   To use `./anvil` to build all amboso-supported tags for `demo` , you also need the same packages.
 

bin/stego.lock

@@ -6,3 +6,4 @@ tests# tests folder name
 0.1.0# autoconf and automake support version
 [Supported versions]
 0.1.0# First release
+0.1.1# abort() on failed operations

bin/v0.1.1/.gitignore

@@ -0,0 +1,4 @@
+#amboso compliant version folder, will ignore everything inside BUT the gitignore, to keep the clean dir
+*
+!.gitignore
+!static

bin/v0.1.1/static

@@ -0,0 +1 @@
+../../static/

configure.ac

@@ -1,5 +1,5 @@
 # Define the package name and version
-AC_INIT([koliseo], [0.1.0], [jgabaut@github.com])
+AC_INIT([koliseo], [0.1.1], [jgabaut@github.com])
 
 # Verify automake version and enable foreign option
 AM_INIT_AUTOMAKE([foreign -Wall])
@@ -24,7 +24,7 @@ fi
 # Set a default version number if not specified externally
 AC_ARG_VAR([VERSION], [Version number])
 if test -z "$VERSION"; then
-  VERSION="0.1.0"
+  VERSION="0.1.1"
 fi
 
 # Output variables to the config.h header

docs/koliseo.doxyfile

@@ -48,7 +48,7 @@ PROJECT_NAME           = "koliseo"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = "0.1.0"
+PROJECT_NUMBER         = "0.1.1"
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

src/koliseo.c

@@ -1,13 +1,31 @@
 #include "koliseo.h"
 
+/**
+ * Returns the constant string representing current version for Koliseo.
+ * @return A constant string in MAJOR-MINOR-PATCH format for current Koliseo version.
+ */
 const char* string_koliseo_version(void) {
 	return KOLISEO_API_VERSION_STRING;
 }
 
+/**
+ * Returns the current offset (position of pointer bumper) for the passed Koliseo.
+ * @param kls The Koliseo at hand.
+ * @return A ptrdiff_t value for current position.
+ */
 ptrdiff_t kls_get_pos(Koliseo* kls) {
 	return kls->offset;
 }
 
+/**
+ * Takes a ptrdiff_t size and allocates the backing memory for a Koliseo. Sets the fields with appropriate values if memory allocation was successful, goes to abort() otherwise.
+ * @param size The size for Koliseo data field.
+ * @return A pointer to the initialised Koliseo struct.
+ * @see Koliseo
+ * @see Koliseo_Temp
+ * @see kls_temp_start()
+ * @see kls_temp_end()
+ */
 Koliseo* kls_new(ptrdiff_t size) {
 	assert(size >= (ptrdiff_t)sizeof(Koliseo));
 	void *p = malloc(size);
@@ -19,21 +37,39 @@ Koliseo* kls_new(ptrdiff_t size) {
 		kls->prev_offset = kls->offset;
 	} else {
 		fprintf(stderr,"[KLS] Failed kls_new() call.\n");
+		abort();
 	}
 	return p;
 }
 
+/**
+ * Takes a Koliseo pointer, and ptrdiff_t values for size, align and count. Tries popping the specified amount of memory from the Koliseo data field, marking it as free (as far as Koliseo is concerned), or goes to abort() if the operation fails.
+ * @param kls The Koliseo at hand.
+ * @param size The size for data to pop.
+ * @param align The alignment for data to pop.
+ * @param count The multiplicative quantity to scale data size to pop for.
+ * @return A void pointer to the start of memory just popped from the Koliseo.
+ */
 void* kls_pop(Koliseo* kls, ptrdiff_t size, ptrdiff_t align, ptrdiff_t count) {
 	ptrdiff_t padding = -kls->offset & (align -1);
 	if (count > PTRDIFF_MAX/size || (kls->size + kls->offset) < (size*count)) {
 		fprintf(stderr,"[KLS] Failed kls_pop() call.\n");
-		return 0;
+		abort();
 	}
 	char* p = kls->data + kls->offset - padding - size*count;
 	kls->offset -= padding + size*count;
 	return p;
 }
 
+/**
+ * Takes a Koliseo pointer, and ptrdiff_t values for size, align and count. Tries pushing the specified amount of memory to the Koliseo data field, or goes to abort() if the operation fails.
+ * Notably, it does NOT zero the memory region.
+ * @param kls The Koliseo at hand.
+ * @param size The size for data to push.
+ * @param align The alignment for data to push.
+ * @param count The multiplicative quantity to scale data size to push for.
+ * @return A void pointer to the start of memory just pushed to the Koliseo.
+ */
 void* kls_push(Koliseo* kls, ptrdiff_t size, ptrdiff_t align, ptrdiff_t count) {
 	ptrdiff_t available = kls->size - kls->offset;
 	ptrdiff_t padding = -kls->offset & (align -1);
@@ -44,13 +80,22 @@ void* kls_push(Koliseo* kls, ptrdiff_t size, ptrdiff_t align, ptrdiff_t count) {
 			fprintf(stderr, "[KLS]  Out of memory. size*count [%li] was bigger than available-padding [%li].\n", size*count, available-padding);
 		}
 		fprintf(stderr,"[KLS] Failed kls_push() call.\n");
-		return 0;
+		abort();
 	}
 	char* p = kls->data + kls->offset + padding;
 	kls->offset += padding + size*count;
 	return p;
 }
 
+/**
+ * Takes a Koliseo pointer, and ptrdiff_t values for size, align and count. Tries pushing the specified amount of memory to the Koliseo data field, or goes to abort() if the operation fails.
+ * Notably, it zeroes the memory region.
+ * @param kls The Koliseo at hand.
+ * @param size The size for data to push.
+ * @param align The alignment for data to push.
+ * @param count The multiplicative quantity to scale data size to push for.
+ * @return A void pointer to the start of memory just pushed to the Koliseo.
+ */
 void* kls_push_zero(Koliseo* kls, ptrdiff_t size, ptrdiff_t align, ptrdiff_t count) {
 	ptrdiff_t available = kls->size - kls->offset;
 	ptrdiff_t padding = -kls->offset & (align -1);
@@ -61,7 +106,8 @@ void* kls_push_zero(Koliseo* kls, ptrdiff_t size, ptrdiff_t align, ptrdiff_t cou
 			fprintf(stderr, "[KLS]  Out of memory. size*count [%li] was bigger than available-padding [%li].\n", size*count, available-padding);
 		}
 		fprintf(stderr,"[KLS] Failed kls_push_zero() call.\n");
-		return 0;
+		abort();
+		//return 0;
 	}
 	char* p = kls->data + kls->offset + padding;
 	//Zero new area
@@ -70,6 +116,10 @@ void* kls_push_zero(Koliseo* kls, ptrdiff_t size, ptrdiff_t align, ptrdiff_t cou
 	return p;
 }
 
+/**
+ * Prints header fields from the passed Koliseo pointer.
+ * @param kls The Koliseo at hand.
+ */
 void print_dbg_kls(Koliseo* kls) {
 	if (kls == NULL) {
 		fprintf(stderr,"[KLS] kls was NULL.");
@@ -80,13 +130,48 @@ void print_dbg_kls(Koliseo* kls) {
 	}
 }
 
+/**
+ * Resets the offset field for the passed Koliseo pointer.
+ * Notably, it sets the prev_offset field to the previous offset, thus remembering where last allocation was before the clear.
+ * @param kls The Koliseo at hand.
+ */
 void kls_clear(Koliseo* kls) {
 	//Reset pointer
 	kls->prev_offset = kls->offset;
 	kls->offset = sizeof(*kls);
 }
 
+/**
+ * Calls kls_clear() on the passed Koliseo pointer and the frees the actual Koliseo.
+ * @param kls The Koliseo at hand.
+ * @see kls_clear()
+ */
 void kls_free(Koliseo* kls) {
 	kls_clear(kls);
 	free(kls);
 }
+
+/**
+ * Starts a new savestate for the passed Koliseo pointer, by initialising a Koliseo_temp and returning it.
+ * Notably, you should not use the original while using the copy.
+ * @param kls The Koliseo at hand.
+ * @return A Koliseo_Temp struct.
+ * @see Koliseo_Temp
+ */
+Koliseo_Temp kls_temp_start(Koliseo* kls) {
+	Koliseo_Temp tmp;
+	tmp.kls = kls;
+	tmp.prev_offset = kls->prev_offset;
+	tmp.offset = kls->offset;
+	return tmp;
+}
+
+/**
+ * Ends a new savestate for the passed Koliseo pointer, by initialising a Koliseo_temp and returning it.
+ * Notably, you should not use the original while using the copy.
+ * @param kls The Koliseo at hand.
+ */
+void kls_temp_end(Koliseo_Temp tmp_kls) {
+	tmp_kls.prev_offset = tmp_kls.prev_offset;
+	tmp_kls.offset = tmp_kls.offset;
+}

src/koliseo.h

@@ -6,25 +6,52 @@
 #include <stdlib.h>
 #include <assert.h>
 #include <string.h>
-static const char KOLISEO_API_VERSION_STRING[] = "0.1.0";
+
+#define KLS_MAJOR 0 /**< Represents current major release.*/
+#define KLS_MINOR 1 /**< Represents current minor release.*/
+#define KLS_PATCH 1 /**< Represents current patch release.*/
+
+static const char KOLISEO_API_VERSION_STRING[] = "0.1.1"; /**< Represents current version with MAJOR.MINOR.PATCH format.*/
+
 const char* string_koliseo_version(void);
 
-#define KLS_DEFAULT_SIZE (16*1024)
+#define KLS_DEFAULT_SIZE (16*1024) /**< Represents a simple default size for demo purposes.*/
 
-#ifndef DEFAULT_ALIGNMENT
-#define DEFAULT_ALIGNMENT (2*sizeof(void *))
+#ifndef KLS_DEFAULT_ALIGNMENT
+#define KLS_DEFAULT_ALIGNMENT (2*sizeof(void *)) /**< Represents a default alignment value. Not used.*/
 #endif
 
+/**
+ * Represents the initialised arena allocator struct.
+ * @see kls_new()
+ * @see kls_clear()
+ * @see kls_free()
+ * @see KLS_PUSH()
+ * @see KLS_POP()
+ */
 typedef struct Koliseo {
-	char* data; /**< Points to data field*/
-	ptrdiff_t size; /**< Size of data field*/
-	ptrdiff_t offset; /**< Current position of memory pointer*/
-	ptrdiff_t prev_offset; /**< Previous position of memory pointer*/
+	char* data; /**< Points to data field.*/
+	ptrdiff_t size; /**< Size of data field.*/
+	ptrdiff_t offset; /**< Current position of memory pointer.*/
+	ptrdiff_t prev_offset; /**< Previous position of memory pointer.*/
 } Koliseo;
 
+/**
+ * Represents a savestate for a Koliseo.
+ * @see kls_temp_start()
+ * @see kls_temp_end()
+ * @see KLS_PUSH()
+ * @see KLS_POP()
+ */
+typedef struct Koliseo_Temp {
+	Koliseo* kls; /**< Reference to the actual Koliseo we're saving.*/
+	ptrdiff_t offset; /**< Current position of memory pointer.*/
+	ptrdiff_t prev_offset; /**< Previous position of memory pointer.*/
+} Koliseo_Temp;
+
 ptrdiff_t kls_get_pos(Koliseo* kls);
 
-Koliseo *kls_new(ptrdiff_t size);
+Koliseo* kls_new(ptrdiff_t size);
 
 void* kls_push(Koliseo* kls, ptrdiff_t size, ptrdiff_t align, ptrdiff_t count);
 void* kls_push_zero(Koliseo* kls, ptrdiff_t size, ptrdiff_t align, ptrdiff_t count);
@@ -40,4 +67,7 @@ void kls_clear(Koliseo* kls);
 void kls_free(Koliseo* kls);
 void print_dbg_kls(Koliseo* kls);
 
+Koliseo_Temp kls_temp_start(Koliseo* kls);
+void kls_temp_end(Koliseo_Temp tmp_kls);
+
 #endif

static/amboso.c

@@ -1,5 +1,5 @@
 #include "amboso.h"
 
-char* getAmbosoVersion() {
+char* getAmbosoVersion(void) {
     return AMBOSO_CV;
 }

static/amboso.h

@@ -1,5 +1,5 @@
 #ifndef AMBOSO_H
 #define AMBOSO_H
 #define AMBOSO_CV "1.6.0"
-char* getAmbosoVersion();
+char* getAmbosoVersion(void);
 #endif

static/demo.c

@@ -16,7 +16,7 @@ int main(void) {
   int minusone = -1;
   int* p = &minusone;
   printf("\n*p is [%i] before KLS_PUSH\n",*p);
-  printf("[KLS_PUSH for a int] [size: %li]\n",sizeof(int));
+  printf("[KLS_PUSH for a int to Koliseo] [size: %li]\n",sizeof(int));
   p = (int*) KLS_PUSH(kls, int, 1);
   printf("[Current position in Koliseo] [pos: %li]\n",kls_get_pos(kls));
   print_dbg_kls(kls);