hive-dsl.lifecycle — io.github.hive-agi/hive-dsl 0.5.2

Lifecycle protocol and bracket macros for composable resource management.

Provides:

1. Lifecycle protocol — start!/stop! for any managed resource.

2. with-lifecycle — Single-resource bracket pattern. Calls start! on entry, stop! in finally (always).

3. with-lifecycle-scope / scope-start! — Multi-resource LIFO cleanup. Resources stopped in reverse start order on scope exit.

4. Reference implementations:

   • ManagedExecutor — wraps ScheduledThreadPoolExecutor
   • ManagedChannel — wraps core.async channel

Designed to prevent leaked executors, unclosed channels, and other resource leaks that cause GC death spirals.

->managed-channel clj

(->managed-channel buf-size)

Create an unstarted ManagedChannel wrapping a core.async buffered channel. Call start! to create the channel.

->managed-executor clj

(->managed-executor pool-size)

Create an unstarted ManagedExecutor wrapping a ScheduledThreadPoolExecutor. Call start! to create the thread pool.

Channeled clj protocol

put! clj

(put! this val)

Put a value onto the channel. Returns true/false via core.async.

take! clj

(take! this)

Take a value from the channel. Returns a channel that yields the value.

Lifecycle clj protocol

start! clj

(start! this)

Start resource. Returns started resource or throws.

stop! clj

(stop! this)

Stop/close resource. Idempotent. Returns stopped resource or throws.

lifecycle-state clj

(lifecycle-state resource)

Return the current lifecycle state of a resource. Convention: state is stored in an atom at key :state. Returns :stopped, :started, or :error.

new-lifecycle-scope clj

(new-lifecycle-scope)

Create a new lifecycle scope. Returns an atom holding a stack of started Lifecycle resources.

scope-start! clj

(scope-start! scope resource)

Start a Lifecycle resource within a scope. Calls start! on the resource, pushes the started resource onto the scope stack, and returns the started resource.

Usage: (scope-start! scope (->managed-executor 4))

scope-stop! clj

(scope-stop! scope)

Stop all resources in a scope in LIFO order. Errors during stop are collected but do not halt the sweep. Returns vector of any stop errors (empty on success).

started? clj

(started? resource)

True if resource is in :started state.

stopped? clj

(stopped? resource)

True if resource is in :stopped state.

Submittable clj protocol

schedule! clj

(schedule! this f delay-ms)

Schedule a zero-arg fn after delay-ms. Returns a ScheduledFuture.

schedule-at-fixed-rate! clj

(schedule-at-fixed-rate! this f initial-delay-ms period-ms)

Schedule a zero-arg fn at fixed rate. Returns a ScheduledFuture.

submit! clj

(submit! this f)

Submit a zero-arg fn for execution. Returns a Future.

with-lifecycle clj macro

(with-lifecycle [sym init-expr] & body)

Bracket pattern for a single Lifecycle resource.

Calls start! on entry, stop! in finally (always — even on exception). Stop! errors are caught and printed as warnings; they do not mask the original exception.

Usage: (with-lifecycle [executor (->managed-executor 4)] (submit! executor task))

Expansion: (let [raw (->managed-executor 4) executor (start! raw)] (try (submit! executor task) (finally (try (stop! executor) (catch Throwable t ...)))))

with-lifecycle-scope clj macro

(with-lifecycle-scope [scope-sym] & body)

Multi-resource scope with LIFO cleanup on exit.

Usage: (with-lifecycle-scope [scope] (let [exec (scope-start! scope (->managed-executor 4)) ch (scope-start! scope (->managed-channel 100))] ;; both auto-stopped in LIFO order on exit (submit! exec task))) ;; ch stopped first, then exec (LIFO)