The core as a shared library, called from Python with ctypes

The service of the previous page pays for a process on every request. The other way to reach the same function is to put it in a shared library: the Python process loads the file once, and a call is a function call in the same address space. There is no line to write and no child to start, and the answer arrives in a buffer the caller owns.

What it costs is the boundary itself. Only C types cross it, so the line protocol has to be written into a buffer by hand, the lifetime of that buffer has to be part of the contract, and the Haskell runtime has to be started before the first call. The page shows each of those with the real build and the real calls, including the build command that does not work.

Why a shared library

A shared library is the cheapest boundary there is: a call is a jump, and the data is in the caller's memory. It is also the least forgiving. A process boundary is a wall that a wrong pointer cannot cross; inside one address space a wrong length is a corrupted heap, and a value that one side frees while the other still reads it is a crash with no stack trace that mentions the other language.

The design that keeps it small is the one this page uses: one exported function, no Haskell value that outlives the call, and a buffer that the caller allocates and the callee fills. Nothing is returned by pointer, so there is nothing to free, and the only shared state is the runtime itself.

The exported function

foreign export ccall core_respond makes the Haskell function visible to the linker under its own name. The signature is the contract: the request as a NUL-terminated string in, the answer written into a buffer of the given size, and the number of bytes written as the result. A negative result means the answer did not fit, and nothing was written.

