patcho.lifecycle

Liking cljdoc? Tell your friends :D

Clojure only.

Module lifecycle management with dependency resolution.

Provides runtime lifecycle management for modules with explicit dependency declaration and automatic startup ordering.

Design Philosophy

This namespace provides a lightweight registry for managing module lifecycle:

Modules register themselves at namespace load time
Dependencies are declared explicitly
Operations are RECURSIVE - automatically handle dependencies
Cleanup uses reference counting (claimed-by semantics)
State tracking prevents double-start/stop
Setup phase is separate from start/stop (one-time vs runtime)

Usage

Registration (at namespace load time)

(ns my.module
  (:require [patcho.lifecycle :as lifecycle]))

(lifecycle/register-module! :my/module
  {:depends-on [:other/module]
   :setup (fn []
            (create-tables!))
   :cleanup (fn []
              (drop-tables!))
   :start (fn []
            (start-connections!)
            (subscribe-to-events!))
   :stop (fn []
           (unsubscribe!)
           (close-connections!))})

Application Startup

(ns my.app
  (:require
    my.database      ; Registers :my/database
    my.cache         ; Registers :my/cache (depends on :my/database)
    my.api           ; Registers :my/api (depends on :my/cache)
    [patcho.lifecycle :as lifecycle]))

;; Set default store once (typically in main or init)
(lifecycle/set-store! (lifecycle/->FileLifecycleStore ".lifecycle"))

;; Simple approach: Just start! (auto-runs setup if needed)
(lifecycle/start! :my/api)
;; → Setups (if needed) and starts: :my/database → :my/cache → :my/api
;; Setup is idempotent - only runs once, tracked via lifecycle store

;; OR explicit control: Run setup separately (optional)
(lifecycle/setup! :my/api)  ; One-time: setup all dependencies
(lifecycle/start! :my/api)  ; Runtime: start all dependencies

;; Visualize dependencies
(lifecycle/print-dependency-tree :my/api)
;; :my/api
;; └── :my/cache
;;     └── :my/database

;; Later: stop (RECURSIVE - stops dependents first)
(lifecycle/stop! :my/database)
;; → Stops: :my/api → :my/cache → :my/database

;; Surgical stop (only this module)
(lifecycle/stop-only! :my/api)

;; Cleanup (RECURSIVE with reference checking)
(lifecycle/cleanup! :my/api)
;; → Cleans :my/api
;; → Cleans :my/cache (if no other modules depend on it)
;; → Cleans :my/database (if no other modules depend on it)

Relationship to patcho.patch

Lifecycle management is complementary to version management:

patcho.patch: Version migrations (data/schema state transitions)
patcho.lifecycle: Runtime management (start/stop with dependencies)

They work together:

Apply patches to reach target version (patch/level!)
Start runtime services (lifecycle/start!) - auto-runs setup if needed

Note: start! automatically runs setup for modules that have a setup function, making the system easy to use while maintaining explicit control when needed.

1-arg fn invoked after every module phase transition. Patcho has no logging dependency by design, so this is the seam a host application rebinds to route lifecycle transitions into its own observability stack.

Receives a map:

{:phase :started :topic :my/api} {:phase :stopped :topic :my/api} {:phase :start-failed :topic :my/api :error <Throwable>}

Called for EVERY module, so a host gets guaranteed coverage without each module having to remember to announce itself. Exceptions thrown by the fn are swallowed — observability must never break a lifecycle transition.

Defaults to default-on-lifecycle-event, which prints to stdout/stderr. Set to nil to silence patcho entirely.

1-arg fn invoked after every module phase transition. Patcho has no logging
dependency by design, so this is the seam a host application rebinds to route
lifecycle transitions into its own observability stack.

Receives a map:

  {:phase :started      :topic :my/api}
  {:phase :stopped      :topic :my/api}
  {:phase :start-failed :topic :my/api :error <Throwable>}

Called for EVERY module, so a host gets guaranteed coverage without each
module having to remember to announce itself. Exceptions thrown by the fn
are swallowed — observability must never break a lifecycle transition.

Defaults to `default-on-lifecycle-event`, which prints to stdout/stderr.
Set to nil to silence patcho entirely.

`Ctrl`+`k`	Jump to recent docs
`←`	Move to previous article
`→`	Move to next article
`Ctrl`+`/`	Jump to the search field