Skip to main content

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}