{-# LANGUAGE ForeignFunctionInterface #-} module Core (core_respond) where import qualified Data.ByteString as BS import qualified Data.Text as T import qualified Data.Text.Encoding as TE import Data.Word (Word8) import Foreign.C.String (CString, peekCString) import Foreign.C.Types (CInt (..)) import Foreign.Marshal.Utils (copyBytes) import Foreign.Storable (pokeByteOff) import Pricing (respond) foreign export ccall core_respond :: CString -> CString -> CInt -> IO CInt -- | Answer one request line into a buffer of the caller and return the number -- of bytes written, or -2 when the answer does not fit. core_respond :: CString -> CString -> CInt -> IO CInt core_respond input output size = do line <- peekCString input let payload = TE.encodeUtf8 (T.pack (respond line)) needed = BS.length payload + 1 capacity = fromIntegral size if needed > capacity then pure (-2) else BS.useAsCStringLen payload $ \(source, lengthBytes) -> do copyBytes output source lengthBytes pokeByteOff output lengthBytes (0 :: Word8) pure (fromIntegral lengthBytes)

The body is four lines of marshalling. peekCString copies the request into a Haskell String; the answer is encoded to UTF-8 with Data.Text.Encoding, because a Haskell Char is not a byte and the protocol is UTF-8; copyBytes writes the bytes into the caller's buffer and a NUL is poked after them. The size check happens before the copy, so a small buffer is an error and not a write past the end.

Two builds: the one that fails and the one that works

The obvious command is ghc -shared, and in this image it fails. GHC links the static archives of its libraries, and those were built for executables, not for position-independent code:

ghc -shared -fPIC -o libcore-plain.so Core.hs Pricing.hs; echo "status $?"

[1 of 3] Compiling Pricing          ( Pricing.hs, Pricing.o )
[2 of 3] Compiling Core             ( Core.hs, Core.o )
[3 of 3] Linking libcore-plain.so
/usr/lib/gcc/x86_64-alpine-linux-musl/15.2.0/../../../../x86_64-alpine-linux-musl/bin/ld: /usr/lib/ghc-9.10.3/lib/../lib/x86_64-linux-ghc-9.10.3-inplace/text-2.1.3-inplace/libHStext-2.1.3-inplace.a(Encoding.o): relocation R_X86_64_32S against `.text.textzm2zi1zi3zminplace_DataziTextziEncoding_zdWSome_info' can not be used when making a shared object; recompile with -fPIC
/usr/lib/gcc/x86_64-alpine-linux-musl/15.2.0/../../../../x86_64-alpine-linux-musl/bin/ld: failed to set dynamic section sizes: bad value
collect2: error: ld returned 1 exit status
ghc-9.10.3: `cc' failed in phase `Linker'. (Exit code: 1)
HasCallStack backtrace:
  collectBacktraces, called at libraries/ghc-internal/src/GHC/Internal/Exception.hs:169:13 in ghc-internal:GHC.Internal.Exception
  toExceptionWithBacktrace, called at libraries/ghc-internal/src/GHC/Internal/IO.hs:260:11 in ghc-internal:GHC.Internal.IO
  throwIO, called at libraries/exceptions/src/Control/Monad/Catch.hs:308:12 in exceptions-0.10.9-inplace:Control.Monad.Catch
  throwM, called at libraries/exceptions/src/Control/Monad/Catch.hs:797:84 in exceptions-0.10.9-inplace:Control.Monad.Catch
  onException, called at compiler/GHC/Driver/Make.hs:2983:23 in ghc-9.10.3-inplace:GHC.Driver.Make


status 1

The first relocation error is the whole story: an archive member was compiled without -fPIC and cannot go into a shared object. The distribution also ships shared versions of the same libraries, and -dynamic is what tells GHC to link those instead. The runtime is one of them and is not added by default, so it is named on the command line:

ghc -Wall -O1 -shared -dynamic -fPIC -o libcore.so Core.hs Pricing.hs -lHSrts-1.0.2-ghc9.10.3; echo "status $?"

[1 of 3] Compiling Pricing          ( Pricing.hs, Pricing.o )
[2 of 3] Compiling Core             ( Core.hs, Core.o )
[3 of 3] Linking libcore.so
status 0

The library is 40,272 bytes and exports one symbol of its own; the runtime, the base library and the rest are dependencies it names, which is why the same file needs GHC's libraries installed where the loader can find them:

nm -D libcore.so | grep -E " T core_respond"
ls -l libcore.so

000000000000583d T core_respond
status 0

40272 libcore.so
status 0

Calling it from ctypes

ctypes loads the file and lets a Python function call a symbol by name. Two things have to be said in Python because C does not say them: the argument and result types of the exported function, and hs_init, which starts the Haskell runtime before the first call. create_string_buffer(256) is the buffer, and its lifetime is the call.

import ctypes import sys LIB = "/tmp/hsm/project/libcore.so" lib = ctypes.CDLL(LIB) lib.hs_init.argtypes = [ctypes.POINTER(ctypes.c_int), ctypes.POINTER(ctypes.c_char_p)] lib.hs_init(None, None) lib.core_respond.argtypes = [ctypes.c_char_p, ctypes.c_char_p, ctypes.c_int] lib.core_respond.restype = ctypes.c_int def ask(line: str) -> str: buffer = ctypes.create_string_buffer(256) written = lib.core_respond(line.encode(), buffer, len(buffer)) if written < 0: raise RuntimeError(f"core_respond returned {written}") return buffer.value.decode() if __name__ == "__main__": for request in ["PRICE tea 3", "PRICE coffee 3", "PRICE gold 1", "PRICE tea 0"]: print(f"{request:16s} -> {ask(request)}") sys.exit(0)

python3 ctypes_client.py; echo "status $?"

PRICE tea 3      -> OK 750 7.50
PRICE coffee 3   -> OK 2632 26.32
PRICE gold 1     -> ERR E_SKU unknown sku: gold
PRICE tea 0      -> ERR E_QTY quantity out of range: 0
status 0

Four answers, byte for byte the ones the executable printed through the pipe. The two ways reach the same function, which is the point of keeping the logic in a pure module: the shared library exports respond and nothing else, so there is no second pricing rule to keep in step.

The four traps of the boundary

The runtime is not started. Without hs_init the first call is a jump into a runtime that has no heap, and the process dies without an exception. A library of this shape has to document that the caller initialises it, and a Python package that wraps one does it at import.

The buffer size is the caller's problem. The function returns -2 when the answer does not fit, and that is a contract, not a courtesy: the check is before the copy because there is no safe way to discover the size afterwards. A C caller that ignores the result has a truncated line, which the next parse will report as a syntax error.

Chars are not bytes. A Haskell String is a list of code points and the buffer is bytes, so the answer is encoded explicitly. Writing fromEnum per character would work for the ASCII answers of this project and would corrupt the message of an unknown SKU with an accent in it, which is exactly the kind of bug that appears in production and not in a test.

The build is not portable. -dynamic and the exact RTS library name are properties of this GHC installation, and the library links against the C library of the machine that built it, which here is musl. The deployment page is about what an image needs because of that; the image of the executable was built and run on the host, and the page says what an image of this library would need on top of it.

The Haskell lesson on this boundary is calling Haskell from Python, and the next page measures what the two ways cost per call. The numbers are in microseconds and milliseconds, and the ratio is larger than most people guess before they see it.

The library was built with GHC 9.10.3 and called from Python 3.14.10 with the ctypes of the standard library, on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev