Skip to content

Performance

kolinsky renders typical documents in milliseconds. On the benchmark machine (an otherwise idle 12-core x86_64 machine, measured on 2026-11-12) the command line took a median of 9.0 ms for a ten-line invoice and 123 ms for an invoice of 1,000 lines, process start included, with a peak memory of 10 MB and 41 MB. The benchmarks page has all documents and the method. Inside a long-running program the start-up cost is paid once; the points below keep it that way.

Build the engine once

An Engine holds the fonts, the built-in stylesheet, the fetcher and the caches: the font index, the parsed font files and the shaping data. Building it reads the font folders; every render after that reuses what is already there. Build one engine when your program starts and use it for every document.

The caches change only the speed, never the result: the same input and options give the same document on a fresh engine and on one that has rendered thousands of documents before.

Threads

An engine can be used from any number of threads at once. In Rust it is Send + Sync, and its clones share the same fonts and caches. Rendering is synchronous and CPU-bound, and the engine starts its own worker threads where it parallelizes; no async runtime is needed.

use kolinsky::{Engine, Input, PdfOptions, RenderOptions};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // One engine for the whole program: fonts are indexed and parsed once, then shared by every render
    let engine = Engine::new();
    let options = RenderOptions::default();

    // Renders from several threads at once; the engine is Send + Sync and its clones share the caches
    let pdfs = std::thread::scope(|s| {
        let jobs: Vec<_> = ["hello.html", "scripts.html"]
            .into_iter()
            .map(|path| {
                let (engine, options) = (engine.clone(), &options);
                s.spawn(move || engine.render(Input::Path(path.into()), options, &PdfOptions::default()))
            })
            .collect();
        jobs.into_iter().map(|j| j.join().expect("render thread")).collect::<Result<Vec<_>, _>>()
    })?;
    std::fs::write("hello.pdf", &pdfs[0].output)?;
    std::fs::write("scripts.pdf", &pdfs[1].output)?;

    // Lay out once, write several PDFs from the same document
    let document = engine.layout(Input::Path("hello.html".into()), &options)?.output;
    let mut first = PdfOptions::default();
    first.pages = Some("1".parse()?);
    std::fs::write("first-page.pdf", document.to_pdf(&first)?.output)?;
    let mut archive = PdfOptions::default();
    archive.outline = true;
    archive.deterministic = true;
    std::fs::write("full.pdf", document.to_pdf(&archive)?.output)?;
    Ok(())
}

In Python, layout, render and the PDF writing release the GIL while the engine works, so several threads rendering with one Engine run in parallel. render_async runs a render in a worker thread for asyncio programs; cancelling the awaiting task does not stop a render that is already running.

import asyncio
from concurrent.futures import ThreadPoolExecutor
from pathlib import Path

import kolinsky

engine = kolinsky.Engine()  # build once, reuse for every document

# The engine releases the GIL while it works, so threads render in parallel
with ThreadPoolExecutor(max_workers=4) as pool:
    results = list(pool.map(engine.render, [Path("hello.html"), Path("scripts.html")]))
Path("hello.pdf").write_bytes(results[0].pdf)


async def main() -> None:
    result = await engine.render_async(Path("scripts.html"))
    Path("scripts.pdf").write_bytes(result.pdf)


asyncio.run(main())

# Lay out once, write twice
document = engine.layout(Path("hello.html"))
document.write_pdf("first-page.pdf", pages="1")
document.write_pdf("full.pdf", outline=True, deterministic=True)

Lay out once, write several PDFs

Layout and writing are separate steps. Engine::layout returns a Document, which can be written any number of times with different PDF options (a page selection, an archive version with attachments, a tagged version) without laying it out again. The examples above write two PDFs from one layout.

Check a layout without writing a PDF

To test where things land (a signature block on the last page, a table that must not split), lay out the document and query its boxes instead of writing and reading a PDF. kolinsky inspect does the same on the command line; see Command line.

A worker process for other languages

kolinsky serve --stdio builds one engine and answers JSON requests, one per line on standard input, with one JSON response per line on standard output, in request order. Programs in other languages keep one worker process running and avoid the start-up cost of a process per document.

A request has an id, a method (render or inspect) and params: one of html, path or url, and optionally base_url, stylesheets, options (the render options by name) and pdf (the PDF options by name):

{"id": 1, "method": "render", "params": {"html": "<p>Hello</p>", "options": {"page_size": "A5"}, "pdf": {"title": "Hello"}}}

The answer holds the PDF in base64 and the diagnostics:

{"id":1,"ok":true,"result":{"pdf":"JVBERi0xLjcK...","diagnostics":[]}}

A failed request is answered with "ok": false and an error object with a kind (fetch, parse, strict, pdf or request), a message and the diagnostics; it does not end the worker. The worker exits at the end of standard input. Only the font options (--font-dir, --no-system-fonts) are given when it starts.

Fonts and memory

Every installed font is a candidate for fallback. For a service, turning off the system fonts and adding the fonts you use with a font folder keeps the set of fonts small and the output the same on every machine (see Fonts).