1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
//! Process-wide engine lifecycle.
//!
//! chDB installs signal handlers and starts threads for the whole process, not
//! for a connection. Both facts are invisible from the connection API and both
//! matter to a host that has its own signal handling or its own teardown
//! sequence, so the controls for them live here.
use ;
use cratebindings;
use crate;
use crateregistry;
/// Choose whether chDB installs process-wide signal handlers.
///
/// May be called at any time, not just before the first connection. Passing
/// `false` sets a process-wide disable flag *and* immediately resets any
/// handlers already installed (chDB's own `chdb_set_signal_handlers_enabled`
/// calls `chdb_reset_signal_handlers` internally when disabling). The flag is
/// consulted whenever the engine installs handlers — at connect for this
/// crate's [`Connection`](crate::connection::Connection) API, and at the
/// start of every query on the one-shot cmdline entry — so a host with an
/// existing connection can still opt out and have it stick.
///
/// Calling this before the first connection is still the cleanest way to
/// ensure the handlers are never installed at all, since it removes the brief
/// window where a query could run before the preference is set. But it is no
/// longer required: this call is infallible and works after connections are
/// already open.
///
/// # Examples
///
/// ```no_run
/// chdb_rust::runtime::signal_handlers(false);
/// let conn = chdb_rust::connection::Connection::open_in_memory()?;
/// # Ok::<(), chdb_rust::error::Error>(())
/// ```
/// Restore every signal handler chDB installed to `SIG_DFL`.
///
/// Does not set the disable flag. Handlers are installed once at connect, not
/// at the start of every [`Connection::query`](crate::connection::Connection::query),
/// so a later query on that connection leaves the disposition at `SIG_DFL`. A
/// later connect may install them again. For an opt-out that also covers a
/// later connect, use [`signal_handlers`]`(false)`, which sets the flag
/// consulted at install as well as resetting.
///
/// # Examples
///
/// ```no_run
/// let conn = chdb_rust::connection::Connection::open_in_memory()?;
/// let _ = conn.query("SELECT 1", chdb_rust::format::OutputFormat::TabSeparated)?;
/// chdb_rust::runtime::reset_signal_handlers();
/// # Ok::<(), chdb_rust::error::Error>(())
/// ```
/// Set once a shutdown has actually succeeded.
///
/// A refusal because connections are still open leaves the engine usable, and
/// this flag correctly stays false for that case — that logic is not changed
/// here. But per `chdb.h`'s own wording on `chdb_shutdown`, once it starts,
/// "the library is closed for business for the rest of the process, whether
/// or not it manages to stop every thread". So a refusal because some thread
/// could not be stopped still closes the engine, yet leaves this flag unset:
/// [`ensure_running`] then can't see it, and a later `open()` surfaces the
/// engine's own `ConnectionFailed` instead of the more informative
/// [`Error::EngineShutDown`] that flag exists to produce.
static SHUT_DOWN: AtomicBool = new;
/// Stop the engine, joining every thread chDB started.
///
/// Call this before a host teardown sequence of its own — global destructors, a
/// finalizing language runtime, a sanitizer exit handler — which would
/// otherwise race the engine's still-running threads.
///
/// A plain exit needs care too. Exiting with a connection still open leaves the
/// engine to be torn down from inside `exit`, and if MergeTree merges are
/// running in the background at that point the process can crash on its way
/// out. Drop every connection before the process exits, and call this after the
/// last one is gone: it returns only once no chDB thread is left. Two common
/// ways a Rust program keeps a connection open at exit: [`std::process::exit`]
/// runs no destructors, and a connection held in a `static` is never dropped.
///
/// This is one-way. Once it succeeds, no further connection can be opened in
/// this process. Calling it again is harmless.
///
/// # Errors
///
/// Returns [`Error::ConnectionsStillOpen`] if any connection is open, and
/// [`Error::EngineCallFailed`] if the engine could not stop every thread. In the
/// latter case `chdb.h` documents the engine as closed for the process
/// regardless — "whether or not it manages to stop every thread" — so this
/// error means the engine is already shut down even though it is reported as
/// a failure; the crate's internal shut-down flag is not set for it (see
/// `SHUT_DOWN`), so a subsequent `open()` will surface `ConnectionFailed`
/// rather than [`Error::EngineShutDown`].
///
/// # Examples
///
/// ```no_run
/// let conn = chdb_rust::connection::Connection::open_in_memory()?;
/// drop(conn);
/// chdb_rust::runtime::shutdown()?;
/// # Ok::<(), chdb_rust::error::Error>(())
/// ```
/// Whether a new connection may still be opened.
pub