Bug: 285067342

Clone this repo:
  1. a596030 Update Android.bp by running cargo_embargo am: f1723cf5fd by James Farrell · 9 weeks ago main master
  2. f1723cf Update Android.bp by running cargo_embargo by James Farrell · 9 weeks ago
  3. 9a4a3d6 Update Android.bp by running cargo_embargo am: 85634ab1bc by James Farrell · 2 months ago
  4. 85634ab Update Android.bp by running cargo_embargo by James Farrell · 2 months ago
  5. ee5fe7e Migrate to cargo_embargo. am: 1be1fde9f3 am: bf019acf14 am: aff551977c by Andrew Walbran · 8 months ago android14-qpr3-release android14-qpr3-s2-release android-14.0.0_r50 android-14.0.0_r51 android-14.0.0_r52 android-14.0.0_r53 android-14.0.0_r54

Linkme: safe cross-platform linker shenanigans

ComponentLinuxmacOSWindowsFreeBSDillumosOther...†
Distributed slice💚💚💚💚💚

† We welcome PRs adding support for any platforms not listed here.

[dependencies]
linkme = "0.3"

Supports rustc 1.62+

Distributed slice

A distributed slice is a collection of static elements that are gathered into a contiguous section of the binary by the linker. Slice elements may be defined individually from anywhere in the dependency graph of the final binary.

The implementation is based on link_section attributes and platform-specific linker support. It does not involve life-before-main or any other runtime initialization on any platform. This is a zero-cost safe abstraction that operates entirely during compilation and linking.

Declaration

A static distributed slice is declared by writing #[distributed_slice] on a static item whose type is [T] for some type T. The initializer expression must be [..] to indicate that elements come from elsewhere.

use linkme::distributed_slice;

#[distributed_slice]
pub static BENCHMARKS: [fn(&mut Bencher)] = [..];

Elements

Slice elements may be registered into a distributed slice by a #[distributed_slice(...)] attribute in which the path to the distributed slice is given in the parentheses. The initializer is required to be a const expression.

use linkme::distributed_slice;
use other_crate::BENCHMARKS;

#[distributed_slice(BENCHMARKS)]
static BENCH_DESERIALIZE: fn(&mut Bencher) = bench_deserialize;

fn bench_deserialize(b: &mut Bencher) {
    /* ... */
}

Elements may be defined in the same crate that declares the distributed slice, or in any downstream crate. Elements across all crates linked into the final binary will be observed to be present in the slice at runtime.

The distributed slice behaves in all ways like &'static [T].

fn main() {
    // Iterate the elements.
    for bench in BENCHMARKS {
        /* ... */
    }

    // Index into the elements.
    let first = BENCHMARKS[0];

    // Slice the elements.
    let except_first = &BENCHMARKS[1..];

    // Invoke methods on the underlying slice.
    let len = BENCHMARKS.len();
}

The compiler will require that the static element type matches with the element type of the distributed slice. If the two do not match, the program will not compile:

#[distributed_slice(BENCHMARKS)]
static BENCH_WTF: usize = 999;
error[E0308]: mismatched types
  --> src/distributed_slice.rs:65:19
   |
17 | static BENCH_WTF: usize = 999;
   |                   ^^^^^ expected fn pointer, found `usize`
   |
   = note: expected fn pointer `fn(&mut other_crate::Bencher)`
                    found type `usize`

Function elements

As a shorthand for the common case of distributed slices containing function pointers, the distributed_slice attribute may be applied directly to a function definition to place a pointer to that function into a distributed slice.

use linkme::distributed_slice;

#[distributed_slice]
pub static BENCHMARKS: [fn(&mut Bencher)] = [..];

// Equivalent to:
//
//    #[distributed_slice(BENCHMARKS)]
//    static _: fn(&mut Bencher) = bench_deserialize;
//
#[distributed_slice(BENCHMARKS)]
fn bench_deserialize(b: &mut Bencher) {
    /* ... */
}

License