{"id":13729583,"url":"https://github.com/HDembinski/stateful_pointer","last_synced_at":"2025-05-08T02:30:26.912Z","repository":{"id":69353658,"uuid":"103676148","full_name":"HDembinski/stateful_pointer","owner":"HDembinski","description":"Use unused bits in your pointer","archived":false,"fork":false,"pushed_at":"2017-10-04T16:14:28.000Z","size":65,"stargazers_count":45,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-03T15:21:14.796Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HDembinski.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}},"created_at":"2017-09-15T16:03:46.000Z","updated_at":"2025-03-24T12:15:57.000Z","dependencies_parsed_at":"2023-02-22T08:30:43.360Z","dependency_job_id":null,"html_url":"https://github.com/HDembinski/stateful_pointer","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HDembinski%2Fstateful_pointer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HDembinski%2Fstateful_pointer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HDembinski%2Fstateful_pointer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HDembinski%2Fstateful_pointer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HDembinski","download_url":"https://codeload.github.com/HDembinski/stateful_pointer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252986514,"owners_count":21836169,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-08-03T02:01:02.646Z","updated_at":"2025-05-08T02:30:26.654Z","avatar_url":"https://github.com/HDembinski.png","language":"C++","readme":"# Stateful Pointer Library\n\nSometimes space is tight! What if you could squeeze *extra state* into a pointer *at (almost) no additional cost*?\n\nA pointer occupies 32 or 64 bit, which is 4 or 8 bytes just to remember a memory address. On common hardware-platforms, some bits of the address are not used, because the computer allocates *aligned* memory addresses which are multiples of an alignment value. The *Stateful Pointer Library* is a C++11 header-only library which provides safe access to those bits. It contains a smart pointer that mimics `std::unique_ptr`, but allows you to use up to 24 bits to store extra state inside the pointer in a safe way. These freely useable bits are encoded inside the pointer itself and occupy *no extra space*.\n\nThe library uses [Boost.Align](http://www.boost.org/doc/libs/1_65_1/doc/html/align.html) to allocate aligned memory. On most platforms (Windows, MacOS, Linux, Android, ...), special system calls are used to get aligned memory at no additional cost. On other platforms, extra memory is allocated to guarantee the alignment of the pointer. The amount grows with the number of bits in the pointer that are used to carry extra state. In either case, the pointers of the *Stateful Pointer Library* are guaranteed to have the same size as a normal pointer.\n\n**Platform dependence**: The library relies on two platform-dependent aspects of memory handling.\n\n * Memory addresses map trivially to consecutive integral numbers.\n * The address of aligned memory, in its representation as an integral number, is an exact multiple of the alignment value.\n\nThe C++ standard not does guarantee these properties, as explained on [StackOverflow](https://stackoverflow.com/questions/34737737/relation-between-numeric-representation-of-memory-address-and-alignment). Nevertheless, common platforms in use today seem to support this simple memory addressing scheme. There is no guarantee, of course, that future platforms will do the same, so use this library with caution. Many thanks go to [the knowledgable Redditors](https://redd.it/73rr47) who pointed all this out.\n\n**Caveat**: The library uses custom memory allocation to do its magic, so it does *not* work with classes/environments that also customize heap allocation.\n\nCode is released under the **Boost Software License v1.0** (see LICENSE file).\n\n## Tagged pointer\n\nLike `std::unique_ptr` in interface and behavior, but encodes `N` extra bits of information inside the pointer, using no additional space.\n\n```c++\n#include \"stateful_pointer/tagged_ptr.hpp\"\n#include \"boost/utility/binary.hpp\" // macro to make binary literals\n#include \u003ccassert\u003e\n#include \u003ciostream\u003e\n\nusing namespace stateful_pointer;\n\n// class to be allocated on the heap\nstruct A {\n    int a;\n    A(int x) : a(x) {}\n};\n\nint main() {\n    // tagged_ptr has the same size as a normal pointer\n    assert(sizeof(tagged_ptr\u003cA, 4\u003e) == sizeof(void*));\n\n    // make tagged_ptr to an instance of A with 4 bits of extra state\n    auto p = make_tagged\u003cA, 4\u003e(3); // 3 is passed to the ctor of A\n\n    // set the 4 bits to some values\n    p.bits(BOOST_BINARY( 1010 )); // that's 10 in decimal\n\n    std::cout \u003c\u003c \"a = \" \u003c\u003c p-\u003ea \u003c\u003c \", bits = \" \u003c\u003c p.bits() \u003c\u003c std::endl;\n\n    // prints: \"a = 3, bits = 10\"\n}\n```\n\n## String\n\nThe World's most compact STL-compatible string with *small string optimization*. Has the size of a mere pointer and yet stores up to 7 characters (on a 64-bit system) without allocating extra memory on the heap.\n\n```c++\n#include \"stateful_pointer/string.hpp\"\n#include \u003ccassert\u003e\n#include \u003ciostream\u003e\n\nusing namespace stateful_pointer;\n\nint main() {\n    // string has the same size as a normal pointer\n    assert(sizeof(string) == sizeof(void*));\n\n    string s(\"foo bar\"); // small string optimisation: no heap allocation\n    std::cout \u003c\u003c s \u003c\u003c std::endl;\n\n    // prints: \"foo bar\"\n}\n```\n\nThis one is still in development, a lot of the standard interface is still missing.\n\n## Performance\n\n### `tagged_ptr` vs `std::unique_ptr`\n\nIn optimized builds, the performance is similar. Most importantly, access is as fast. Pointer creation is at most 10 % slower and becomes negligible compared to the allocation and initialization cost of larger pointees.\n\n|Benchmark                                   |CPU [ns]|\n|:-------------------------------------------|-------:|\n|`unique_ptr_creation\u003cchar\u003e`                 |      29|\n|`tagged_ptr_creation\u003cchar\u003e`                 |      32|\n|`unique_ptr_creation\u003cstd::array\u003cchar, 256\u003e\u003e`|      70|\n|`tagged_ptr_creation\u003cstd::array\u003cchar, 256\u003e\u003e`|      72|\n|`unique_ptr_access\u003cchar\u003e`                   |       2|\n|`tagged_ptr_access\u003cchar\u003e`                   |       2|\n|`unique_ptr_access\u003cstd::array\u003cchar, 256\u003e\u003e`  |       2|\n|`tagged_ptr_access\u003cstd::array\u003cchar, 256\u003e\u003e`  |       2|\n\n([Google benchmark library](https://github.com/google/benchmark) run on 4x3GHz CPUs, compiled with -O3)\n","funding_links":[],"categories":["C++"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHDembinski%2Fstateful_pointer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FHDembinski%2Fstateful_pointer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FHDembinski%2Fstateful_pointer/lists"}