quinzee.cloud

Development edition · 16 November 2026. Commands using repository paths, Make targets or sample projects require access to the Quinzee source checkout. No public installer is available. Examples use disposable local environments.

Contributor’s guide

15. From a shell command to a running service

At the Unix level, Quinzee is a set of ordinary processes. A module is a C++ object inside the cloud process; it is not a daemon, container or dynamically loaded shared library. A PostgreSQL server, by contrast, really is another process with its own address space, sockets and storage. Begin an investigation by identifying the boundary that owns the work.

Follow startup in order

Consider a native launch with an existing private configuration:

bin/debug/quinzee.cloud --config /absolute/path/to/cloud.json

The shell starts the executable. The kernel maps the executable and its required runtime libraries, supplies arguments/environment and inherited file descriptors, and begins execution under the shell's UID and GID. Quinzee does not become root or install a service manager as part of this command. Relative paths resolve against this process's current working directory.

The composition root in src/quinzee_cloud/main.cpp then performs these steps:

  1. Parse the JSON configuration and command-line overrides. Invalid settings fail before serving requests; the CLI overrides the file.
  2. Block SIGINT and SIGTERM before creating worker threads. Those threads inherit the blocked signal mask.
  3. Prepare diagnostics, migrate the old single-file format when applicable, construct the module host and load the selected modules and dependencies.
  4. Create the request executor with eight workers and a queue of 64 requests.
  5. Construct the native HTTPS listener and optional Azure-name listener, loading their certificate/key pairs. They share the service executor and module host.
  6. Start the listeners and wait for a termination signal using sigwait.

Some modules start additional work while loading: the AMQP listener, deployment processing, Event Grid delivery or optional directory socket. Consequently, the process can have more threads and sockets than the two HTTP listeners suggest. The exact count depends on the selected modules and enabled facilities.

Distinguish processes from threads

operator shell / development launcher
  +-- quinzee.cloud
  |     +-- main thread: sigwait
  |     +-- HTTPS listener I/O thread(s)
  |     +-- eight request workers
  |     +-- module-specific workers and optional telemetry export
  +-- qhq: UI loop and asynchronous client jobs
  +-- rasta: viewer process, shared framebuffer and UDP input
  +-- engine helper: Python controller, Docker CLI subprocesses
  +-- hosting helper: Python controller, Docker CLI subprocesses
  +-- slapd: optional LDAP frontend (ldap.py execs this executable)

Docker daemon / container runtime
  +-- cloud and CoreDNS containers when using Compose
  +-- managed PostgreSQL / MySQL / Valkey containers
  +-- Functions host + isolated .NET worker, or web application containers

This is an ownership sketch, not a promise about every PPID on every system. Container processes are supervised by the container runtime; they are not Unix children of the cloud just because an ARM request caused them to be created. Stopping a Python controller therefore does not automatically stop its containers.

Threads share process memory and file descriptors. Mutexes protect C++ state; they do not protect a directory against a separate process editing its files. The request workers wait on a condition variable when idle. In Linux tools that can appear as a futex wait. A sleeping worker is usually idle, not deadlocked.

Observe one known native process

Choose the PID of your own lab instance, rather than terminating every process with a matching name. The commands below use an explicit PID:

cloud_pid=12345
ps -p "$cloud_pid" -o pid,ppid,user,stat,etimes,comm
ps -L -p "$cloud_pid" -o pid,tid,stat,pcpu,wchan:28,comm
readlink "/proc/$cloud_pid/exe"
readlink "/proc/$cloud_pid/cwd"
cat "/proc/$cloud_pid/limits"

Replace 12345 before running. Expect one PID with several TIDs. The executable and working directory tell you which build and relative paths are in use. The limits file explains ceilings such as open files; it does not mean Quinzee can safely use every descriptor allowed by the OS. Its own queues, connections and resource stores have additional bounds.

For a container, obtain its host PID with a narrow inspection:

cloud_container=$(docker compose ps -q quinzee-cloud)
docker inspect --format '{{.State.Pid}} {{.State.Status}}' "$cloud_container"

That is a host PID, which can differ from the PID visible inside the container. With a remote Docker context it belongs to the remote Docker host, not your workstation's /proc.

Understand graceful termination

SIGINT from Ctrl+C and SIGTERM from a supervisor wake the main thread's sigwait. Normal C++ code stops HTTP listeners; it does not perform complex cleanup from an asynchronous signal handler. Each listener stops accepting, closes idle/partial connections, and gives waiting work or active writes the configured shutdown allowance before closing stragglers. The library default is five seconds per listener.

Leaving main then destroys local owners in reverse order: the exporter, listeners, request executor and module host are released while their dependencies still exist. The executor requests worker stop, wakes sleepers and joins threads. Joining cannot forcibly interrupt arbitrary blocking application code; handlers and external calls must honour cancellation or have their own bounded timeouts. The earlier “shutdown complete” log does not mean every local destructor has already finished.

SIGKILL, an OOM kill or power loss skips this C++ cleanup. A container manager may escalate to SIGKILL when its grace period expires. Do not treat that timeout as a transaction coordinator: recovery still depends on the individual durable stores. The persistence chapter explains which operations survive interruption.

Closing QHQ only closes a client. Unloading a module changes admission and worker lifetime inside the cloud. Stopping a hosted app changes an external workload. These are three different operations with different owners.