awk-polycall is the AWK binding for Polycall, distributed through PyPI as source files. It is not a Python library: pip install awk-polycall places the binding's files (commit f10853722fe1) inside the package. python -m awk_polycall path prints where they are and python -m awk_polycall extract DIR copies them out; build and use them as described below.

awk-polycall

AWK binding for Polycall (binding ABI v1, Polycall >= 1.1.0), published as awk-polycall. It has two layers, because only gawk can load C:

gawk extension

make ext                          # build/awk_polycall.so (.dll on Windows)
AWKLIBPATH=build gawk -b -f examples/gawk_ext.awk

@load "awk_polycall"
BEGIN {
    if (polycall::run_config("awk-polycallrc") != polycall::OK) {      # = polycall_ffi_run_config(path, 1)
        print polycall::strerror(polycall::STATUS) ": " polycall::last_error() > "/dev/stderr"
        exit 1
    }
    inbox  = polycall::peer_open("inbox", "127.0.0.1:0")             # handle > 0, or a negative status
    outbox = polycall::peer_open("outbox")                           # no bind = send-only
    polycall::peer_send(outbox, polycall::peer_endpoint(inbox), "hello", "m-1")
    if (polycall::peer_recv(inbox, 5000, msg) == polycall::OK)
        print msg["from"], msg["id"], msg["payload"], msg["length"]
    polycall::peer_close(outbox); polycall::peer_close(inbox)
}

All functions live in the polycall:: namespace and map 1:1 onto polycall.h:

Every call sets polycall::STATUS (0 = polycall::OK, negative = polycall::E_*, all 19 codes are defined); polycall::FOREVER (4294967295) waits indefinitely. Arguments the C API cannot take (a path with a NUL byte, a timeout outside 0..2^32-1, a fractional number) are refused by the binding with E_INVALID_ARGUMENT and a detail in last_error(). Payloads are byte strings: run gawk with -b (or LC_ALL=C) so length()/substr() count bytes, and set BINMODE = 3 on Windows to read binary files without CRLF translation. A gawk program has one thread, so a blocked peer_recv ends on a message, its timeout, or the node's close; peer_cancel exists for completeness.

Loading: the extension checks polycall_ffi_abi_version() == 1 before it registers anything (otherwise it prints why and defines no function), and on Linux it is linked with -z now, so an old 1.0 libpolycall.so.1 without the ABI v1 symbols fails at load time ("undefined symbol"), never at a later call. The module is named awk_polycall, not polycall: on Windows a DLL called polycall.dll would shadow the MSVC core of the same name.

Building needs gawk's gawkapi.h, a C compiler and the core's pkg-config file (or POLYCALL_CFLAGS / POLYCALL_LIBS). On Windows the extension is built with MSYS2 UCRT64 gcc and loaded by Git-for-Windows or MSYS2 gawk (both API 4.1); give GAWK_CFLAGS=-I<dir holding only gawkapi.h> so the MSYS headers next to it do not replace the mingw ones, and link either core:

make ext CC=gcc GAWK_CFLAGS=-I/path/to/gawkapi-dir \
  POLYCALL_CFLAGS=-I$CORE/include/polycall POLYCALL_LIBS="-L$CORE/lib -lpolycall"

POSIX library

awk -v polycall_cli=/path/to/polycall -f src/awk_polycall.awk -f examples/basic.awk

Functions: polycall_check(), polycall_version(), polycall_strerror() (the status name), polycall_last_error(), polycall_run_config(path [, strict]), polycall_call(endpoint, service, op, input, timeout) (output in POLYCALL_OUTPUT), polycall_peer_open/close/endpoint/node_id/ register/list/ping/health/send/send_file/recv/recv_file, polycall_cleanup(); data comes back in POLYCALL_OUTPUT and POLYCALL_MSG_*. See the comments in src/awk_polycall.awk.

Limits, because the CLI is the transport: the CLI has no strict validation mode, so polycall_run_config(path, 1) applies strictness to the CLI's report (warning count, tls_enabled=true) — use the gawk extension for the core's exact run=1 semantics. There is no unregister (no CLI command), no caller-sized receive buffer, and receive timeouts are capped at 30 s. Text payloads cannot contain NUL in a POSIX awk string; use polycall_peer_send_file / polycall_peer_recv_file for binary data. On MSYS / Git Bash / Cygwin, file arguments are handed to a native polycall.exe as Windows paths (cygpath -m).

Tests

npm test            # = sh tests/run-all.sh, plus the npm package test
make valgrind       # the gawk extension test under valgrind memcheck

tests/run-gawk-ext-test.sh builds the extension and runs tests/gawk_ext_test.awk (the binding-ABI checklist, call against polycall start and polycall daemon start, payloads both ways with a polycall peer serve C node, four concurrent gawk sender processes) plus the loader-error cases (missing / old / ABI-2 library, extension not on AWKLIBPATH). tests/run-awk-test.sh runs tests/awk_polycall_test.awk with every AWK it finds (gawk, mawk, busybox awk). Both use the real core and the real CLI; a missing AWK, CLI or toolchain is exit 77 (SKIP), never a pass. Tested on Linux x86-64 (Debian 12: gawk 5.2.1, mawk, busybox awk) and Windows x64 (Git-for-Windows gawk 5.4.1 with both the MSVC polycall.dll and the UCRT64 libpolycall.dll cores).

Install from npm

npm install awk-polycall

The npm package is a source package: require('awk-polycall') returns absolute paths (awk, extSource, makefile, config, ...); build the extension from it with make -C node_modules/awk-polycall ext.

The configuration override awk-polycallrc uses the core's own grammar (polycall config validate).

Author

Nnamdi Michael Okpala — okpalan@protonmail.com