{"id":16446528,"url":"https://github.com/elsid/resource_pool","last_synced_at":"2025-03-16T17:36:49.048Z","repository":{"id":50036214,"uuid":"57433451","full_name":"elsid/resource_pool","owner":"elsid","description":"C++ header only library purposed to create pool of some resources like keepalive connections","archived":false,"fork":false,"pushed_at":"2024-08-09T13:36:38.000Z","size":445,"stargazers_count":23,"open_issues_count":0,"forks_count":4,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-02-27T12:05:45.282Z","etag":null,"topics":["asio","async-programming","cpp","cpp-library","cpp14","header-only"],"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/elsid.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":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-04-30T08:22:04.000Z","updated_at":"2024-11-18T06:16:44.000Z","dependencies_parsed_at":"2024-08-09T15:03:55.872Z","dependency_job_id":"ed5247cf-d4e8-438b-b915-560cbd47a554","html_url":"https://github.com/elsid/resource_pool","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/elsid%2Fresource_pool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elsid%2Fresource_pool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elsid%2Fresource_pool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elsid%2Fresource_pool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elsid","download_url":"https://codeload.github.com/elsid/resource_pool/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243823769,"owners_count":20353728,"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":["asio","async-programming","cpp","cpp-library","cpp14","header-only"],"created_at":"2024-10-11T09:47:55.992Z","updated_at":"2025-03-16T17:36:48.668Z","avatar_url":"https://github.com/elsid.png","language":"C++","readme":"# Resource pool\n\n![Build Status](https://github.com/elsid/resource_pool/actions/workflows/build.yaml/badge.svg)\n\nHeader only library purposed to create pool of some resources like keep-alive connections.\nSupports sync and async interfaces. Based on boost.\n\n## Dependencies\n\n* **CMake** \u003e= 3.12\n* **GCC** or **Clang** C++ compilers with C++17 support.\n* **Boost** \u003e= 1.66\n\n## Build\n\nProject uses CMake. Build need only to run tests, examples and benchmarks:\n```bash\nmkdir build\ncd build\ncmake ..\nmake -j $(nproc)\nctest -V\nexamples/sync_pool\nexamples/async_pool\nbenchmarks/resource_pool_benchmark_async\n```\n\n## Install\n\nInclude as subdirectory into your CMake project or copy folder include.\n\n## Usage\n\n### Handle\n\nThe handle contains iterator to ```boost::optional``` of resource value in pool.\nDeclared as type [handle](include/yamail/resource_pool/handle.hpp#L11-L56).\nConstructs with one of strategies that uses in destructor:\n* waste -- resets iterator if handle is usable.\n* recycle -- returns iterator to pool if handle is usable.\n\nPool contains slots for resources that means handle iterator may refers to empty ```boost::optional```.\nClient always must check value before using by method:\n```c++\nbool empty() const;\n```\n\nAccess to value provides by methods:\n```c++\nvalue_type\u0026 get();\nconst value_type\u0026 get() const;\nvalue_type *operator -\u003e();\nconst value_type *operator -\u003e() const;\nvalue_type \u0026operator *();\nconst value_type \u0026operator *() const;\n```\n\n```value_type``` -- resource type.\n\nValue of handle changes by method:\n```c++\nvoid reset(value_type\u0026\u0026 res);\n```\n\nTo drop resource use method:\n```c++\nvoid waste();\n```\n\nTo return resource into pool use method:\n```c++\nvoid recycle();\n```\n\nBoth methods makes handle unusable that could be checked by method:\n```c++\nbool unusable() const;\n```\n\nCalling one of these methods for unusable handle throws an exception ```error::unusable_handle```.\n\n### Synchronous pool\n\nBased on ```std::condition_variable```.\n\n#### Create pool\n\nUse type [sync::pool](include/yamail/resource_pool/sync/pool.hpp#L14-L65). Parametrize resource type:\n```c++\ntemplate \u003cclass Value\n          class Impl = detail::pool_impl\u003cValue, std::condition_variable\u003e \u003e\nclass pool;\n```\n\nPool holds ```boost::optional``` of resource type.\n\nExample:\n```c++\nusing fstream_pool = pool\u003cstd::fstream\u003e;\n```\n\nObject construction requires pool capacity:\n```c++\npool(\n    std::size_t capacity,\n    time_traits::duration idle_timeout = time_traits::duration::max(),\n    time_traits::duration lifespan = time_traits::duration::max()\n);\n```\n\n* `idle_timeout` defines maximum time interval to keep unused resource in the pool.\n  Check for elapsed time happens on resource allocation.\n* `lifespan` defines maximum time interval to keep resource.\n  Check for elapsed time happens on resource allocation and recycle.\n\nExample:\n```c++\nfstream_pool pool(42);\n```\n\n#### Get handle\n\nUse one of these methods:\n```c++\nstd::pair\u003cboost::system::error_code, handle\u003e get_auto_waste(\n    time_traits::duration wait_duration = time_traits::duration(0)\n);\n```\nreturns resource handle when it will be available with auto waste strategy.\n\n```c++\nstd::pair\u003cboost::system::error_code, handle\u003e get_auto_recycle(\n    time_traits::duration wait_duration = time_traits::duration(0)\n);\n```\nreturns resource handle when it will be available with auto recycle strategy.\n\nRecommends to use ```get_auto_waste``` and explicit call ```recycle```.\n\nExample:\n```c++\nauto r = pool.get(time_traits::duration(1));\nconst auto\u0026 ec = r.first;\nif (ec) {\n    std::cerr \u003c\u003c \"Can't get resource: \" \u003c\u003c ec.message() \u003c\u003c std::endl;\n    return;\n}\nauto\u0026 h = r.second;\nif (h.empty()) {\n    h.reset(create_resource());\n}\nuse_resource(h.get());\n```\n\n#### Invalidate pool\n\nFollowing method allows to force all available and used handles to be wasted:\n```c++\nvoid invalidate();\n```\n\nAll currently available but not used handles will be wasted. All currently used handles will be wasted on return to the pool.\n\n### Asynchronous pool\n\nBased on ```boost::asio::io_context```. Uses async queue with deadline timer to store waiting resources requests.\n\n#### Create pool\n\nUse type [async::pool](include/yamail/resource_pool/async/pool.hpp#L34-L105). Parametrize resource type:\n```c++\ntemplate \u003cclass Value,\n          class IoContext = boost::asio::io_context,\n          class Impl = default_pool_impl\u003cValue, IoContext\u003e::type\u003e\nclass pool;\n```\n\nPool holds ```boost::optional``` of resource type.\n\nExample:\n```c++\nusing fstream_pool = pool\u003cstd::fstream\u003e;\n```\n\nObject construction requires reference to io service, capacity of pool, queue capacity:\n```c++\npool(\n    io_context_t\u0026 io_context,\n    std::size_t capacity,\n    std::size_t queue_capacity,\n    time_traits::duration idle_timeout = time_traits::duration::max(),\n    time_traits::duration lifespan = time_traits::duration::max()\n);\n```\n\n* `idle_timeout` defines maximum time interval to keep unused resource in the pool.\n  Check for elapsed time happens on resource allocation.\n* `lifespan` defines maximum time interval to keep resource.\n  Check for elapsed time happens on resource allocation and recycle.\n\nExample:\n```c++\nboost::asio::io_context io;\nfstream_pool pool(io, 13, 42);\n```\n\n#### Get handle\n\nUse one of these methods:\n```c++\ntemplate \u003cclass CompletionToken\u003e\nvoid get_auto_waste(\n    boost::asio::io_context\u0026 io,\n    CompletionToken\u0026\u0026 token,\n    const time_traits::duration\u0026 wait_duration = time_traits::duration(0)\n);\n```\nreturns resource handle when it will be available with auto waste strategy.\n\n```c++\ntemplate \u003cclass CompletionToken\u003e\nvoid get_auto_recycle(\n    boost::asio::io_context\u0026 io,\n    CompletionToken\u0026\u0026 token,\n    const time_traits::duration\u0026 wait_duration = time_traits::duration(0)\n);\n```\nreturns resource handle when it will be available with auto recycle strategy.\n\nType ```CompetionToken``` must provide interface:\n```c++\nvoid operator ()(\n    const boost::system::error_code\u0026,\n    handle\n);\n```\nor it can be any valid completion token from **Boost.Asio** like ```boost::asio::yield_context```, ```boost::asio::use_future``` and so on.\n\nRecommends to use ```get_auto_waste``` and explicit call ```recycle```.\n\nIf error occurs ```ec``` will be not ok and ```handle``` will be unusable.\n\nExample with classic callbacks:\n```c++\nstruct on_create_resource {\n    handle h;\n\n    on_create_resource(handle h) : h(std::move(h)) {}\n\n    void operator ()(const boost::system::error_code\u0026 ec, handle::value_type\u0026\u0026 r) {\n        if (ec) {\n            std::cerr \u003c\u003c \"Can't create resource: \" \u003c\u003c ec.message() \u003c\u003c std::endl;\n            return;\n        }\n        h.reset(std::move(r));\n        use_resource(h.get());\n    }\n};\n\nstruct handle_get {\n    void operator ()(const boost::system::error_code\u0026 ec, handle h) {\n        if (ec) {\n            std::cerr \u003c\u003c \"Can't get resource: \" \u003c\u003c ec.message() \u003c\u003c std::endl;\n            return;\n        }\n        if (h.empty()) {\n            async_create_resource(on_create_resource(std::move(h)));\n        } else {\n            use_resource(h.get());\n        }\n    }\n};\n\npool.get(handle_get(), time_traits::duration(1));\n```\n\nExample with Boost.Coroutines:\n```c++\nboost::asio::spawn(io, [\u0026](boost::asio::yield_context yield) {\n    auto h = pool.get(yield, time_traits::duration(1));\n    if (h.empty()) {\n        h.reset(create_resource(yield));\n    }\n    use_resource(h.get());\n}\n```\n\n#### Invalidate pool\n\nFollowing method allows to force all available and used handles to be wasted:\n```c++\nvoid invalidate();\n```\n\nAll currently available but not used handles will be wasted. All currently used handles will be wasted on return to the pool.\n\n## Examples\n\nSource code can be found in [examples](examples) directory.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felsid%2Fresource_pool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felsid%2Fresource_pool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felsid%2Fresource_pool/lists"}