git.sesse.net Git - pistorm/blob - raylib/rmem.h

   1 /**********************************************************************************************
   2 *
   3 *   rmem - raylib memory pool and objects pool
   4 *
   5 *   A quick, efficient, and minimal free list and arena-based allocator
   6 *
   7 *   PURPOSE:
   8 *     - A quicker, efficient memory allocator alternative to 'malloc' and friends.
   9 *     - Reduce the possibilities of memory leaks for beginner developers using Raylib.
  10 *     - Being able to flexibly range check memory if necessary.
  11 *
  12 *   CONFIGURATION:
  13 *
  14 *   #define RMEM_IMPLEMENTATION
  15 *       Generates the implementation of the library into the included file.
  16 *       If not defined, the library is in header only mode and can be included in other headers
  17 *       or source files without problems. But only ONE file should hold the implementation.
  18 *
  19 *
  20 *   LICENSE: zlib/libpng
  21 *
  22 *   Copyright (c) 2019 Kevin 'Assyrianic' Yonan (@assyrianic) and reviewed by Ramon Santamaria (@raysan5)
  23 *
  24 *   This software is provided "as-is", without any express or implied warranty. In no event
  25 *   will the authors be held liable for any damages arising from the use of this software.
  26 *
  27 *   Permission is granted to anyone to use this software for any purpose, including commercial
  28 *   applications, and to alter it and redistribute it freely, subject to the following restrictions:
  29 *
  30 *     1. The origin of this software must not be misrepresented; you must not claim that you
  31 *     wrote the original software. If you use this software in a product, an acknowledgment
  32 *     in the product documentation would be appreciated but is not required.
  33 *
  34 *     2. Altered source versions must be plainly marked as such, and must not be misrepresented
  35 *     as being the original software.
  36 *
  37 *     3. This notice may not be removed or altered from any source distribution.
  38 *
  39 **********************************************************************************************/
  40
  41 #ifndef RMEM_H
  42 #define RMEM_H
  43
  44 #include <inttypes.h>
  45 #include <stdbool.h>
  46
  47 //----------------------------------------------------------------------------------
  48 // Defines and Macros
  49 //----------------------------------------------------------------------------------
  50 #if defined(_WIN32) && defined(BUILD_LIBTYPE_SHARED)
  51     #define RMEMAPI __declspec(dllexport)         // We are building library as a Win32 shared library (.dll)
  52 #elif defined(_WIN32) && defined(USE_LIBTYPE_SHARED)
  53     #define RMEMAPI __declspec(dllimport)         // We are using library as a Win32 shared library (.dll)
  54 #else
  55     #define RMEMAPI   // We are building or using library as a static library (or Linux shared library)
  56 #endif
  57
  58 #define RMEM_VERSION    "v1.3"    // changelog at bottom of header.
  59
  60 //----------------------------------------------------------------------------------
  61 // Types and Structures Definition
  62 //----------------------------------------------------------------------------------
  63
  64 // Memory Pool
  65 typedef struct MemNode MemNode;
  66 struct MemNode {
  67     size_t size;
  68     MemNode *next, *prev;
  69 };
  70
  71 // Freelist implementation
  72 typedef struct AllocList {
  73     MemNode *head, *tail;
  74     size_t len;
  75 } AllocList;
  76
  77 // Arena allocator.
  78 typedef struct Arena {
  79     uintptr_t mem, offs;
  80     size_t size;
  81 } Arena;
  82
  83
  84 enum {
  85     MEMPOOL_BUCKET_SIZE = 8,
  86     MEMPOOL_BUCKET_BITS = (sizeof(uintptr_t) >> 1) + 1,
  87     MEM_SPLIT_THRESHOLD = sizeof(uintptr_t) * 4
  88 };
  89
  90 typedef struct MemPool {
  91     AllocList large, buckets[MEMPOOL_BUCKET_SIZE];
  92     Arena arena;
  93 } MemPool;
  94
  95
  96 // Object Pool
  97 typedef struct ObjPool {
  98     uintptr_t mem, offs;
  99     size_t objSize, freeBlocks, memSize;
 100 } ObjPool;
 101
 102
 103 // Double-Ended Stack aka Deque
 104 typedef struct BiStack {
 105     uintptr_t mem, front, back;
 106     size_t size;
 107 } BiStack;
 108
 109
 110 #if defined(__cplusplus)
 111 extern "C" {            // Prevents name mangling of functions
 112 #endif
 113
 114 //------------------------------------------------------------------------------------
 115 // Functions Declaration - Memory Pool
 116 //------------------------------------------------------------------------------------
 117 RMEMAPI MemPool CreateMemPool(size_t bytes);
 118 RMEMAPI MemPool CreateMemPoolFromBuffer(void *buf, size_t bytes);
 119 RMEMAPI void DestroyMemPool(MemPool *mempool);
 120
 121 RMEMAPI void *MemPoolAlloc(MemPool *mempool, size_t bytes);
 122 RMEMAPI void *MemPoolRealloc(MemPool *mempool, void *ptr, size_t bytes);
 123 RMEMAPI void MemPoolFree(MemPool *mempool, void *ptr);
 124 RMEMAPI void MemPoolCleanUp(MemPool *mempool, void **ptrref);
 125 RMEMAPI void MemPoolReset(MemPool *mempool);
 126 RMEMAPI size_t GetMemPoolFreeMemory(const MemPool mempool);
 127
 128 //------------------------------------------------------------------------------------
 129 // Functions Declaration - Object Pool
 130 //------------------------------------------------------------------------------------
 131 RMEMAPI ObjPool CreateObjPool(size_t objsize, size_t len);
 132 RMEMAPI ObjPool CreateObjPoolFromBuffer(void *buf, size_t objsize, size_t len);
 133 RMEMAPI void DestroyObjPool(ObjPool *objpool);
 134
 135 RMEMAPI void *ObjPoolAlloc(ObjPool *objpool);
 136 RMEMAPI void ObjPoolFree(ObjPool *objpool, void *ptr);
 137 RMEMAPI void ObjPoolCleanUp(ObjPool *objpool, void **ptrref);
 138
 139 //------------------------------------------------------------------------------------
 140 // Functions Declaration - Double-Ended Stack
 141 //------------------------------------------------------------------------------------
 142 RMEMAPI BiStack CreateBiStack(size_t len);
 143 RMEMAPI BiStack CreateBiStackFromBuffer(void *buf, size_t len);
 144 RMEMAPI void DestroyBiStack(BiStack *destack);
 145
 146 RMEMAPI void *BiStackAllocFront(BiStack *destack, size_t len);
 147 RMEMAPI void *BiStackAllocBack(BiStack *destack, size_t len);
 148
 149 RMEMAPI void BiStackResetFront(BiStack *destack);
 150 RMEMAPI void BiStackResetBack(BiStack *destack);
 151 RMEMAPI void BiStackResetAll(BiStack *destack);
 152
 153 RMEMAPI intptr_t BiStackMargins(BiStack destack);
 154
 155 #ifdef __cplusplus
 156 }
 157 #endif
 158
 159 #endif // RMEM_H
 160
 161 /***********************************************************************************
 162 *
 163 *   RMEM IMPLEMENTATION
 164 *
 165 ************************************************************************************/
 166
 167 #if defined(RMEM_IMPLEMENTATION)
 168
 169 #include <stdio.h>          // Required for:
 170 #include <stdlib.h>         // Required for:
 171 #include <string.h>         // Required for:
 172
 173 //----------------------------------------------------------------------------------
 174 // Defines and Macros
 175 //----------------------------------------------------------------------------------
 176
 177 // Make sure restrict type qualifier for pointers is defined
 178 // NOTE: Not supported by C++, it is a C only keyword
 179 #if defined(_WIN32) || defined(_WIN64) || defined(__CYGWIN__) || defined(_MSC_VER)
 180     #ifndef restrict
 181         #define restrict __restrict
 182     #endif
 183 #endif
 184
 185 //----------------------------------------------------------------------------------
 186 // Global Variables Definition
 187 //----------------------------------------------------------------------------------
 188 // ...
 189
 190 //----------------------------------------------------------------------------------
 191 // Module specific Functions Declaration
 192 //----------------------------------------------------------------------------------
 193 static inline size_t __AlignSize(const size_t size, const size_t align)
 194 {
 195     return (size + (align - 1)) & -align;
 196 }
 197
 198 static MemNode *__SplitMemNode(MemNode *const node, const size_t bytes)
 199 {
 200     uintptr_t n = ( uintptr_t )node;
 201     MemNode *const r = ( MemNode* )(n + (node->size - bytes));
 202     node->size -= bytes;
 203     r->size = bytes;
 204     return r;
 205 }
 206
 207 static void __InsertMemNodeBefore(AllocList *const list, MemNode *const insert, MemNode *const curr)
 208 {
 209     insert->next = curr;
 210     if (curr->prev==NULL) list->head = insert;
 211     else
 212     {
 213         insert->prev = curr->prev;
 214         curr->prev->next = insert;
 215     }
 216     curr->prev = insert;
 217 }
 218
 219 static void __ReplaceMemNode(MemNode *const old, MemNode *const replace)
 220 {
 221     replace->prev = old->prev;
 222     replace->next = old->next;
 223     if( old->prev != NULL )
 224         old->prev->next = replace;
 225     if( old->next != NULL )
 226         old->next->prev = replace;
 227 }
 228
 229
 230 static MemNode *__RemoveMemNode(AllocList *const list, MemNode *const node)
 231 {
 232     if (node->prev != NULL) node->prev->next = node->next;
 233     else
 234     {
 235         list->head = node->next;
 236         if (list->head != NULL) list->head->prev = NULL;
 237         else list->tail = NULL;
 238     }
 239
 240     if (node->next != NULL) node->next->prev = node->prev;
 241     else
 242     {
 243         list->tail = node->prev;
 244         if (list->tail != NULL) list->tail->next = NULL;
 245         else list->head = NULL;
 246     }
 247     list->len--;
 248     return node;
 249 }
 250
 251 static MemNode *__FindMemNode(AllocList *const list, const size_t bytes)
 252 {
 253     for (MemNode *node = list->head; node != NULL; node = node->next)
 254     {
 255         if (node->size < bytes) continue;
 256         // close in size - reduce fragmentation by not splitting.
 257         else if (node->size <= bytes + MEM_SPLIT_THRESHOLD) return __RemoveMemNode(list, node);
 258         else return __SplitMemNode(node, bytes);
 259     }
 260     return NULL;
 261 }
 262
 263 static void __InsertMemNode(MemPool *const mempool, AllocList *const list, MemNode *const node, const bool is_bucket)
 264 {
 265     if (list->head == NULL)
 266     {
 267         list->head = node;
 268         list->len++;
 269     }
 270     else
 271     {
 272         for (MemNode *iter = list->head; iter != NULL; iter = iter->next)
 273         {
 274             if (( uintptr_t )iter == mempool->arena.offs)
 275             {
 276                 mempool->arena.offs += iter->size;
 277                 __RemoveMemNode(list, iter);
 278                 iter = list->head;
 279             }
 280             const uintptr_t inode = ( uintptr_t )node;
 281             const uintptr_t iiter = ( uintptr_t )iter;
 282             const uintptr_t iter_end = iiter + iter->size;
 283             const uintptr_t node_end = inode + node->size;
 284             if (iter==node) return;
 285             else if (iter < node)
 286             {
 287                 // node was coalesced prior.
 288                 if (iter_end > inode) return;
 289                 else if (iter_end==inode && !is_bucket)
 290                 {
 291                     // if we can coalesce, do so.
 292                     iter->size += node->size;
 293                     return;
 294                 }
 295             }
 296             else if (iter > node)
 297             {
 298                 // Address sort, lowest to highest aka ascending order.
 299                 if (iiter < node_end) return;
 300                 else if (iter==list->head && !is_bucket)
 301                 {
 302                     if (iter_end==inode) iter->size += node->size;
 303                     else if (node_end==iiter)
 304                     {
 305                         node->size += list->head->size;
 306                         node->next = list->head->next;
 307                         node->prev = NULL;
 308                         list->head = node;
 309                     }
 310                     else
 311                     {
 312                         node->next = iter;
 313                         node->prev = NULL;
 314                         iter->prev = node;
 315                         list->head = node;
 316                         list->len++;
 317                     }
 318                     return;
 319                 }
 320                 else if (iter_end==inode && !is_bucket)
 321                 {
 322                     // if we can coalesce, do so.
 323                     iter->size += node->size;
 324                     return;
 325                 }
 326                 else
 327                 {
 328                     __InsertMemNodeBefore(list, iter, node);
 329                     list->len++;
 330                     return;
 331                 }
 332             }
 333         }
 334     }
 335 }
 336
 337 //----------------------------------------------------------------------------------
 338 // Module Functions Definition - Memory Pool
 339 //----------------------------------------------------------------------------------
 340
 341 MemPool CreateMemPool(const size_t size)
 342 {
 343     MemPool mempool = { 0 };
 344
 345     if (size == 0) return mempool;
 346     else
 347     {
 348         // Align the mempool size to at least the size of an alloc node.
 349         uint8_t *const restrict buf = malloc(size*sizeof *buf);
 350         if (buf==NULL) return mempool;
 351         else
 352         {
 353             mempool.arena.size = size;
 354             mempool.arena.mem = ( uintptr_t )buf;
 355             mempool.arena.offs = mempool.arena.mem + mempool.arena.size;
 356             return mempool;
 357         }
 358     }
 359 }
 360
 361 MemPool CreateMemPoolFromBuffer(void *const restrict buf, const size_t size)
 362 {
 363     MemPool mempool = { 0 };
 364     if ((size == 0) || (buf == NULL) || (size <= sizeof(MemNode))) return mempool;
 365     else
 366     {
 367         mempool.arena.size = size;
 368         mempool.arena.mem = ( uintptr_t )buf;
 369         mempool.arena.offs = mempool.arena.mem + mempool.arena.size;
 370         return mempool;
 371     }
 372 }
 373
 374 void DestroyMemPool(MemPool *const restrict mempool)
 375 {
 376     if (mempool->arena.mem == 0) return;
 377     else
 378     {
 379         void *const restrict ptr = ( void* )mempool->arena.mem;
 380         free(ptr);
 381         *mempool = (MemPool){ 0 };
 382     }
 383 }
 384
 385 void *MemPoolAlloc(MemPool *const mempool, const size_t size)
 386 {
 387     if ((size == 0) || (size > mempool->arena.size)) return NULL;
 388     else
 389     {
 390         MemNode *new_mem = NULL;
 391         const size_t ALLOC_SIZE = __AlignSize(size + sizeof *new_mem, sizeof(intptr_t));
 392         const size_t BUCKET_SLOT = (ALLOC_SIZE >> MEMPOOL_BUCKET_BITS) - 1;
 393
 394         // If the size is small enough, let's check if our buckets has a fitting memory block.
 395         if (BUCKET_SLOT < MEMPOOL_BUCKET_SIZE)
 396         {
 397             new_mem = __FindMemNode(&mempool->buckets[BUCKET_SLOT], ALLOC_SIZE);
 398         }
 399         else if (mempool->large.head != NULL)
 400         {
 401             new_mem = __FindMemNode(&mempool->large, ALLOC_SIZE);
 402         }
 403
 404         if (new_mem == NULL)
 405         {
 406             // not enough memory to support the size!
 407             if ((mempool->arena.offs - ALLOC_SIZE) < mempool->arena.mem) return NULL;
 408             else
 409             {
 410                 // Couldn't allocate from a freelist, allocate from available mempool.
 411                 // Subtract allocation size from the mempool.
 412                 mempool->arena.offs -= ALLOC_SIZE;
 413
 414                 // Use the available mempool space as the new node.
 415                 new_mem = ( MemNode* )mempool->arena.offs;
 416                 new_mem->size = ALLOC_SIZE;
 417             }
 418         }
 419
 420         // Visual of the allocation block.
 421         // --------------
 422         // | mem size   | lowest addr of block
 423         // | next node  | 12 byte (32-bit) header
 424         // | prev node  | 24 byte (64-bit) header
 425         // |------------|
 426         // |   alloc'd  |
 427         // |   memory   |
 428         // |   space    | highest addr of block
 429         // --------------
 430         new_mem->next = new_mem->prev = NULL;
 431         uint8_t *const restrict final_mem = ( uint8_t* )new_mem + sizeof *new_mem;
 432         return memset(final_mem, 0, new_mem->size - sizeof *new_mem);
 433     }
 434 }
 435
 436 void *MemPoolRealloc(MemPool *const restrict mempool, void *const ptr, const size_t size)
 437 {
 438     if (size > mempool->arena.size) return NULL;
 439     // NULL ptr should make this work like regular Allocation.
 440     else if (ptr == NULL) return MemPoolAlloc(mempool, size);
 441     else if ((uintptr_t)ptr - sizeof(MemNode) < mempool->arena.mem) return NULL;
 442     else
 443     {
 444         MemNode *const node = ( MemNode* )(( uint8_t* )ptr - sizeof *node);
 445         const size_t NODE_SIZE = sizeof *node;
 446         uint8_t *const resized_block = MemPoolAlloc(mempool, size);
 447         if (resized_block == NULL) return NULL;
 448         else
 449         {
 450             MemNode *const resized = ( MemNode* )(resized_block - sizeof *resized);
 451             memmove(resized_block, ptr, (node->size > resized->size)? (resized->size - NODE_SIZE) : (node->size - NODE_SIZE));
 452             MemPoolFree(mempool, ptr);
 453             return resized_block;
 454         }
 455     }
 456 }
 457
 458 void MemPoolFree(MemPool *const restrict mempool, void *const ptr)
 459 {
 460     const uintptr_t p = ( uintptr_t )ptr;
 461     if ((ptr == NULL) || (p - sizeof(MemNode) < mempool->arena.mem)) return;
 462     else
 463     {
 464         // Behind the actual pointer data is the allocation info.
 465         const uintptr_t block = p - sizeof(MemNode);
 466         MemNode *const mem_node = ( MemNode* )block;
 467         const size_t BUCKET_SLOT = (mem_node->size >> MEMPOOL_BUCKET_BITS) - 1;
 468
 469         // Make sure the pointer data is valid.
 470         if ((block < mempool->arena.offs) ||
 471             ((block - mempool->arena.mem) > mempool->arena.size) ||
 472             (mem_node->size == 0) ||
 473             (mem_node->size > mempool->arena.size)) return;
 474         // If the mem_node is right at the arena offs, then merge it back to the arena.
 475         else if (block == mempool->arena.offs)
 476         {
 477             mempool->arena.offs += mem_node->size;
 478         }
 479         else
 480         {
 481             // try to place it into bucket or large freelist.
 482             struct AllocList *const l = (BUCKET_SLOT < MEMPOOL_BUCKET_SIZE) ? &mempool->buckets[BUCKET_SLOT] : &mempool->large;
 483             __InsertMemNode(mempool, l, mem_node, (BUCKET_SLOT < MEMPOOL_BUCKET_SIZE));
 484         }
 485     }
 486 }
 487
 488 void MemPoolCleanUp(MemPool *const restrict mempool, void **const ptrref)
 489 {
 490     if ((ptrref == NULL) || (*ptrref == NULL)) return;
 491     else
 492     {
 493         MemPoolFree(mempool, *ptrref);
 494         *ptrref = NULL;
 495     }
 496 }
 497
 498 size_t GetMemPoolFreeMemory(const MemPool mempool)
 499 {
 500     size_t total_remaining = mempool.arena.offs - mempool.arena.mem;
 501
 502     for (MemNode *n=mempool.large.head; n != NULL; n = n->next) total_remaining += n->size;
 503
 504     for (size_t i=0; i<MEMPOOL_BUCKET_SIZE; i++) for (MemNode *n = mempool.buckets[i].head; n != NULL; n = n->next) total_remaining += n->size;
 505
 506     return total_remaining;
 507 }
 508
 509 void MemPoolReset(MemPool *const mempool)
 510 {
 511     mempool->large.head = mempool->large.tail = NULL;
 512     mempool->large.len = 0;
 513     for (size_t i = 0; i < MEMPOOL_BUCKET_SIZE; i++)
 514     {
 515         mempool->buckets[i].head = mempool->buckets[i].tail = NULL;
 516         mempool->buckets[i].len = 0;
 517     }
 518     mempool->arena.offs = mempool->arena.mem + mempool->arena.size;
 519 }
 520
 521 //----------------------------------------------------------------------------------
 522 // Module Functions Definition - Object Pool
 523 //----------------------------------------------------------------------------------
 524
 525 ObjPool CreateObjPool(const size_t objsize, const size_t len)
 526 {
 527     ObjPool objpool = { 0 };
 528     if ((len == 0) || (objsize == 0)) return objpool;
 529     else
 530     {
 531         const size_t aligned_size = __AlignSize(objsize, sizeof(size_t));
 532         uint8_t *const restrict buf = calloc(len, aligned_size);
 533         if (buf == NULL) return objpool;
 534         objpool.objSize = aligned_size;
 535         objpool.memSize = objpool.freeBlocks = len;
 536         objpool.mem = ( uintptr_t )buf;
 537
 538         for (size_t i=0; i<objpool.freeBlocks; i++)
 539         {
 540             size_t *const restrict index = ( size_t* )(objpool.mem + (i*aligned_size));
 541             *index = i + 1;
 542         }
 543
 544         objpool.offs = objpool.mem;
 545         return objpool;
 546     }
 547 }
 548
 549 ObjPool CreateObjPoolFromBuffer(void *const restrict buf, const size_t objsize, const size_t len)
 550 {
 551     ObjPool objpool = { 0 };
 552
 553     // If the object size isn't large enough to align to a size_t, then we can't use it.
 554     const size_t aligned_size = __AlignSize(objsize, sizeof(size_t));
 555     if ((buf == NULL) || (len == 0) || (objsize < sizeof(size_t)) || (objsize*len != aligned_size*len)) return objpool;
 556     else
 557     {
 558         objpool.objSize = aligned_size;
 559         objpool.memSize = objpool.freeBlocks = len;
 560         objpool.mem = (uintptr_t)buf;
 561
 562         for (size_t i=0; i<objpool.freeBlocks; i++)
 563         {
 564             size_t *const restrict index = ( size_t* )(objpool.mem + (i*aligned_size));
 565             *index = i + 1;
 566         }
 567
 568         objpool.offs = objpool.mem;
 569         return objpool;
 570     }
 571 }
 572
 573 void DestroyObjPool(ObjPool *const restrict objpool)
 574 {
 575     if (objpool->mem == 0) return;
 576     else
 577     {
 578         void *const restrict ptr = ( void* )objpool->mem;
 579         free(ptr);
 580         *objpool = (ObjPool){0};
 581     }
 582 }
 583
 584 void *ObjPoolAlloc(ObjPool *const objpool)
 585 {
 586     if (objpool->freeBlocks > 0)
 587     {
 588         // For first allocation, head points to the very first index.
 589         // Head = &pool[0];
 590         // ret = Head == ret = &pool[0];
 591         size_t *const restrict block = ( size_t* )objpool->offs;
 592         objpool->freeBlocks--;
 593
 594         // after allocating, we set head to the address of the index that *Head holds.
 595         // Head = &pool[*Head * pool.objsize];
 596         objpool->offs = (objpool->freeBlocks != 0)? objpool->mem + (*block*objpool->objSize) : 0;
 597         return memset(block, 0, objpool->objSize);
 598     }
 599     else return NULL;
 600 }
 601
 602 void ObjPoolFree(ObjPool *const restrict objpool, void *const ptr)
 603 {
 604     uintptr_t block = (uintptr_t)ptr;
 605     if ((ptr == NULL) || (block < objpool->mem) || (block > objpool->mem + objpool->memSize*objpool->objSize)) return;
 606     else
 607     {
 608         // When we free our pointer, we recycle the pointer space to store the previous index and then we push it as our new head.
 609         // *p = index of Head in relation to the buffer;
 610         // Head = p;
 611         size_t *const restrict index = ( size_t* )block;
 612         *index = (objpool->offs != 0)? (objpool->offs - objpool->mem)/objpool->objSize : objpool->memSize;
 613         objpool->offs = block;
 614         objpool->freeBlocks++;
 615     }
 616 }
 617
 618 void ObjPoolCleanUp(ObjPool *const restrict objpool, void **const restrict ptrref)
 619 {
 620     if (ptrref == NULL) return;
 621     else
 622     {
 623         ObjPoolFree(objpool, *ptrref);
 624         *ptrref = NULL;
 625     }
 626 }
 627
 628
 629 //----------------------------------------------------------------------------------
 630 // Module Functions Definition - Double-Ended Stack
 631 //----------------------------------------------------------------------------------
 632 BiStack CreateBiStack(const size_t len)
 633 {
 634     BiStack destack = { 0 };
 635     if (len == 0) return destack;
 636
 637     uint8_t *const buf = malloc(len*sizeof *buf);
 638     if (buf==NULL) return destack;
 639     destack.size = len;
 640     destack.mem = ( uintptr_t )buf;
 641     destack.front = destack.mem;
 642     destack.back = destack.mem + len;
 643     return destack;
 644 }
 645
 646 BiStack CreateBiStackFromBuffer(void *const buf, const size_t len)
 647 {
 648     BiStack destack = { 0 };
 649     if (len == 0 || buf == NULL) return destack;
 650     else
 651     {
 652         destack.size = len;
 653         destack.mem = destack.front = ( uintptr_t )buf;
 654         destack.back = destack.mem + len;
 655         return destack;
 656     }
 657 }
 658
 659 void DestroyBiStack(BiStack *const restrict destack)
 660 {
 661     if (destack->mem == 0) return;
 662     else
 663     {
 664         uint8_t *const restrict buf = ( uint8_t* )destack->mem;
 665         free(buf);
 666         *destack = (BiStack){0};
 667     }
 668 }
 669
 670 void *BiStackAllocFront(BiStack *const restrict destack, const size_t len)
 671 {
 672     if (destack->mem == 0) return NULL;
 673     else
 674     {
 675         const size_t ALIGNED_LEN = __AlignSize(len, sizeof(uintptr_t));
 676         // front end arena is too high!
 677         if (destack->front + ALIGNED_LEN >= destack->back) return NULL;
 678         else
 679         {
 680             uint8_t *const restrict ptr = ( uint8_t* )destack->front;
 681             destack->front += ALIGNED_LEN;
 682             return ptr;
 683         }
 684     }
 685 }
 686
 687 void *BiStackAllocBack(BiStack *const restrict destack, const size_t len)
 688 {
 689     if (destack->mem == 0) return NULL;
 690     else
 691     {
 692         const size_t ALIGNED_LEN = __AlignSize(len, sizeof(uintptr_t));
 693         // back end arena is too low
 694         if (destack->back - ALIGNED_LEN <= destack->front) return NULL;
 695         else
 696         {
 697             destack->back -= ALIGNED_LEN;
 698             uint8_t *const restrict ptr = ( uint8_t* )destack->back;
 699             return ptr;
 700         }
 701     }
 702 }
 703
 704 void BiStackResetFront(BiStack *const destack)
 705 {
 706     if (destack->mem == 0) return;
 707     else destack->front = destack->mem;
 708 }
 709
 710 void BiStackResetBack(BiStack *const destack)
 711 {
 712     if (destack->mem == 0) return;
 713     else destack->back = destack->mem + destack->size;
 714 }
 715
 716 void BiStackResetAll(BiStack *const destack)
 717 {
 718     BiStackResetBack(destack);
 719     BiStackResetFront(destack);
 720 }
 721
 722 inline intptr_t BiStackMargins(const BiStack destack)
 723 {
 724     return destack.back - destack.front;
 725 }
 726
 727 #endif  // RMEM_IMPLEMENTATION
 728
 729 /*******
 730  * Changelog
 731  * v1.0: First Creation.
 732  * v1.1: bug patches for the mempool and addition of object pool.
 733  * v1.2: addition of bidirectional arena.
 734  * v1.3:
 735     * optimizations of allocators.
 736     * renamed 'Stack' to 'Arena'.
 737     * replaced certain define constants with an anonymous enum.
 738     * refactored MemPool to no longer require active or deferred defragging.
 739  ********/