{"id":44655584,"url":"https://github.com/johsteffens/tbman","last_synced_at":"2026-02-27T09:01:15.152Z","repository":{"id":157217313,"uuid":"104779148","full_name":"johsteffens/tbman","owner":"johsteffens","description":"Memory Manager - Fast, Scalable and Easy to use","archived":false,"fork":false,"pushed_at":"2025-10-22T08:11:48.000Z","size":319,"stargazers_count":32,"open_issues_count":0,"forks_count":11,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-10-22T10:11:26.515Z","etag":null,"topics":["alignment","free","malloc","malloc-free","memory-manager","platform-independent","realloc","thread-safe"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/johsteffens.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2017-09-25T17:13:42.000Z","updated_at":"2025-10-22T08:11:52.000Z","dependencies_parsed_at":"2025-10-22T10:08:03.100Z","dependency_job_id":"19655f32-92ac-454e-8c8b-447efd1d447e","html_url":"https://github.com/johsteffens/tbman","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/johsteffens/tbman","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johsteffens%2Ftbman","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johsteffens%2Ftbman/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johsteffens%2Ftbman/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johsteffens%2Ftbman/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johsteffens","download_url":"https://codeload.github.com/johsteffens/tbman/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johsteffens%2Ftbman/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29888777,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-27T08:34:21.514Z","status":"ssl_error","status_checked_at":"2026-02-27T08:32:38.035Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alignment","free","malloc","malloc-free","memory-manager","platform-independent","realloc","thread-safe"],"created_at":"2026-02-14T22:00:25.252Z","updated_at":"2026-02-27T09:01:15.137Z","avatar_url":"https://github.com/johsteffens.png","language":"C","funding_links":[],"categories":["memory manager"],"sub_categories":["dynamic malloc"],"readme":"# Tbman - Fast and Easy Memory Manager\n\n## Table of Content\n\n   * [What it is](#anchor_what_it_is)\n   * [Benefits](#anchor_benefits)\n   * [How to use it](#anchor_how_to_use_it)\n   * [Detailed Description](#anchor_features)\n      * [Basics](#anchor_basic)\n      * [Faster collection](#anchor_faster_collection)\n      * [One function for everything](#anchor_one_function_for_everything)\n      * [Advanced Alignment](#anchor_advanced_alignment)\n      * [Granted Memory](#anchor_granted_memory)\n      * [Diagnostic Features](#anchor_diagnostic_features)\n      * [Thread safety](#anchor_thread_safety)\n      * [Multiple managers](#anchor_multiple_managers)\n      * [Mixing different memory managers](#anchor_mixing_different_memory_managers)\n   * [Side effects](#anchor_side_effects)\n      * [Prefetching](#anchor_prefetching)\n      * [Unused Memory](#anchor_unused_memory)\n      * [Memory Model](#anchor_memory_model)\n      * [Debugging Tools](#anchor_debugging_tools)\n   * [How it works internally](#anchor_how_it_works_internally)\n   * [Motivation/Origin](#anchor_motivation)\n\n\u003ca name=\"anchor_what_it_is\"\u003e\u003c/a\u003e\n# What it is\n\nTbman is a general-purpose memory manager offering (among others) these functions\n\n`tbman_malloc, tbman_free, tbman_realloc`,\n\nwhich can replace corresponding stdlib functions\n\n`malloc, free, realloc`,\n\nin C and C++ code.\n\n\u003ca name=\"anchor_benefits\"\u003e\u003c/a\u003e\n# Benefits\n\n* Very fast. ([*You can easily verify this yourself.*](#anchor_quick_evaluation))\n* Low fragmentation of system memory.\n* Few system calls.\n* [Advanced Alignment](#anchor_advanced_alignment).\n* [Integrated Leak Detection](#anchor_integrated_leak_detection)\n* [Diagnostic Features](#anchor_diagnostic_features)\n* [Granted Memory](#anchor_granted_memory)\n* [Platform Independence](#anchor_build_requirements)\n\n\u003ca name=\"anchor_how_to_use_it\"\u003e\u003c/a\u003e\n# How to use it\n\n* `$ git clone https://github.com/johsteffens/tbman.git`\n\n\u003ca name=\"anchor_build_requirements\"\u003e\u003c/a\u003e\n## In your workspace\n\n   * Compile `tbman.c` and `btree.c` (either among your source files or into a static library)\n   * In your code:\n      * `#include \"tbman.h\"`\n      * Call once `tbman_open();` at the beginning or your program. *(E.g. first in `main()`)*\n      * Use `tbman_*` - functions anywhere.\n      * Call once `tbman_close();` at the end or your program. *(E.g. last in `main()`)*\n\n## C++\n\nIn object oriented C++ programming, the direct use of `malloc`, `realloc` or `free` is discouraged in favor of \nusing operators `new` and `delete`, which take care of object construction/destruction. \nHowever, you can overload these operators. This gives you control over the part concerned with memory allocation.\n\n**Example:**\n\nIf you add the code below to your program, operators `new` and `delete` will work as intended but use tbman\nfor allocating and freeing memory.\n\n```C++\nvoid* operator new( size_t size )\n{\n    return tbman_malloc( size ); \n}\n\nvoid operator delete( void* p )\n{\n    tbman_free( p ); \n}\n```\n\n\u003ca name=\"anchor_quick_evaluation\"\u003e\u003c/a\u003e\n## Quick Evaluation\n\n`eval.c` is an evaluation program simulating realistic runtime conditions for a memory manager. \nIt verifies correct functionality and assesses the processing speed. \nIt compares the performance of stdlib functions with tbman functions. \nYou can quickly run it yourself.\n\nEnter the folder with source files:\n```\n$ gcc -std=c11 -O3 btree.c tbman.c eval.c -lm -lpthread\n$ ./a.out\n```\n\n## Requirements/Dependencies\n\n   * Compiler supporting the C11 standard (e.g. gcc, clang).\n   * Compiler options: `-std=c11`, `-O3` for max speed; (or compatible settings)\n   * Linker options: `-lm -lpthread` (or compatible settings)\n   * **POSIX**: Out of the box, tbman relies on two features, which are normally available on POSIX compliant systems\n      * [Flat Memory Model](#anchor_memory_model).\n      * Library pthread: Tbman uses `pthread_mutex_t` (locking) for thread safety in `tbman.c`.\n      * The following platforms have sufficient POSIX compliance: **Linux, Android, Darwin (and related OS)**\n\n   * **If pthread is not available, try one of the folowing options ...**:\n      * Check if the \u0026#x1F517;[Tread Support Library](https://en.cppreference.com/w/c/thread) is available for your traget platform. In tbman.c: Use **mtx_t** instead of **pthread_mutex_t**; replace functions **pthread_mutex_...** with corresponding functions **mtx_...**; use **call_once** instead of **pthread_once**.\n\n      * If you have other native locks available: In `tbman.c`: Replace pthread-locks by native locks.\n\n      * **Windows**: You can setup a posix subsystem\n         * [Set up a POSIX-environment via cygwin.](https://github.com/johsteffens/beth/wiki/Requirements#how-to-setup-a-posix-environment-for-beth-on-windows)\n         * Windows 10: Provides an optional Linux-Subsystem.\n\n\u003ca name=\"anchor_features\"\u003e\u003c/a\u003e\n# Detailed Description\n\n\u003ca name=\"anchor_basic\"\u003e\u003c/a\u003e\n## Basics\n\nTbman offers the three basic functions of a memory manager:\n\n```C\nvoid* tbman_malloc(             size_t size ); // pure allocation\nvoid* tbman_realloc( void* ptr, size_t size ); // reallocation\nvoid  tbman_free(    void* ptr              ); // freeing\n```\nUsage and behavior is compatible to corresponding stdlib functions `malloc`, `free`, `realloc`.\n\u003cbr\u003e\u003csub\u003eException: Should the entire system run out of available memory,\ntbman aborts with an error message to stderr.\u003c/sub\u003e\n\nTbman must be initialized once before usage. It should also be properly closed at the end of the program. \nThese two functions take care of it:\n\n```C\nvoid tbman_open( void );  // initializes tbman\nvoid tbman_close( void ); // closes tbman\n```\n**Example:**\n\n```C\nint main( int argc, char* argv[] )\n{\n   tbman_open();\n\n   ... // my program\n\n   tbman_close();\n   return my_exit_state;\n}\n```\n\n\u003ca name=\"anchor_faster_collection\"\u003e\u003c/a\u003e\n## Faster collection\n\nIf you free or reallocate memory and know the previously allocated amount, you can further speed up processing by \ntelling tbman about the currently allocated size using `tbman_nrealloc` and `tbman_nfree`. \nThis helps the manager finding the corresponding node for the memory instance faster.\n\n```C\n// realloc with size communication\nvoid* tbman_nrealloc( void* current_ptr, size_t current_size, size_t new_size ); \n\n// free with size communication\nvoid  tbman_nfree( void* current_ptr, size_t current_size );\n```\n`current_size` must hold either the requested amount or the [granted amount](#anchor_granted_memory)\nfor the memory instance addressed by `current_ptr`.\n\n\u003ca name=\"anchor_one_function_for_everything\"\u003e\u003c/a\u003e\n## One function for everything\n\nAlternatively, you can use just one of the following two functions for all memory management including some special features of tbman.\n\n```C\nvoid* tbman_alloc(  void* current_ptr,                      size_t requested_size, size_t* granted_size );\nvoid* tbman_nalloc( void* current_ptr, size_t current_size, size_t requested_size, size_t* granted_size );\n```\n`tbman_nalloc` works slightly faster than `tbman_alloc` but requires extra size input.\nThe two functions can also be mixed; even serving the same memory instance.\n\n### Arguments\n\n| Name      | Description  |\n| :----     | :---------------------------  |\n| **`current_ptr`**    | Pointer to current memory instance for freeing or reallocating. \u003cbr\u003e Set to `NULL` for pure allocation. |\n| **`current_size`**   | Previously requested or [granted size](#anchor_granted_memory) for freeing or reallocating a memory instance. \u003cbr\u003e Set to `0` for pure allocation. |\n| **`requested_size`** | Requested new size pure allocation or reallocation.\u003cbr\u003e Set to `0` for freeing.|\n| **`granted_size`** | Optional pointer to variable where the function stores the [granted amount](#anchor_granted_memory).\u003cbr\u003e Set to `NULL` when not needed. |\n\n### Return value\n\nPointer to new memory instance for pure allocation or reallocation. Returns `NULL` in case of freeing.\n\n\u003ca name=\"anchor_advanced_alignment\"\u003e\u003c/a\u003e\n## Advanced Alignment\n\nTbman aligns the memory instance selectively. \nThis covers all standard C/C++ data types `char, short, int, float, double, etc`\nand also larger types such as `int32x4_t, float32x4_t, etc`, which are typically \nused for SIMD-extensions such as `SSE, AVX, NEON, etc`.\n\n**Example:**\n\n```C\nint32x4_t* my_data = tbman_malloc( sizeof( int32x4_t ) * 10 ); // aligned array of 10 x int32x4_t\n```\n\n\u003ca name=\"anchor_granted_memory\"\u003e\u003c/a\u003e\n## Granted Memory\n\nFor design reasons, tbman might find no proper use for some space immediately following your requested memory block.\nIn that case, it grants you that extra space, appending it to your request.\nYou may use the granted space as if you had requested it in the first place.\n\u003cbr\u003e\u003csub\u003e*(Note: Tbman never grants less than requested.)*\u003c/sub\u003e\n\nThis feature is a special resource for optimizing speed and memory efficiency\nof objects that vary allocation size during lifetime.\nIt is extensively used in [beth](https://github.com/johsteffens/beth) on dynamic arrays.\n\nFunction `tbman_alloc` lets you allocate with the [granted amount communicated](#anchor_one_function_for_everything).\nYou can retrieve the granted amount for a given instance using function `tbman_granted_space`:\n\n```C\n// Allocation with granted amount communicated.\nvoid* tbman_alloc( void* current_ptr, size_t requested_size, size_t* granted_size );\n\n// Explicit query for the granted amount from an already existing memory instance\nsize_t tbman_granted_space( const void* ptr );\n```\n\n**Example:**\n\n```C\nsize_t requested_space = 5;\nsize_t granted_space;\nchar* my_string = tbman_alloc( NULL, requested_space, \u0026granted_space );\n// At this point granted_space \u003e= requested_space. Using that extra space is allowed.\n\n// To visualize, we fill the requested and extra space with different characters:\nfor( size_t i = 0; i \u003c requested_space - 1; i++ ) my_string[ i ] = '=';\nfor( size_t i = requested_space - 1; i \u003c granted_space - 1; i++ ) my_string[ i ] = '#';\nmy_string[ granted_space - 1 ] = 0;\n\n// Possible output:\n// ====###\nprintf( \"%s\\n\", my_string );\n```\n\n\u003ca name=\"anchor_diagnostic_features\"\u003e\u003c/a\u003e\n## Diagnostic Features\n\nTbman offers a few features for advanced memory analysis.\nThey are useful for debugging, ensuring memory integrity or even developing a garbage-collection scheme.\n\n\u003ca name=\"anchor_integrated_leak_detection\"\u003e\u003c/a\u003e\n### Integrated Leak Detection\n\nFunctions `tbman_close()` and `tbman_s_close()` check for leaking memory instances.\nThese are instances allocated but not freed before closing the manager.\nIf any are found, a message is send to stderr.\n\n**Example:**\n\n```C\ntbman_open();\n\n// We are deliberately leaking some memory.\ntbman_malloc( 16 );\ntbman_malloc( 8 );\n\n// tbman_close() will produce a message like this:\n// TBMAN WARNING: Detected 2 instances with a total of 24 bytes leaking space.\ntbman_close();\n```\n\n\u003ca name=\"anchor_memory_tracking\"\u003e\u003c/a\u003e\n### Memory Tracking\n\nYou can query the total of tbman-allocations at any point in your program. The following functions do this:\n```C\n// returns the current number of allocations (memory instances)\nsize_t tbman_total_instances( void );\n\n// returns the number of bytes currently allocated\nsize_t tbman_total_granted_space( void ); \n```\nPossible use-cases:\n\n   * Hunting down memory leaks.\n   * Assessing the memory footprint of a program, sections thereof or of specific objects.\n\n**Example:**\n\n```C\nsize_t prior_space = tbman_total_granted_space();\nsize_t prior_insts = tbman_total_instances();\n\n... // section to be tested for leaks\n\nsize_t leaking_space = tbman_total_granted_space() - prior_space;\nsize_t leaking_insts = tbman_total_instances() - prior_insts;\nif( leaking_insts \u003e 0 )\n{\n    fprintf( stderr, \n        \"Memory leak of %zu bytes detected. %zu instances were not freed.\\n\", \n        leaking_space, \n        leaking_insts );\n}\n```\n\n\u003ca name=\"anchor_memory_tracking\"\u003e\u003c/a\u003e\n### Iterating through instances\n\nThe following function lets you iterate through all instances currently allocated:\n\n```C\nvoid tbman_for_each_instance( \n    void (*cb)( void* arg, void* ptr, size_t space ), \n    void* arg );\n```\n\n`cb` is a *callback function*. It is called for each instance active at the time of calling `tbman_for_each_instance`.\n\n#### Arguments\n\n| Name      | Description  |\n| :----     | :---------------------------  |\n| **`cb`**    | Pointer to callback function |\n| **`arg`**   | Custom argument passed to each callback |\n| **`ptr`**   | Address of the memory instance |\n| **`space`** | Number of bytes granted to the instance |\n\nChanging tbman's state inside a callback function is allowed. E.g. The callback function may free or allocate memory.\nKeep in mind, though, that all instances, producing a callback, are determined before executing the first callback.\nFreeing or allocating inside a callback will therefore not affect the callback-order.\nIt will only affect the next call to `tbman_for_each_instance`.\n\n**Example:**\n\nA trivial garbage collector, simply freeing all remaining open instances and counting them.\n\n```C\n// frees the instance assuming arg references a counter\nvoid free_instance_callback( void* arg, void* ptr, size_t space )\n{\n    tbman_nalloc( ptr, space, 0, NULL );\n    if( arg ) (*(size_t*)arg)++;\n} \n```\n\n```C\n... // somewhere in code\nsize_t count = 0;\ntbman_for_each_instance( free_instance_callback, \u0026count );\nprintf( \"%zu instances were freed.\\n\", count );\n\n```\n\n\u003ca name=\"anchor_thread_safety\"\u003e\u003c/a\u003e\n## Thread safety\n\nTbman is thread safe: The interface functions can be called any time from any thread simultaneously.\nMemory allocated in one thread can be freed in any other thread.\n\nConcurrency is governed by a mutex.\nThis means that memory management is not lock-free.\nNormally, this will not significantly affect processing speed for typical multi threaded programs.\nOnly during heavvy simultaneous usage of the same manager lock-contention time might be noticeable\ncompared to single threaded usage.\n\n\u003ca name=\"anchor_multiple_managers\"\u003e\u003c/a\u003e\n## Multiple managers\n\nFunctions `tbman_` above relate to global management (one manager for everything).\nYou can also create multiple individual, independent and dedicated managers using the the `tbman_s` object.\nEach manager has its own mutex.\nThis is particularly helpful in a multi threaded context.\nGiving each thread its own manager for thread-local memory can reduce lock-contention.\n\nFor each of above functions `tbman_` there exists a corresponding function with postfix `_s`\nmeant for a dedicated manager instance.\nExcept `tbman_s_open`, all functions `tbman_s_` take as first argument the reference to the dedicated manager instance.\n\n**Example:**\n\n```C \ntbman_s* my_man = tbman_s_open(); // opens a dedicated manager\nchar* my_memory = tbman_s_malloc( my_man, 1024 );\n... // do something else\ntbman_s_free( my_man, my_memory );  \ntbman_s_close( my_man ); // closes a dedicated manager\n```\n\u003ca name=\"anchor_mixing_different_memory_managers\"\u003e\u003c/a\u003e\n## Mixing different memory managers\n\nTbman does not affect the behavior of other memory managers (such as `malloc`, `free`, `realloc`),\nso you can mix code using different management systems.\n\nHowever, different managers can not serve the **same memory instance**.\nFor example: You can not use `free` or `realloc` on a memory instance,\nwhich was allocated with `tbman_malloc` (`tbman_realloc`) or vice versa.\n\nLikewise, you can not manage the same memory instance with different [dedicated managers](#anchor_multiple_managers).\n\n\u003ca name=\"anchor_side_effects\"\u003e\u003c/a\u003e\n# Side effects\n\nBelow are some side effects you should be aware of.\nWe believe they are tolerable for the vast majority of use cases.\n\n\u003ca name=\"anchor_prefetching\"\u003e\u003c/a\u003e\n## Prefetching\n\nTbman reserves and returns system memory in larger chunks to offload the system.\nThat means that the memory your application reserves at a given time is likely\nhigher than if you use system functions directly.\n\n\u003ca name=\"anchor_unused_memory\"\u003e\u003c/a\u003e\n## Unused Memory\n\nTbman organizes memory instances into slots with a predefined size distribution.\nFor an allocation request, the best fitting slot is selected and the full slot-size is [granted](#anchor_granted_memory).\nIf you do not need that extra amount, it is wasted.\nTests have shown that in realistic situations this overhead tends to average around 10% ... 30% of the requested memory.\n\n*Note that also other memory managers reserve excess memory and/or render memory sections\ntemporarily unusable (e.g. due to fragmentation).\nWhich manager is most efficient depends on the use case.*\n\n\u003ca name=\"anchor_memory_model\"\u003e\u003c/a\u003e\n## Memory Model\n\nTbman expects a flat memory model. More specifically, it requires the following behavior:\n\nIf two pointers `ptr1`, `ptr2` reference valid but **different** objects anywhere in the application's addressable\nmemory space, then `( ptrdiff_t )( ptr1 - ptr2 )` can never be zero.\n\nAlthough this sounds like a no-brainer, it actually goes beyond the standard C provisions.\nStd. C allows the compiler implementation to leave the result of pointer subtraction undefined if the objects are\nnot of the same array- or structure-instance.\n(see [cppreference.com: Pointer arithmetic](https://en.cppreference.com/w/c/language/operator_arithmetic#Pointer_arithmetic).)\n\n*Note that most modern platforms employ a flat memory model.\nVery old systems, like early x86 platforms, use a segmented memory model\n(segment:offset) where only the offset participates in pointer arithmetic.\nOn that model tbman would not work correctly.*\n\n\u003ca name=\"anchor_debugging_tools\"\u003e\u003c/a\u003e\n## Debugging Tools\n\nCertain debugging tools (e.g. [valgrind](http://www.valgrind.org)) can analyze the memory integrity of a program.\nOne of the methods employed is capturing interactions of the program with the system.\n\nSince tbman represents an intermediate layer between your program and the system,\neffectively reducing system interactions, such a tool might capture less activity. For example,\nit might not recognize all the boundaries of a single tbman-allocation and can therefore\nnot verify the validity of all types of block-access by the program.\nSince `tbman_close()` returns all [tbman-pools](#anchor_block-pooling-layer) to the system,\nthe tool might also not detect all possible memory leaks.\n\nFunction `tbman_close` [checks for leaks](#anchor_integrated_leak_detection) and reports them to stderr,\nwhich should alleviate the last side effect for most practical purposes.\n\nYou can can also create a custom-check for leaks in your program by testing\n`tbman_total_granted_space()` before closing tbman:\n\n**Example:**\n\n```C \nint main( int argc, char* argv[] )\n{\n   tbman_open();\n   \n   ... // my program\n   \n   if( tbman_total_granted_space() \u003e 0 )\n   {\n      fprintf( stderr, \"Memory leak of %zu bytes detected.\\n\", tbman_total_granted_space() );\n   }\n   tbman_close();\n   return my_exit_state;\n}\n```\n\n\u003ca name=\"anchor_how_it_works_internally\"\u003e\u003c/a\u003e\n# How it works internally\n\n\u003ca name=\"anchor_block-pooling-layer\"\u003e\u003c/a\u003e\n## Block-Pooling-Layer with Tokens\n\nTbman represents a dedicated management layer, which sits between your code and the system. It communicates with the system to obtain/return larger memory blocks, which are subdivided for dispatching/recollection in your program.\n\nTbman uses \"conservative\" memory pooling with multiple fixed size block-managers at a strategic size-distribution.\nMultiple pools are managed in a btree.\nWhen the client (your code) requests or returns small-medium sized memory instances,\ntbman dispatches/recollects pool memory accordingly without initiating system requests.\nSystem requests are executed infrequently in order to acquire a new pool or return an empty pool.\nThis offloads the system manager significantly.\nCompared to always using system calls it can speed up overall processing and/or reduce fragmentation,\nparticularly in programs where many small sized memory instances are used.\n\nEach memory instance is associated with an internal node controlled by tbman.\nThe manager dedicates separate memory areas for node-data and user space (user space == memory space used by the client).\nThe content of user space does not affect node management.\n\nA special design feature is binding the allocated memory address to the address of the associated node in tbman.\nThis allows fast node retrieval at O(1) complexity. Since the association is address-based (and not meta-data-based\nas typical in some conventional memory managers),\nit cannot be altered or destroyed by a faulty memory override in user space. Hence, specific software bugs such as using a \ndangling pointer (pointer to already collected memory) or writing past allocated space, are less likely to affect manager's\nintegrity. (Such bugs still affect the integrity of your program, though.).\n\nThe design ensures very low latency for allocation and collection and it gives this manager its name:\ntbman = token-block-manager.\n\nWhen the client requests a large memory instance, where pooling would be wasteful,\ntbman falls back to using a direct system call.\nHowever, it [keeps track](#anchor_memory_tracking) of all memory.\n\n## Memory alignment\n\nTbman analyzes the requested size.\nIf you allocate an instance or array of type `my_type` with `sizeof( my_type )` being a power of two not larger than\n[`TBMAN_ALIGN`](https://github.com/johsteffens/tbman/blob/848bebed1648d66d1fe101ee19f4803fed8ea81a/tbman.c#L43),\nthen the memory block is alinged to `sizeof( my_type )`.\nMore generally: When requesting memory of _**s**_ bytes and _**s**_ can be expressed as product of two positive\nintegers _**s**_ = _**m**\\***n**_ such that _**m**_ is a power of 2,\nthen the returned memory is aligned to the lesser of _**m**_ and\n[`TBMAN_ALIGN`](https://github.com/johsteffens/tbman/blob/848bebed1648d66d1fe101ee19f4803fed8ea81a/tbman.c#L43).\n\n\u003ca name=\"anchor_motivation\"\u003e\u003c/a\u003e\n# Motivation / Origin\n\nI conceived and developed tbman originally for my project\n[beth](https://github.com/johsteffens/beth).\n\nFor those interested in elementary memory management\nbut not keen on digesting the whole of project beth, \nI offer herewith a simplified but better documented spin-off.\n\nThe beth-memory-manager has some aditional features\n\n   * Integrated Reference Management\n   * Garbage Collection \n   * ... and more\n\nLocation: [beth/lib/bcore/](https://github.com/johsteffens/beth/tree/master/lib/bcore)bcore_tbman.*\n*(Note that for [beth](https://github.com/johsteffens/beth) I chose a different\n[license](https://github.com/johsteffens/beth/blob/master/LICENSE).)*\n\n------\n\nThanks for reading. If you find it useful, have questions or suggestions I'd be happy to hear from you.\n\n\u003csub\u003e\u0026copy; Johannes B. Steffens\u003c/sub\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohsteffens%2Ftbman","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohsteffens%2Ftbman","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohsteffens%2Ftbman/lists"}