{"id":19564373,"url":"https://github.com/ronenness/bucketalerts","last_synced_at":"2026-06-11T03:31:44.360Z","repository":{"id":82588212,"uuid":"127956259","full_name":"RonenNess/BucketAlerts","owner":"RonenNess","description":"C++ Library for Token-Buckets based alerts.","archived":false,"fork":false,"pushed_at":"2018-04-03T19:34:42.000Z","size":14,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-26T09:24:13.672Z","etag":null,"topics":["alerts","cpp","cpp11","events","token-bucket"],"latest_commit_sha":null,"homepage":null,"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/RonenNess.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}},"created_at":"2018-04-03T19:09:01.000Z","updated_at":"2024-01-13T23:58:07.000Z","dependencies_parsed_at":null,"dependency_job_id":"6824ef40-480e-4d18-8df8-063152ba5177","html_url":"https://github.com/RonenNess/BucketAlerts","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/RonenNess/BucketAlerts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RonenNess%2FBucketAlerts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RonenNess%2FBucketAlerts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RonenNess%2FBucketAlerts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RonenNess%2FBucketAlerts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RonenNess","download_url":"https://codeload.github.com/RonenNess/BucketAlerts/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RonenNess%2FBucketAlerts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34181554,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["alerts","cpp","cpp11","events","token-bucket"],"created_at":"2024-11-11T05:21:42.164Z","updated_at":"2026-06-11T03:31:44.333Z","avatar_url":"https://github.com/RonenNess.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BucketAlerts\n\nLibrary for Token-Buckets based alerts.\n\n## What Is It\n\n`BucketAlerts` uses Token Buckets to generate events after a specific resource or function was used too much.\n\nIf you don't know what it is, a [Token Bucket](https://en.wikipedia.org/wiki/Token_bucket) is an algorithm typically used in networking to create limits on bandwidth while supporting burstiness.\n\nThis lib simply implement a basic Token Bucket object + Managers with callbacks, to provide a more logger-like API and allow you to easily define different buckets and register to their events.\n\n### Why\n\nI was working on a scene tree with 3d transformations that had a mechanism to cache transformations matrix internally, so objects won't constantly update when its not necessary. In small 'lab condition' tests it seemed to work perfectly, but as the scenes grew complicated and bigger I began to suspect that the mechanism may be broken.\n\nHowever, debugging it was tricky. Putting a breakpoint or a log on the update event was useless because in a large scenes it naturally happens a lot and from many different objects. Its also OK for a specific object to update often and many times, just not *too* often. I needed to break on a very special case, when the same object was updating too much over a longer period of time.\n\nThat's when I realized I need a token-bucket mechanism that could detect these events. Later I found it to be useful for other cases and projects (like detecting when two objects are \"stuck\" on each other and constantly colliding) and decided to port it to CPP and make it slightly more generic.\n\nThis lib can be used for debugging, logging, or even to respond to real events of resources abuse.\n\n## Install\n\nThere's no dll / lib built, so just grab the source and include / build it yourself.\n\n## Usage\n\nHere's a quick usage example:\n\n```cpp\n#include \"Source/AlertsManager.h\"\n\n// test bucket category and name\n#define TEST_CATEGORY 5\n#define TEST_BUCKET 15\n\nint main()\n{\n\t// create a bucket with category 'TEST_CATEGORY' and id 'TEST_BUCKET'\n\tBucketAlerts::get_main().CreateBucket(TEST_CATEGORY, TEST_BUCKET, 5, 10, 1, \n\t\t[](const BucketAlerts::TokenBucket\u0026 bucket) {\n\t\t\tstd::cout \u003c\u003c \"Bucket Exhausted!\" \u003c\u003c std::endl;\n\t});\n\t\n\t// consume 1 token\n\tBucketAlerts::get_main().Consume(TEST_CATEGORY, TEST_BUCKET, 1.0);\n}\n```\n\nNow lets explain the code above:\n\nTo manage the token buckets we use a manager called `Alerts Manager`. Calling `BucketAlerts::get_main()` will return a default static instance of it, but you can also create your own instances if you need to manage different pools of buckets.\n\nIn the first line of code we create a new bucket.\n\n`Category Id` is not mandatory (there's a version of CreateBucket without this argument) but useful to group together buckets under a common subject. For example, things like \"Memory Allocation\", \"Update Calls\", etc.\n\n`Bucket Id` is what identifies the bucket itself. It should represent the actual cause of the resource consumption or the related object id.\n\nThe next 3 numbers define the bucket starting size, max tokens, and how many new tokens it will replenish per second (tokens replenish automatically when you try to consume). \n\nAnd the final argument is the callback to trigger when someone tries to consume tokens but don't have enough left in the bucket.\n\nNext and final line in the example shows how to consume 1 token from the bucket. If we ran out of tokens this function will return false and trigger the alert (note however that the tokens will still be consumed).\n\n### Without Category Id\n\nIf you don't want to use categories for your buckets, the code above would look like this:\n\n```cpp\n// create a bucket with id 'TEST_BUCKET'\nBucketAlerts::get_main().CreateBucket(TEST_BUCKET, 5, 10, 1, \n\t[](const BucketAlerts::TokenBucket\u0026 bucket) {\n\t\t\tstd::cout \u003c\u003c \"Bucket Exhausted!\" \u003c\u003c std::endl;\n});\n\n// consume 1 token\nBucketAlerts::get_main().Consume(TEST_BUCKET, 1.0);\n```\n\n### Using Custom Managers\n\nAs mentioned before, you don't have to use the default `Alerts Manager`. To create your own manager simply instantiate a `AlertsManager` class:\n\n```cpp\nBucketAlerts::AlertsManager manager();\n```\n\nAnd use it just like you would use `BucketAlerts::get_main()`.\n\n### AlertsManager API\n\nThe following are some other useful functions you should know about `Alerts Manager`:\n\n#### GetBucket()\n\nReturn a bucket reference by id and optional category.\n\n#### Restore()\n\nRestore tokens to bucket.\n\n#### ResetAll()\n\nReset all bucket to their starting value.\n\n#### Clear()\n\nRemove all buckets.\n\n#### ManualUpdate()\n\nForce all buckets to recalculate their remaining tokens based on last time they were accessed. Normally you don't need to call this.\n\n#### Enabled\n\nSet to false to temporarily disable all consuming and alerts (will just return true and do nothing instead of consuming). This is useful if you have a special user-invoked action or a heavy initialization step that you don't want to trigger alerts.\n\n### TokenBucket\n\nYou can create and use token buckets yourself, without any `Alert Managers` bossing them around. To create a bucket simply instantiate `BucketAlerts::TokenBucket`:\n\n```cpp\nBucketAlerts::TokenBucket myBucket(starting, max, replenish_rate);\n```\n\nAnd to register the callback to invoke when exhausted, set the public `OnBucketExhausted` pointer:\n\n```cpp\nmyBucket.OnBucketExhausted = some_func; \n```\n\n### Manual Update\n\nBy default, token buckets update (eg replenish tokens) every time you try to consume from them. However, if you're planning to consume a lot of times per second and only want updates at a constant rate (and not on every time you consume), you can disable the auto update by setting:\n\n```cpp\nBucketAlerts::Defs::AutoUpdate = false;\n```\n\nAnd then update buckets yourself, by calling:\n\n```cpp\nBucketAlerts::get_main().ManualUpdate();\n```\n\n(or call ManualUpdate on your own custom managers, if you don't use the default one).\n\n### Defs\n\nThere are some global defs you can set to change the buckets behavior before you create them (note: don't change these flags while running - it will cause undefined behavior). To access these defs use the `BucketAlerts::Defs` object.\n\nDefs you can change are:\n\n#### BucketAlerts::Defs::ThreadSafe (default: true)\n\nIf true, will use mutex internally to make sure the buckets are thread safe. If you don't use threads, disable this option for slightly better performance.\n\n#### BucketAlerts::Defs::DefaultCategoryId (default: -1)\n\nCategory id to use as the default category (when no category id provided).\n\n#### BucketAlerts::Defs::ResetWhenConsumed (default: false)\n\nIf true, will reset buckets back to their starting value whenever they are exhausted (but after invoking the callback).\n\n#### BucketAlerts::Defs::AutoUpdate (default: true)\n\nIf true, buckets will update automatically whenever you try to consume from them. If false, you'll need to call ManualUpdate() every few intervals (depending on your normal consumption rate) to make sure tokens replenish.\n\n## License\n\nBucketAlerts is distributed under the MIT license and is free to use for any commercial or non commercial purpose.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fronenness%2Fbucketalerts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fronenness%2Fbucketalerts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fronenness%2Fbucketalerts/lists"}