Cpp

C++ SDK

The C++ SDK is a header-only library for writing TaskDaemon handlers.

Installation

Download the header file directly:

curl -O https://raw.githubusercontent.com/jona62/TaskDaemon-Handlers/main/cpp/include/taskdaemon.hpp

Or add as a git submodule:

git submodule add https://github.com/jona62/TaskDaemon-Handlers.git libs/taskdaemon-handlers

Then include:

#include "taskdaemon.hpp"
// or
#include "libs/taskdaemon-handlers/cpp/include/taskdaemon.hpp"

Dependencies

The SDK requires nlohmann/json. Install via your package manager:

# Debian/Ubuntu
apt-get install nlohmann-json3-dev

# macOS
brew install nlohmann-json

# vcpkg
vcpkg install nlohmann-json

Basic Usage

#include "taskdaemon.hpp"

int main() {
    taskdaemon::run([](const taskdaemon::Task& task) {
        std::string name = task.task_data.value("name", "World");
        
        return taskdaemon::success({
            {"message", "Hello, " + name + "!"}
        });
    });
}

Task Struct

struct Task {
    std::string task_id;
    std::string task_type;
    json task_data;        // nlohmann::json
    int attempt;           // Current attempt (starts at 0)
};

Result Functions

using json = nlohmann::json;

// Success with result
return taskdaemon::success({{"result", "value"}});

// Non-retryable error (default)
return taskdaemon::error("invalid input");

// Retryable error
return taskdaemon::error("service unavailable", true);

The result types:

struct Success {
    json result;
};

struct Error {
    std::string error;
    bool retryable = false;
};

using Result = std::variant<Success, Error>;

Complete Example

Here’s the actual word count handler from the sample project:

#include "taskdaemon.hpp"
#include <algorithm>
#include <sstream>

int main() {
    taskdaemon::run([](const taskdaemon::Task& task) {
        std::string text = task.task_data.value("text", "");
        
        // Count words
        int words = 0;
        std::istringstream iss(text);
        std::string word;
        while (iss >> word) words++;
        
        // Count characters (excluding spaces)
        int chars = std::count_if(text.begin(), text.end(), 
            [](char c) { return !std::isspace(c); });
        
        // Count lines
        int lines = std::count(text.begin(), text.end(), '\n') + 1;
        
        return taskdaemon::success({
            {"words", words},
            {"characters", chars},
            {"lines", lines}
        });
    });
}

Error Handling

Exceptions are automatically caught and converted to non-retryable errors:

taskdaemon::run([](const taskdaemon::Task& task) {
    // If this throws, it becomes an error response
    std::string required = task.task_data.at("required");
    return taskdaemon::success({{"value", required}});
});

For explicit error handling:

taskdaemon::run([](const taskdaemon::Task& task) {
    if (!task.task_data.contains("required")) {
        return taskdaemon::error("missing required field");
    }
    
    try {
        auto result = external_call();
        return taskdaemon::success(result);
    } catch (const NetworkError& e) {
        return taskdaemon::error(e.what(), true);  // Retryable
    } catch (const std::exception& e) {
        return taskdaemon::error(e.what());
    }
});

Compilation

# Basic compilation
g++ -std=c++17 -O2 -o handler handler.cpp

# With static linking (for minimal Docker images)
g++ -std=c++17 -O2 -static-libstdc++ -o handler handler.cpp

Dockerfile

FROM gcc:13 AS builder
WORKDIR /app

# Install nlohmann-json
RUN apt-get update && apt-get install -y nlohmann-json3-dev

# Copy SDK and handler
COPY taskdaemon.hpp handler.cpp ./

# Compile with static linking
RUN g++ -std=c++17 -O2 -static-libstdc++ -o handler handler.cpp

FROM debian:bookworm-slim
COPY --from=builder /app/handler /handler
CMD ["/handler"]

For an even smaller image:

FROM gcc:13-bookworm AS builder
WORKDIR /app
RUN apt-get update && apt-get install -y nlohmann-json3-dev
COPY taskdaemon.hpp handler.cpp ./
RUN g++ -std=c++17 -O2 -static -o handler handler.cpp

FROM scratch
COPY --from=builder /app/handler /handler
CMD ["/handler"]

Handler Configuration

[handlers.wordcount]
image = "cpp-handler:latest"
instances = 4
timeout = 10

Performance Notes

C++ handlers are ideal for:

• CPU-intensive computations
• Low-latency requirements
• Memory-efficient processing

The header-only design means no runtime dependencies beyond the standard library and nlohmann/json.