#34775 kernel: allow only one global logging connection

Restricts libbitcoinkernel to a single process-wide logging connection, moves log level configuration onto the connection handle, and invokes logging callbacks without holding the logger mutex. Creating a second concurrent connection now fails, and logging callbacks can be invoked concurrently across threads.

Problem: The underlying KernelLogger is a process-wide singleton, but the API permitted multiple connection handles, misleading consumers into expecting independent loggers. In addition, holding the logger mutex while invoking the consumer callback serialized all logging threads on user code and risked deadlocks if the callback thread triggered any logging (such as during garbage collector finalization).

Evidence of importance:

• Description notes that multiple handles 'give the false impression of independent loggers.'
• Commit 921329000f notes that holding the lock 'serializes all logging threads on user code, and deadlocks if anything on the callback's thread logs, e.g. a garbage collector running finalizers that destroy kernel objects.'

Scope: Modifies the public libbitcoinkernel C API by renaming btck_logging_connection_create to btck_global_logging_connection_create, replacing btck_logging_set_min_level with btck_logging_connection_set_min_level, and requiring logging callbacks to be thread-safe.

Risk of a mistake: medium (other). Synchronization or concurrency bugs in the kernel logging interface could cause deadlocks, race conditions, or crashes in applications consuming libbitcoinkernel.

Changed since the previous assessment: Now invokes logging callbacks without holding the logger mutex, using an atomic in-flight counter to wait for running callbacks on connection destruction, and updates consumers like bitcoin-chainstate to format log output without interleaving concurrent lines.

Ready

Nothing known that would invalidate a review now.

Waiting on (from the thread read):

• reviewer: review of the updated approach and deadlock-free callback invocation 2026-10-19

Mild

objection that needs a change was answered, no reply from the objector (ryanofsky: Prematurely restricts the kernel logging API in a way difficult to reverse without notable simplification)

Thread notes: The author updated the PR to invoke the logging callback without holding the logger mutex to avoid deadlocks from GC finalizers, restructured the commits, and marked the PR ready for review.

Objections, suggestions, and questions:

Support:

• sedited (member) (Concept ACK, 2026-03-09) [read]: Not having separate connections seems simpler, clients can multiplex themselves, and it is pragmatic
• w0xlt (contributor) (Approach ACK, 2026-06-24): (no reason given) [not substantive]

Participants:

• purpleKarrot (member, neutral, 1 statements 2026-03-09 to 2026-03-09): suggested dropping user_data in favor of a plain function pointer
• ryanofsky (member, objection, 2 statements 2026-03-09 to 2026-09-25): objected that limiting logging API to a global callback is premature, hard to reverse, and disrupts callers
• sedited (member, support, 6 statements 2026-03-09 to 2026-08-27): Concept ACK; raised concern about test state leakage and asked about raw pointer
• w0xlt (contributor, support, 3 statements 2026-06-24 to 2026-07-16): Approach ACK; noted test callback leakage and suggested RAII wrapper

114 lines under test/bench/ci.

• src/kernel/bitcoinkernel.cpp +87/-62
• src/test/kernel/test_kernel.cpp +96/-18
• src/kernel/bitcoinkernel.h +27/-22
• src/kernel/bitcoinkernel_wrapper.h +9/-6
• src/bitcoin-chainstate.cpp +9/-4

The short text the ranking pass compares across PRs.

Restricts libbitcoinkernel to allow only one active logging connection per process, and executes logging callbacks without holding the logger mutex. Previously, multiple connection handles gave consumers the false impression of independent loggers, while holding the mutex serialized all logging threads and risked deadlocks if consumer callbacks triggered kernel logging. Attempting to create a second connection now fails, log level configuration is moved to the connection handle, and callbacks must be thread-safe as they can run concurrently.

P1 · bug fix (assessed alone as P2; Raised to P1 and moved up five places: a deadlock risk when consumer callbacks log is a reliability defect exactly at the kernel boundary, and the single-connection decision also gates the per-context logging series.)

Fixes a potential deadlock at the kernel boundary by releasing the logger mutex before invoking consumer callbacks, and aligns the API with the underlying singleton logger. As noted in commit 921329000f, holding the lock 'serializes all logging threads on user code, and deadlocks if anything on the callback's thread logs, e.g. a garbage collector running finalizers that destroy kernel objects.'

Membership: Modifies the libbitcoinkernel C/C++ API headers and implementations (`src/kernel/bitcoinkernel.h`, `src/kernel/bitcoinkernel.cpp`), kernel tests, and the `bitcoin-chainstate` example.

Factors: security/stability 2, bug 1, performance 1, user value 1, leverage 1