{"id":18406502,"url":"https://github.com/georgiifirsov/ntp","last_synced_at":"2025-04-07T08:32:25.304Z","repository":{"id":64081956,"uuid":"569587368","full_name":"GeorgiiFirsov/ntp","owner":"GeorgiiFirsov","description":"\"ntp\" stands for \"Native Thread Pool\". This library implements a thread pool using Win32 API (and some Native API too).","archived":false,"fork":false,"pushed_at":"2023-07-07T17:54:48.000Z","size":1967,"stargazers_count":2,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-22T15:23:02.367Z","etag":null,"topics":["cplusplus","cplusplus-17","cpp","cpp17","multithreading","thread-pool","winapi"],"latest_commit_sha":null,"homepage":"https://georgyfirsov.github.io/ntp","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GeorgiiFirsov.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":"2022-11-23T06:59:06.000Z","updated_at":"2023-06-25T20:10:49.000Z","dependencies_parsed_at":"2024-08-09T04:22:41.512Z","dependency_job_id":"eb782d0d-921b-42cf-aa27-96007570d547","html_url":"https://github.com/GeorgiiFirsov/ntp","commit_stats":null,"previous_names":["georgiifirsov/ntp"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GeorgiiFirsov%2Fntp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GeorgiiFirsov%2Fntp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GeorgiiFirsov%2Fntp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GeorgiiFirsov%2Fntp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GeorgiiFirsov","download_url":"https://codeload.github.com/GeorgiiFirsov/ntp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247620428,"owners_count":20968209,"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":["cplusplus","cplusplus-17","cpp","cpp17","multithreading","thread-pool","winapi"],"created_at":"2024-11-06T03:09:20.577Z","updated_at":"2025-04-07T08:32:24.783Z","avatar_url":"https://github.com/GeorgiiFirsov.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ntp\n\nWindows API has a very beautiful [Thread Pool API][1] that allows to execute \nwork tasks, wait for waitable handles or completion ports and schedule timer \ncallbacks very efficiently.\n\nThis API is designed for C programming language, but C++ provides more useful \nfeatures, that make working with such APIs easier. This library is a wrapper \nfor Thread Pool API, that provides a C++ abstraction and makes easier to \nmanage all threadpool resources.\n\nFor further information about internal API refer to [Microsoft documentation][2].\n\n## Installation\n\nTODO :)\n\n## Usage\n\nUsage of `ntp` is as simple as possible.\nJust add the following lines in your CMakeLists.txt:\n```cmake\ntarget_link_libraries(your-project PRIVATE ntp)\ntarget_include_directories(your-project PRIVATE \"/path/to/ntp/include\")\n```\nAfter that you can just include header and use library features:\n```cpp\n #include \"ntp.hpp\"\n```\n\n## Examples\n\n### Basic workers\n\n```cpp\n#include \"ntp.hpp\"\n\nvoid DoWork()\n{\n    ntp::SystemThreadPool pool;\n\t \n    pool.SubmitWork([]() {\n        // Do some long operation.\n    });\n\t \n    // Do some other work.\n\t \n    pool.WaitWorks();\n}\n```\n\n### External cancellation\n\n```cpp\n#include \"ntp.hpp\"\n\nvoid DoWork(const std::vector\u003cCallable\u003e\u0026 tasks)\n{\n    //\n    // For RpcTestCancel refer to: https://learn.microsoft.com/en-us/windows/win32/api/rpcdce/nf-rpcdce-rpctestcancel\n    //\n\n    ntp::SystemThreadPool pool(RpcTestCancel);\n\n    for (const auto\u0026 task : tasks)\n    {\n        pool.SumbitWork(task);\n    }\n\n    // Do some other work.\n\t\n    const bool completed = pool.WaitWorks();\n    if (!completed)\n    {\n        //\n        // If WaitWorks returns false, then external cancellation test was \n        // triggered while tasks were awaited.\n        //\n\n        HandleIncompleteWork();\n    }\n}\n```\n\n### Cleanup on callback exit\n\nCallbacks may optionally accept `PTP_CALLBACK_INSTANCE` as their first argument.\nIt allows user to call the following functions:\n- [`FreeLibraryWhenCallbackReturns`][3]\n- [`LeaveCriticalSectionWhenCallbackReturns`][4]\n- [`ReleaseMutexWhenCallbackReturns`][5]\n- [`ReleaseSemaphoreWhenCallbackReturns`][6]\n- [`SetEventWhenCallbackReturns`][7]\n\n```cpp\n#include \"ntp.hpp\"\n\nvoid DoWork(HANDLE event)\n{\n    ntp::SystemThreadPool pool;\n\n    pool.SubmitWork([event](PTP_CALLBACK_INSTANCE instance) {\n        SetEventWhenCallbackReturns(instance, event);\n\n        // Do some work. After callback ends event will be set.\n    });\n\n    // Do further work...\n}\n```\n\n### Basic wait callbacks\n\n```cpp\n#include \"ntp.hpp\"\n\nclass ProcessManager final\n{\npublic:\n    void LaunchProcess(const wchar_t* command_line)\n    {\n        STARTUPINFO si{ sizeof(STARTUPINFO) };\n        PROCESS_INFORMATION pi{};\n\n        //\n        // Don't handle errors for simplicity\n        //\n\n        CreateProcess(nullptr, command_line, nullptr, nullptr, \n            FALSE, 0, nullptr, nullptr, \u0026si, \u0026pi);\n\t\t\t \n        //\n        // Set wait callback\n        //\n\n        pool_.SubmitWait(pi.hProcess, OnProcessCompleted, \n            pi.hProcess /* Pass handle to callback too */); // (1)\n    }\n\nprivate:\n    static void OnProcessCompleted(TP_WAIT_RESULT wait_result, HANDLE process)\n    {\n        if (wait_result == WAIT_OBJECT_0)\n        {\n            // Process has been ended\n        }\n\n        //\n        // Close process handle, passed as parameter at (1)\n        //\n\n        CloseHandle(process);\n    }\n\nprivate:\n    ntp::SystemThreadPool pool_;\n}\n```\n\n### External logger support\n\n`ntp` library supports custom logger callback, that accepts severity and a message string.\nSeverity has values from `ntp::logger::Severity` enumeration.\n\n```cpp\n#include \"ntp.hpp\"\n\nvoid TraceCallback(ntp::logger::Severity severity, const wchar_t* message)\n{\n    if (severity \u003e= ntp::logger::Severity::kNormal)\n    {\n        //\n        // Skip ntp::logger::Severity::kExtended\n        //\n\n        std::wcerr \u003c\u003c message \u003c\u003c L'\\n';\n    }\n}\n\nint main()\n{\n    ntp::logger::SetLogger(TraceCallback);\n\n    // Do work with thread pools\n}\n```\n\n### Variety of thread pools\n\n```cpp\n#include \"ntp.hpp\"\n\nvoid DoWork()\n{\n    //\n    // You can create your own pool with, for\n    // instance, 4 to 16 threads\n    //\n    \n    ntp::ThreadPool pool(4, 16);\n    \n    pool.SubmitWork([]() {\n        // Do more work\n    });\n    \n    // ...\n}\n```\n\n\n## TODO\n\n- [X] Work callbacks (`PTP_WORK`)\n- [X] Wait callbacks (`PTP_WAIT`)\n- [X] Timer callbacks (`PTP_TIMER`)\n- [ ] IO callbacks (`PTP_IO`)\n- [X] Tests\n- [X] Cute documentation\n- [X] Support for `PTP_CALLBACK_INSTANCE` as optional first argument in callbacks\n- [X] Refactor tests\n- [ ] Extend code coverage\n- [ ] (Optional) Alpc callbacks (`PTP_ALPC`)\n\n[1]: https://learn.microsoft.com/en-us/windows/win32/procthread/thread-pool-api\n[2]: https://learn.microsoft.com/en-us/windows/win32/procthread/thread-pools\n[3]: https://learn.microsoft.com/ru-ru/windows/win32/api/threadpoolapiset/nf-threadpoolapiset-freelibrarywhencallbackreturns\n[4]: https://learn.microsoft.com/ru-ru/windows/win32/api/threadpoolapiset/nf-threadpoolapiset-leavecriticalsectionwhencallbackreturns\n[5]: https://learn.microsoft.com/ru-ru/windows/win32/api/threadpoolapiset/nf-threadpoolapiset-releasemutexwhencallbackreturns\n[6]: https://learn.microsoft.com/ru-ru/windows/win32/api/threadpoolapiset/nf-threadpoolapiset-releasesemaphorewhencallbackreturns\n[7]: https://learn.microsoft.com/ru-ru/windows/win32/api/threadpoolapiset/nf-threadpoolapiset-seteventwhencallbackreturns\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeorgiifirsov%2Fntp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeorgiifirsov%2Fntp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeorgiifirsov%2Fntp/lists"}