tvm_ffi/static_init.rs
1/*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19
20//! Static init blocks: code that runs when the program or library that holds it loads. The
21//! blocks of a program or library are gathered at link time, wherever in it they are, and a
22//! constructor runs them when it loads. Once Python loads a library built on this crate, by any
23//! means, it sees what the blocks registered, such as global functions. A block that several
24//! libraries of a process have, as each links its own copy of a crate they share, runs once. See
25//! [`static_init_block!`](crate::static_init_block).
26
27use std::ffi::c_void;
28use std::panic::catch_unwind;
29use std::sync::{Once, OnceLock};
30
31use crate::{Any, Error, Function, INTERNAL_ERROR, Result};
32
33#[doc(hidden)]
34pub use linkme;
35
36/// Run code when the program or library that holds it loads, the Rust form of
37/// `TVM_FFI_STATIC_INIT_BLOCK`. The body is the body of a function that returns
38/// [`Result<()>`](crate::Result): it registers what the library defines, such as global functions,
39/// and stops at its first error, which `?` returns. A body whose statements all end in `;` returns
40/// `Ok(())`; one that ends in an expression returns it, a `Result<()>`.
41///
42/// ```standalone_crate
43/// use tvm_ffi::{Function, Result};
44///
45/// fn add_one(x: i64) -> Result<i64> {
46/// Ok(x + 1)
47/// }
48///
49/// tvm_ffi::static_init_block! {
50/// Function::register_global_typed("my_ext.add_one", add_one, "Add one to an integer.")?;
51/// }
52///
53/// // Registered when the program loaded.
54/// let add_one = Function::get_global("my_ext.add_one")?;
55/// assert_eq!(i64::try_from(add_one.call_tuple((1i64,))?)?, 2);
56/// # Ok::<(), tvm_ffi::Error>(())
57/// ```
58///
59/// A block runs when its program or library loads: it adds a constructor, which the loader runs,
60/// and the first constructor runs every block of the program or library, in the order of their
61/// modules and lines. Python sees what the blocks of a library registered once it loads the
62/// library, by any means, and the library stays loaded for the process, as the registrations keep
63/// its code. An error cannot reach a caller when the library loads: it is printed, and
64/// [`run_static_init_blocks`](crate::run_static_init_blocks) reports it again. Where the loader
65/// does not run the constructor, call [`run_static_init_blocks`](crate::run_static_init_blocks)
66/// first. A crate that a library depends on but never names is not linked into it, nor are its
67/// blocks: name it, as `use my_crate as _;` does.
68///
69/// A block runs once per process. Every library built on the crate links its own copy of the
70/// crates it uses, so a block of a crate that several libraries link is in each of them; the first
71/// library that runs it registers what it defines, and the others skip it. A block of another
72/// version of the crate, or whose text differs, is another block, and registering what it defines
73/// again is an error. A change to the body of a function the block calls does not make another
74/// block: rebuild every library that links a crate after changing it. A block is known by the
75/// module path, line, crate version and text, so two crates of the same name and version, such as
76/// plugins built from one template, share the identities of their blocks and only the first runs:
77/// give them distinct crate names.
78///
79/// A panic in a block is caught and reported as its error, except under `panic = "abort"`, where
80/// it aborts the process; a failed `rs_object` registration is such a panic.
81#[macro_export]
82macro_rules! static_init_block {
83 ($($body:tt)*) => {
84 const _: () = {
85 #[$crate::static_init::linkme::distributed_slice($crate::static_init::STATIC_INIT_BLOCKS)]
86 #[linkme(crate = $crate::static_init::linkme)]
87 static BLOCK: $crate::static_init::StaticInitBlock =
88 $crate::static_init::StaticInitBlock::__new(
89 ::core::module_path!(),
90 ::core::line!(),
91 match ::core::option_env!("CARGO_PKG_VERSION") {
92 ::core::option::Option::Some(version) => version,
93 ::core::option::Option::None => "",
94 },
95 ::core::stringify!($($body)*),
96 __tvm_ffi_static_init_block_body,
97 );
98 // A function item rather than a closure, to carry the attribute: a body that diverges,
99 // such as one that panics, makes the conversion of its value unreachable.
100 #[allow(unreachable_code)]
101 fn __tvm_ffi_static_init_block_body() -> $crate::Result<()> {
102 $crate::static_init::IntoStaticInitResult::into_static_init_result({ $($body)* })
103 }
104 #[used]
105 #[cfg_attr(target_os = "linux", unsafe(link_section = ".init_array"))]
106 #[cfg_attr(target_os = "macos", unsafe(link_section = "__DATA,__mod_init_func"))]
107 #[cfg_attr(windows, unsafe(link_section = ".CRT$XCU"))]
108 static RUN_AT_LOAD: extern "C" fn() = $crate::static_init::__run_at_load;
109 };
110 };
111}
112
113/// The value of the body of a [`static_init_block!`](crate::static_init_block), converted to the
114/// outcome of the block: `()`, of a body whose statements all end in `;`, is `Ok(())`, a
115/// [`Result<()>`](crate::Result) is itself, and a body that diverges, as one that panics or ends
116/// in `return`, has no value to convert.
117#[doc(hidden)]
118#[diagnostic::on_unimplemented(
119 message = "a static init block returns `Result<()>`, not `{Self}`",
120 label = "the value of the block",
121 note = "end the last statement of the block with `;`, or return a `Result<()>`"
122)]
123pub trait IntoStaticInitResult {
124 fn into_static_init_result(self) -> Result<()>;
125}
126
127impl IntoStaticInitResult for () {
128 fn into_static_init_result(self) -> Result<()> {
129 Ok(())
130 }
131}
132
133impl IntoStaticInitResult for Result<()> {
134 fn into_static_init_result(self) -> Result<()> {
135 self
136 }
137}
138
139/// The never type `!`, which stable Rust names only as the return type of a function pointer.
140/// The value of a body that diverges is `!`, or `()` where an edition before 2024 falls back to it.
141#[doc(hidden)]
142pub trait FnOutput {
143 type Output;
144}
145
146impl<T> FnOutput for fn() -> T {
147 type Output = T;
148}
149
150#[doc(hidden)]
151pub type Never = <fn() -> ! as FnOutput>::Output;
152
153impl IntoStaticInitResult for Never {
154 fn into_static_init_result(self) -> Result<()> {
155 self
156 }
157}
158
159/// A [`static_init_block!`](crate::static_init_block), gathered at link time.
160#[doc(hidden)]
161pub struct StaticInitBlock {
162 /// The module and line of the block.
163 module: &'static str,
164 line: u32,
165 /// The version of the block's crate and a hash of the block's text, which with the module and
166 /// line identify the block in every library that links the crate.
167 version: &'static str,
168 text_hash: u64,
169 body: fn() -> Result<()>,
170 /// The outcome of the block, which runs once: the error's text if it failed.
171 outcome: OnceLock<std::result::Result<(), std::string::String>>,
172}
173
174/// The [`static_init_block!`](crate::static_init_block)s of the program or library, gathered at
175/// link time from the whole of it.
176#[doc(hidden)]
177#[linkme::distributed_slice]
178pub static STATIC_INIT_BLOCKS: [StaticInitBlock];
179
180impl StaticInitBlock {
181 #[doc(hidden)]
182 pub const fn __new(
183 module: &'static str,
184 line: u32,
185 version: &'static str,
186 text: &str,
187 body: fn() -> Result<()>,
188 ) -> Self {
189 let text_hash = text_hash(text);
190 Self {
191 module,
192 line,
193 version,
194 text_hash,
195 body,
196 outcome: OnceLock::new(),
197 }
198 }
199
200 /// The identity of the block in the process, `module:line@version#hash`: the same in every
201 /// library that links the block's crate, and another one if the crate version or the block's
202 /// text differs.
203 #[doc(hidden)]
204 pub fn identity(&self) -> std::string::String {
205 format!(
206 "{}:{}@{}#{:016x}",
207 self.module, self.line, self.version, self.text_hash
208 )
209 }
210
211 /// The name of the global function that marks the block run in the process,
212 /// `ffi.static_init_block.<identity>`. The libraries of a process share the global function
213 /// table, and their statics are their own.
214 #[doc(hidden)]
215 pub fn marker(&self) -> std::string::String {
216 format!("ffi.static_init_block.{}", self.identity())
217 }
218
219 /// Run the block if it has not run. The caller that runs a failing block gets its error;
220 /// later ones get an error that names the block.
221 #[doc(hidden)]
222 pub fn run(&self) -> Result<()> {
223 let mut failure = None;
224 let outcome = self.outcome.get_or_init(|| {
225 self.run_once().map_err(|error| {
226 let text = format!("{}: {}", error.kind(), error.message());
227 failure = Some(error);
228 text
229 })
230 });
231 match (failure, outcome) {
232 (Some(error), _) => Err(error),
233 (None, Ok(())) => Ok(()),
234 (None, Err(text)) => {
235 let message = format!("The static init block at {} failed: {text}", self.place());
236 Err(Error::new(INTERNAL_ERROR, &message))
237 }
238 }
239 }
240
241 /// Run the block unless another library of the process has run it. Every library links its
242 /// own copy of the crates it is built from, so the same block can be in several, and what it
243 /// defines is registered once, by the first library that runs it. The block is marked once it
244 /// succeeds, so that one that fails fails in every library. A panic in the body is its error.
245 fn run_once(&self) -> Result<()> {
246 let marker = self.marker();
247 if Function::get_global(&marker).is_err() {
248 catch_unwind(self.body).unwrap_or_else(|payload| Err(Error::from_panic(payload)))?;
249 Function::register_global(&marker, Function::from_packed(|_| Ok(Any::default())))?;
250 }
251 Ok(())
252 }
253
254 /// Where the block is, for an error.
255 fn place(&self) -> std::string::String {
256 format!("{}:{}", self.module, self.line)
257 }
258}
259
260/// The FNV-1a hash of `text` without its whitespace, which does not depend on how the compiler
261/// spaces the tokens of a block it stringifies.
262const fn text_hash(text: &str) -> u64 {
263 let bytes = text.as_bytes();
264 let mut hash: u64 = 0xcbf2_9ce4_8422_2325;
265 let mut i = 0;
266 while i < bytes.len() {
267 if !bytes[i].is_ascii_whitespace() {
268 hash = (hash ^ bytes[i] as u64).wrapping_mul(0x0100_0000_01b3);
269 }
270 i += 1;
271 }
272 hash
273}
274
275/// Run every block of this program or library that has not run, in the order of their modules
276/// and lines, and return those that failed, each with its first error.
277fn run_blocks() -> Vec<(&'static StaticInitBlock, Error)> {
278 let mut blocks: Vec<&StaticInitBlock> = STATIC_INIT_BLOCKS.iter().collect();
279 blocks.sort_by_key(|block| (block.module, block.line));
280 blocks
281 .into_iter()
282 .filter_map(|block| block.run().err().map(|e| (block, e)))
283 .collect()
284}
285
286/// Run every [`static_init_block!`](crate::static_init_block) of this program or library that has
287/// not run, in the order of their modules and lines; running again does nothing. Every block is
288/// tried, and the error lists those that failed. A block that another library of the process has
289/// run, from the same version of its crate and the same text, is skipped: libraries that link the
290/// same crate register what its blocks define once.
291///
292/// The blocks run when their program or library loads, so this reports the errors of those that
293/// failed, which could not reach a caller then: a library exports it, with
294/// [`tvm_ffi_dll_export_typed_func!`](crate::tvm_ffi_dll_export_typed_func), for its loader to
295/// call. Where the loader does not run the blocks, call it before using what they define.
296pub fn run_static_init_blocks() -> Result<()> {
297 // As at load: what the blocks register keeps this library's code.
298 keep_loaded();
299 let mut failures = run_blocks();
300 if failures.len() <= 1 {
301 return failures.pop().map_or(Ok(()), |(_, error)| Err(error));
302 }
303 let mut message = format!("{} static init blocks failed:", failures.len());
304 for (block, error) in &failures {
305 message.push_str(&format!(
306 "\n {}: {}: {}",
307 block.place(),
308 error.kind(),
309 error.message()
310 ));
311 }
312 Err(Error::new(failures[0].1.kind(), &message))
313}
314
315/// The constructor of every [`static_init_block!`](crate::static_init_block), which the loader
316/// runs when the program or library loads: the first one keeps the library loaded and runs every
317/// block of it. An error cannot reach a caller here, so it is printed; [`run_static_init_blocks`]
318/// reports it again.
319#[doc(hidden)]
320pub extern "C" fn __run_at_load() {
321 static LOADED: Once = Once::new();
322 LOADED.call_once(|| {
323 let library = keep_loaded().unwrap_or_else(|| "static_init_block!".to_string());
324 match catch_unwind(run_blocks) {
325 Ok(failures) => {
326 for (block, error) in failures {
327 eprintln!(
328 "{library}: the static init block at {} failed: {}: {}",
329 block.place(),
330 error.kind(),
331 error.message()
332 );
333 }
334 }
335 Err(_) => eprintln!("{library}: running the static init blocks panicked"),
336 }
337 });
338}
339
340/// Keep the library that holds this code loaded for the rest of the process, as what its blocks
341/// register keeps its code: unloading it, as `tvm_ffi.load_module` does when Python drops the
342/// module, would leave the registrations dangling. Returns the path of the library.
343#[cfg(any(target_os = "linux", target_os = "macos"))]
344fn keep_loaded() -> Option<std::string::String> {
345 use std::ffi::{CStr, c_char, c_int};
346
347 #[repr(C)]
348 struct DlInfo {
349 fname: *const c_char,
350 fbase: *mut c_void,
351 sname: *const c_char,
352 saddr: *mut c_void,
353 }
354 unsafe extern "C" {
355 fn dladdr(addr: *const c_void, info: *mut DlInfo) -> c_int;
356 fn dlopen(filename: *const c_char, flags: c_int) -> *mut c_void;
357 }
358 // RTLD_LAZY | RTLD_NOLOAD | RTLD_NODELETE.
359 #[cfg(target_os = "linux")]
360 const FLAGS: c_int = 0x1 | 0x4 | 0x1000;
361 #[cfg(target_os = "macos")]
362 const FLAGS: c_int = 0x1 | 0x10 | 0x80;
363
364 let null = std::ptr::null_mut();
365 let mut info = DlInfo {
366 fname: null as _,
367 fbase: null,
368 sname: null as _,
369 saddr: null,
370 };
371 // SAFETY: `dladdr` fills `info` for an address of this library, whose path stays valid while
372 // the library is loaded; `dlopen` of a loaded library only marks it, and its handle is kept.
373 unsafe {
374 if dladdr(keep_loaded as *const c_void, &mut info) == 0 || info.fname.is_null() {
375 return None;
376 }
377 dlopen(info.fname, FLAGS);
378 Some(CStr::from_ptr(info.fname).to_string_lossy().into_owned())
379 }
380}
381
382/// Keep the library that holds this code loaded for the rest of the process, as what its blocks
383/// register keeps its code. Returns the path of the library.
384#[cfg(windows)]
385fn keep_loaded() -> Option<std::string::String> {
386 use std::ffi::OsString;
387 use std::os::windows::ffi::OsStringExt;
388
389 type Module = *mut c_void;
390 #[link(name = "kernel32")]
391 unsafe extern "system" {
392 fn GetModuleHandleExW(flags: u32, module_name: *const u16, module: *mut Module) -> i32;
393 fn GetModuleFileNameW(module: Module, filename: *mut u16, size: u32) -> u32;
394 }
395 // GET_MODULE_HANDLE_EX_FLAG_PIN | GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS: the module that
396 // holds the address stays loaded until the process exits.
397 const FLAGS: u32 = 0x1 | 0x4;
398
399 let mut module: Module = std::ptr::null_mut();
400 let mut path = vec![0u16; 32768];
401 // SAFETY: `GetModuleHandleExW` takes an address of this library as the name, and
402 // `GetModuleFileNameW` writes at most `path.len()` units into `path`.
403 unsafe {
404 let address = keep_loaded as *const c_void as *const u16;
405 if GetModuleHandleExW(FLAGS, address, &mut module) == 0 || module.is_null() {
406 return None;
407 }
408 let len = GetModuleFileNameW(module, path.as_mut_ptr(), path.len() as u32) as usize;
409 if len == 0 {
410 return None;
411 }
412 Some(
413 OsString::from_wide(&path[..len.min(path.len())])
414 .to_string_lossy()
415 .into_owned(),
416 )
417 }
418}
419
420#[cfg(not(any(target_os = "linux", target_os = "macos", windows)))]
421fn keep_loaded() -> Option<std::string::String> {
422 None
423}