nqsetprog(3)

NAME

nqsetprog — report the progress of long calls

LIBRARY

libnoqtis, -lnoqtis

SYNOPSIS

#include <noqtis.h>

typedef void (*nqprogfn)(int stage, uint64_t done, uint64_t total, void *user);

int
nqsetprog(nqprogfn fn, void *user);

DESCRIPTION

nqsetprog() sets a function the library calls as its long calls go, so that a caller can show how far they are: fn is called from the thread doing the work with user, the stage, and done going from 0 to total; once when the stage begins (done 0), as it goes, and once more when it ends (done equal to total). The stages:

NQPHASH: The bytes of the folder's files that nqseal(3), nqseal2() and nqchkx(3) (and so nqchk(), nqchkt()) hash; total is the size of the files in the folder's listing (0 for a partial check, which hashes only the files named).
NQPSIGN: An SLH-DSA signature's trees, the slow part of signing: the FORS tree, then each of the d hypertree layers, so total is d + 1 (8 or 9 for the ‘s’ sets, 18 or 23 for the ‘f’ sets).

Only counts the caller could know are reported, nothing that depends on a secret. The function must not call back into the library. The setting is global and not synchronised, as nqsetrng(3): set it once, before any thread uses the library. A NULL fn stops the calls.

noqtis(1) uses it to draw a progress bar on standard error when that is a terminal.

RETURN VALUES

nqsetprog() returns NQOK.

EXAMPLES

static void show(int stage, uint64_t done, uint64_t total, void *u) {
  (void)u;
  fprintf(stderr, "\r%s %3u%%", stage == NQPHASH ? "hashing" : "signing",
          total ? (unsigned)(done * 100 / total) : 0);
  if (done == total) fputc('\n', stderr);
}
...
nqsetprog(show, NULL);