{"id":50988354,"url":"https://github.com/cantrepro/cppq","last_synced_at":"2026-07-07T22:00:51.459Z","repository":{"id":58096627,"uuid":"529855448","full_name":"cantrepro/cppq","owner":"cantrepro","description":"Simple, reliable \u0026 efficient distributed task queues for C++17","archived":false,"fork":false,"pushed_at":"2026-06-13T09:17:41.000Z","size":596,"stargazers_count":116,"open_issues_count":0,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2026-07-05T11:21:12.159Z","etag":null,"topics":["asynchronous-tasks","background-jobs","cpp","cpp17","distributed-computing","redis","redis-queue","task-queue","tasks","worker-pool"],"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/cantrepro.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":"2022-08-28T12:26:51.000Z","updated_at":"2026-06-17T14:35:39.000Z","dependencies_parsed_at":"2025-08-13T06:41:55.163Z","dependency_job_id":"d8a55bf2-46a2-45ed-80bf-5529fbef4cf7","html_url":"https://github.com/cantrepro/cppq","commit_stats":null,"previous_names":["h2337/cppq","hikmat2337/cppq","cantrepro/cppq"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cantrepro/cppq","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cantrepro%2Fcppq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cantrepro%2Fcppq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cantrepro%2Fcppq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cantrepro%2Fcppq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cantrepro","download_url":"https://codeload.github.com/cantrepro/cppq/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cantrepro%2Fcppq/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35243953,"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-07-07T02:00:07.222Z","response_time":90,"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":["asynchronous-tasks","background-jobs","cpp","cpp17","distributed-computing","redis","redis-queue","task-queue","tasks","worker-pool"],"created_at":"2026-06-19T23:00:32.327Z","updated_at":"2026-07-07T22:00:51.448Z","avatar_url":"https://github.com/cantrepro.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"\u003cimg align=\"right\" src=\"https://raw.githubusercontent.com/h2337/cppq/refs/heads/master/logo.svg\"\u003e\n\n# cppq\n\nDistributed, Redis-backed task queue for modern C++17 applications with worker orchestration, scheduling, and tooling built-in.\n\n## Table of Contents\n- [Overview](#overview)\n- [Features](#features)\n- [Requirements](#requirements)\n- [Quickstart](#quickstart)\n- [Example](#example)\n- [Running the Example](#running-the-example)\n- [Testing](#testing)\n- [CLI](#cli)\n- [Web UI](#web-ui)\n- [Project Layout](#project-layout)\n- [License](#license)\n\n## Overview\ncppq is a header-only task queue that lets you enqueue work from C++ and execute it asynchronously via Redis. Workers pull jobs, run user supplied handlers, and update task state in Redis. The library focuses on predictable behaviour and ease of adoption—drop the header in your project, link a couple of dependencies, and you have a resilient queue.\n\n### Architecture at a Glance\n- Producers enqueue `Task` objects into Redis lists and hashes.\n- `runServer` polls queues by priority, hands tasks to a thread pool, and dispatches registered handlers.\n- Recovery logic returns stuck tasks to the pending list after configurable timeouts.\n- Auxiliary tooling (CLI, web dashboard) surfaces queue state and provides pause / resume controls.\n\n## Features\n- At-least-once delivery with retry tracking and task recovery.\n- Scheduled execution (time-based today, cron support planned).\n- Queue-level priorities and pause / unpause switches.\n- Header-only API; only Redis, libuuid, and hiredis are required.\n- Companion CLI and web dashboard for operations teams.\n- Extensive Catch2 test suite covering queue flows and thread pool behaviour.\n\n## Requirements\n### Runtime\n- Redis 6.0+ available on `redis://127.0.0.1:6379` (configurable).\n\n### C++ Dependencies\n- C++17-capable compiler (`g++`, `clang++`).\n- [`hiredis`](https://github.com/redis/hiredis) client library.\n- `libuuid` for UUID generation.\n\nInstall dependencies with your package manager, e.g.\n```bash\n# Debian / Ubuntu\nsudo apt install g++ libhiredis-dev uuid-dev\n\n# Arch Linux\nsudo pacman -S hiredis util-linux-libs\n\n# macOS (Homebrew)\nbrew install hiredis ossp-uuid\n```\n\n## Quickstart\n1. Copy `cppq.hpp` into your include path.\n2. Include the header and link against hiredis, uuid, and pthread on POSIX systems:\n   ```bash\n   g++ -std=c++17 your_app.cpp -I/path/to/cppq -lhiredis -luuid -lpthread\n   ```\n3. Register task handlers before calling `runServer`.\n4. Start Redis and execute your application.\n\n## Example\n```cpp\n#include \"cppq.hpp\"\n\n#include \u003cnlohmann/json.hpp\u003e\n\n// Specify task type name\nconst std::string TypeEmailDelivery = \"email:deliver\";\n\n// Define a payload type for your task\ntypedef struct {\n  int UserID;\n  std::string TemplateID;\n} EmailDeliveryPayload;\n\n// Provide conversion to JSON (optional, you can use any kind of payload)\nvoid to_json(nlohmann::json\u0026 j, const EmailDeliveryPayload\u0026 p) {\n  j = nlohmann::json{{\"UserID\", p.UserID}, {\"TemplateID\", p.TemplateID}};\n}\n\n// Helper function to create a new task with the given payload\ncppq::Task NewEmailDeliveryTask(EmailDeliveryPayload payload) {\n  nlohmann::json j = payload;\n  // \"10\" is maxRetry -- the number of times the task will be retried on exception\n  return cppq::Task{TypeEmailDelivery, j.dump(), 10};\n}\n\n// The actual task code\nvoid HandleEmailDeliveryTask(cppq::Task\u0026 task) {\n  // Fetch the parameters\n  nlohmann::json parsedPayload = nlohmann::json::parse(task.payload);\n  int userID = parsedPayload[\"UserID\"];\n  std::string templateID = parsedPayload[\"TemplateID\"];\n\n  // Send the email...\n\n  // Return a result\n  nlohmann::json r;\n  r[\"Sent\"] = true;\n  task.result = r.dump();\n}\n\nint main(int argc, char* argv[]) {\n  // Register task types and handlers\n  cppq::registerHandler(TypeEmailDelivery, \u0026HandleEmailDeliveryTask);\n\n  // Create a Redis connection for enqueuing, you can reuse this for subsequent enqueues\n  redisOptions redisOpts = {0};\n  REDIS_OPTIONS_SET_TCP(\u0026redisOpts, \"127.0.0.1\", 6379);\n  redisContext* c = redisConnectWithOptions(\u0026redisOpts);\n  if (c == nullptr || c-\u003eerr) {\n    std::cerr \u003c\u003c \"Failed to connect to Redis\" \u003c\u003c std::endl;\n    return 1;\n  }\n\n  // Create tasks\n  cppq::Task task = NewEmailDeliveryTask(EmailDeliveryPayload{.UserID = 666, .TemplateID = \"AH\"});\n  cppq::Task task2 = NewEmailDeliveryTask(EmailDeliveryPayload{.UserID = 606, .TemplateID = \"BH\"});\n  cppq::Task task3 = NewEmailDeliveryTask(EmailDeliveryPayload{.UserID = 666, .TemplateID = \"CH\"});\n\n  // Enqueue a task on default queue\n  cppq::enqueue(c, task, \"default\");\n  // Enqueue a task on high priority queue\n  cppq::enqueue(c, task2, \"high\");\n  // Enqueue a task on default queue to be run at exactly 1 minute from now\n  cppq::enqueue(\n      c,\n      task3,\n      \"default\",\n      cppq::scheduleOptions(std::chrono::system_clock::now() + std::chrono::minutes(1)));\n\n  // Pause queue to stop processing tasks from it\n  cppq::pause(c, \"default\");\n  // Unpause queue to continue processing tasks from it\n  cppq::unpause(c, \"default\");\n\n  // This call will loop forever checking the pending queue\n  // before being pushed back to pending queue (i.e. when worker dies in middle of execution).\n  cppq::runServer(redisOpts, {{\"low\", 5}, {\"default\", 10}, {\"high\", 20}}, 1000);\n}\n```\n\n## Running the Example\n```bash\ng++ -std=c++17 example.cpp -I. -lhiredis -luuid -lpthread -o example\n./example\n```\nEnsure Redis is running locally before executing the binary.\n\n## Testing\nThe repository ships with Catch2 tests that exercise queue operations, scheduling, recovery, pause logic, and the internal thread pool.\n\n1. Install dependencies (besides hiredis/uuid you also need Catch2 headers and nlohmann-json).\n2. Start a local Redis instance: `redis-server --port 6379`.\n3. Build the tests:\n   ```bash\n   ./build_tests.sh\n   ```\n4. Run them:\n   ```bash\n   ./tests\n   ```\n\nThe script emits useful tags such as `[queue]`, `[recovery]`, or `[threadpool]` that you can pass to Catch2 to focus on specific areas.\n\n## CLI\nThe `cli/` directory contains a Python-based management tool built with Click, Rich, and Redis-py.\n\n```bash\ncd cli\npip install -r requirements.txt\npython3 main.py --help\npython3 main.py queues --format json\n```\n\nKey capabilities:\n- Inspect queues, task states, and statistics.\n- Pause or resume queues.\n- Dump task metadata for debugging.\n- Load configuration from environment variables, CLI flags, or `~/.config/cppq/config.json`.\n\nFor deeper usage details see [`cli/README.md`](cli/README.md).\n\n## Web UI\nA Next.js dashboard lives in `web/`. It offers real-time monitoring, task inspection, and queue controls via a modern interface.\n\n```bash\ncd web\nnpm install\nnpm run dev\n```\nVisit http://localhost:3000/ and connect to your Redis instance (default `redis://localhost:6379`). Read the dedicated [web/README.md](web/README.md) for screenshots, API routes, and deployment hints.\n\n## Project Layout\n```\n.\n├── cppq.hpp          # Header-only queue library\n├── example.cpp       # Minimal producer/worker demonstration\n├── tests.cpp         # Catch2 regression suite\n├── build_tests.sh    # Helper script for building tests\n├── cli/              # Python CLI for operations\n└── web/              # Next.js dashboard\n```\n\n## License\ncppq is released under the MIT License. The bundled thread pool implementation is adapted from https://github.com/bshoshany/thread-pool.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcantrepro%2Fcppq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcantrepro%2Fcppq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcantrepro%2Fcppq/lists"}