Skip to content

Quick Start

This page walks through the API surface end to end: a plain synchronous run, a timeout that escalates SIGTERM → SIGKILL, cooperative cancellation, the low-level asynchronous primitive, and a pipeline. Each example builds on the last — see the Guide section for the full option reference behind each call.

A synchronous run

(let ((command (process-kit:make-command
                "/usr/bin/printf" (list "%s\n" "hello, world")
                :stdout :capture
                :stderr :capture)))
  (process-kit:run-command command))
;; => a PROCESS-RESULT whose stdout is "hello, world\n"

make-command builds an immutable command-spec; run-command launches it and blocks until it exits (or the deadline you gave it fires). For a one-shot call, skip the intermediate command-spec and call run directly with a program and argument list.

Timeouts and escalation

A command that runs too long is escalated SIGTERM → SIGKILL and, by default, signals a condition:

(handler-case
    (process-kit:run "sleep" (list "10") :timeout 1)
  (process-kit:process-timeout-error (e)
    (format t "timed out after ~a seconds~%"
            (process-kit:process-timeout-error-timeout e))))

Or ask for a result instead of a condition with :on-timeout :return:

(let ((result (process-kit:run "sleep" (list "10")
                                :timeout 1
                                :on-timeout :return)))
  (process-kit:process-result-timed-out-p result)) ;; => T

Cancellation

Cancellation is cooperative at the API boundary and terminates the command's whole process group, not just its immediate child:

(let ((token (process-kit:make-cancellation-token)))
  (process-kit:cancel token)
  (process-kit:run-command
   (process-kit:make-command "/bin/sleep" (list "10"))
   :cancellation-token token
   :on-cancel :return))
;; => a PROCESS-RESULT whose cancelled-p is true

See Cancellation for the escalation timing and how tokens compose with communicate-async tasks.

Streaming output yourself

spawn/spawn-command are the low-level async primitive for callers who want to drive the process themselves instead of letting run/communicate manage it end to end. with-process terminates/reaps the child and closes its streams on exit:

(process-kit:with-process
    (process (process-kit:spawn-command
              (process-kit:make-command
               "/usr/bin/printf" (list "hello\n")
               :stdout :pipe)))
  (read-line (process-kit:process-output process)))

See Asynchronous Execution for the full process-handle surface and the event-driven process-task API.

Pipelines

A pipeline captures the final stage's stdout and every stage's stderr:

(process-kit:run-pipeline
 (list (process-kit:make-command "/usr/bin/printf" (list "c\nb\na\n"))
       (process-kit:make-command "/usr/bin/sort" nil)))
;; => a PIPELINE-RESULT whose stdout is "a\nb\nc\n"

See Pipelines for stage wiring details and run-pipeline/checked.

Where to next