A mechanism for defining a static whose definition can be provided (or overridden) in another crate.

Example 1:

// core::panic:

extern static PANIC_HANDLER: fn(_: &PanicInfo) -> !;

// user:

impl static core::panic::PANIC_HANDLER = |panic_info| {
    eprintln!("panic: {panic_info:?}");
    loop {}
};

Example 2:

// log crate:

extern static LOGGER: Logger = Logger::default();

// user:

impl static log::LOGGER = Logger::to_stdout().with_colors();

Motivation

We have several items in the standard library that are overridable/definable by the user crate. For example, the (no_std) panic_handler, the global allocator for alloc, and so on.

Each of those is a special lang item with its own special handling. Having a general mechanism simplifies the language and makes this functionality available for other crates, and potentially for more use cases in core/alloc/std.

Explanation

A static can be defined as "externally definable" using the extern keyword as follows:

// In crate `x`:

// Without a default:
extern static A: fn();

// With a default:
extern static B: fn() = || {
    println!("default impl");
};

Another crate can then provide (or override) the definition of these statics using impl static syntax (using their path) as follows:

// In another crate:

impl static x::A = || {
    println!("my implementation of A");
};

impl static x::B = || {
    println!("my implementation of B");
};

Details

Signature

The type on the impl static item is optional, as it is taken from the extern static item referred to by the path. If it is given, the types must match.

One definition

It is an error to have no impl static item (in any crate) for an extern static item without a default value.

It is an error to have multiple impl static items (across all crates) for the same extern static item.

Note: This means that adding or removing an impl static item is a semver incompatible change.

Safety

By marking the extern static as unsafe, defining it becomes unsafe and will also require the unsafe keyword.

Example:

// In crate `x`:

unsafe extern static A: fn();

// In another crate:

unsafe impl static A = || {
    println!("hello");
};

Visibility

extern static items can have a visibility specifier (like pub), which determines who can access the static.

Defining the static can be done by any crate that can name the item. (The impl static item will need to name the item to define, which could be directly or through an alias/re-export.)

Implementation

The implementation will be based on the same mechanisms as used today for the panic_handler and #[global_allocator] features.

The compiler of the root crate will find the implementation of all externally definable statics and give an error if more than one definition is found for any of them. If none are found, the result is either an error, or—if the extern static has a default value—a definition is emitted with that value.

Drawbacks

• It encourages globally defined behaviour.
  • Counterargument: We are already doing this anyway, both inside the standard library (e.g. panic_handler, allocator) and outside (e.g. global logger). This just makes it much easier (and safer) to get right.
• This will invite the addition of many hooks to the standard library to modify existing behavior. While we should consider such possibilities, this RFC does not propose that every piece of standard library behavior should be replaceable.

Rationale and alternatives

Syntax

The syntax re-uses existing keywords. Alternatively, we could:

• Use the override reserved keyword.
• Add a new (contextual) keyword (e.g. existential static, define static, …).
• Use an attribute (e.g. #[externally_definable]) instead.

Functions or statics

This RFC only proposes externally definable statics.

An alternative is to only provide externally implementable functions instead (RFC 3632).

That would be equivalent in power: one can store a function pointer in a static, and one can return a reference to a static from a function.

(Another alternative, of course is to provide both. See future possibilities.)

Visibility

There are two kinds of visibilities to be considered for externally definable statics: who can define the static, and who can access the static.

Not allowing the static to be defined by other crates nullifies the functionality, as the entire point of externally definable statics is that they can be defined in another crate. This visibility is therefore always (implicitly) "pub".

Allowing a more restricted (that is, not pub) visibility for accessing the static can be useful. For example, today's #[panic_handler] can be defined by any crate, but can not be called directly. (Only indirectly through panic!() and friends.)

A downside is that it is not possible to allow this "only definable but not publicly accessible" visibility through an alias.

An alternative could be to use the same visibility for both defining an accessing, which would simply mean that the static (or an alias to it) will always have to be pub.

Prior art

RFC 2494 "Existential types with external definition" has been proposed before, which basically does this for types. Doing this for statics (as a start) saves a lot of complexity.

Unresolved questions

• Should we allow some form of subtyping, similarly to how traits allow trait impls to do subtyping?
• What should the syntax be once we stabilize this?
• How should this work in dynamic libraries?
• Should not having an implementation be an error when the static is never used (after dead code elimination)?

Future possibilities

• Doing this for fn items too. (Perhaps all items that can appear in an extern "Rust" { … } block.)
• Using this for existing overridable global behavior in the standard library, like the panic handler, global allocator, etc.
• Using this mechanism in the standard library to make more parts overridable. For example:
  • Allowing custom implementations of panic_out_of_bounds and panic_overflowing_add, etc. (The Rust for Linux project would make use of this.)
  • Allowing overriding STDOUT and STDERR in std. (This enables custom testing frameworks to capture output. It is also extremely useful on targets like wasm.)
• This could possibly be extended to traits, by allowing a trait te globally implemented. (E.g. extern impl AsyncRuntime, to say that there must be a global implementation of that trait.)