[Coding Guideline]: Do Not Depend on Function Pointer Identity Across Crates

[rcseacord]

Chapter

Associated Items

Guideline Title

Do Not Depend on Function Pointer Identity Across Crates

Category

Required

Status

Draft

Release Begin

unclear

Release End

latest

FLS Paragraph ID

fls_1kg1mknf4yx7

Decidability

Decidable

Scope

System

Tags

surprising-behavior

Amplification

Do not rely on the equality or stable identity of function pointers originating from different
crates or that may be inlined, duplicated, or instantiated differently across compilation units,
codegen units, or optimization profiles.

Avoid assumptions about low-level metadata (such as symbol addresses) unless explicitly guaranteed by the Ferrocene Language Specification (FLS).
Function address identity is not guaranteed by Rust and must not be treated as stable.
Rust's fn type is a zero-sized function item promoted to a function pointer,
whose address is determined by the compiler backend.
When a function resides in a different crate,
or when optimizations such as inlining, link-time optimization, or codegen-unit partitioning are enabled,
the compiler may generate multiple distinct code instances for the same function or
alter the address at which it is emitted.

Consequently, the following operations are not reliable:

• Comparing function pointers for equality (fn1 == fn2)
• Assuming a unique function address
• Using function pointers as identity keys (e.g., in maps, registries, matchers)
• Matching behavior based on function address

This rule applies even when the functions are semantically identical, exported as pub, or defined once in source form.

Exception(s)

#[no_mangle] functions are guaranteed to have a single instance.

Rationale

Compiler optimizations may cause function pointers originating from different crates to lose stable identity. Observed behaviors include:

• Cross-crate inlining producing multiple code instantiations
• Codegen-unit separation causing function emission in multiple units
• Incremental builds producing variant symbol addresses
• Link-time optimization merging or splitting functions unpredictably

This behavior has resulted in real-world issues, such as the bug reported in rust-lang/rust#117047, where function pointer comparisons unexpectedly failed due to cross-crate inlining.

Violating this rule may cause:

• Silent logic failures: callbacks not matching, dispatch tables misbehaving.
• Inappropriate branching: identity-based dispatch selecting wrong handler.
• Security issues: adversary-controlled conditions bypassing function-based authorization/dispatch logic.
• Nondeterministic behavior: correctness depending on build flags or incremental state.
• Test-only correctness: function pointer equality passing in debug builds but failing in release/LTO builds.

In short, dependence on function address stability introduces non-portable,
build-profile-dependent behavior, which is incompatible with high-integrity Rust.

Non-Compliant Example - Prose

Due to cross-crate inlining or codegen-unit partitioning, the address of handler_a in crate B may differ from its address in crate A, causing comparisons to fail as shown in this noncompliant code example:

Non-Compliant Example - Code

// crate A
pub fn handler_a() {}
pub fn handler_b() {}
rust

// crate B
use crate_a::{handler_a, handler_b};

fn dispatch(f: fn()) {
if f == handler_a {
println!("Handled by A");
} else if f == handler_b {
println!("Handled by B");
}
}

dispatch(handler_a);

// Error: This may fail unpredictably if handler_a is inlined or duplicated.

Compliant Example - Prose

Replace function pointer comparison with an explicit enum as shown in this compliant example:

Compliant Example - Code

// crate A
pub enum HandlerId { A, B }

pub fn handler(id: HandlerId) {
match id {
HandlerId::A => handler_a(),
HandlerId::B => handler_b(),
}
}

// crate B
use crate_a::{handler, HandlerId};

fn dispatch(id: HandlerId) {
handler(id);
}

dispatch(HandlerId::A); // OK: semantically stable identity

[github-actions]

📋 RST Preview for Coding Guideline

This is an automatically generated preview of your coding guideline in reStructuredText format.

📁 Target File

Add this guideline to: src/coding-guidelines/associated-items.rst

📝 How to Use This

1. Fork the repository (if you haven't already) and clone it locally
2. Create a new branch from main:

   git checkout main
   git pull origin main
   git checkout -b guideline/your-descriptive-branch-name

3. Open the target file src/coding-guidelines/associated-items.rst in your editor
4. Copy the RST content below and paste it at the end of the file (before any final directives if present)
5. Build locally to verify the guideline renders correctly:

   ./make.py

6. Commit and push your changes:

   git add src/coding-guidelines/associated-items.rst
   git commit -m "Add guideline: <your guideline title>"
   git push origin guideline/your-descriptive-branch-name

7. Open a Pull Request against main

📄 Click to expand RST content

.. guideline:: Do Not Depend on Function Pointer Identity Across Crates
    :id: gui_HmesqyUM3daC 
    :category: required
    :status: draft
    :release: unclear-latest
    :fls: fls_1kg1mknf4yx7
    :decidability: decidable
    :scope: system
    :tags: surprising-behavior

    Do not rely on the equality or stable identity of function pointers originating from different crates or that may be inlined, duplicated, or instantiated differently across compilation units, codegen units, or optimization profiles.

    Avoid assumptions about low-level metadata (such as symbol addresses) unless explicitly guaranteed by the Ferrocene Language Specification (FLS). Function address identity is not guaranteed by Rust and must not be treated as stable. Rust’s fn type is a zero-sized function item promoted to a function pointer, whose address is determined by the compiler backend. When a function resides in a different crate, or when optimizations such as inlining, link-time optimization, or codegen-unit partitioning are enabled, the compiler may generate multiple distinct code instances for the same function or alter the address at which it is emitted.

    Consequently, the following operations are not reliable:

    - Comparing function pointers for equality (``fn1 == fn2``)
    - Assuming a unique function address
    - Using function pointers as identity keys (e.g., in maps, registries, matchers)
    - Matching behavior based on function address

    This rule applies even when the functions are semantically identical, exported as ``pub``, or defined once in source form.

    **Exceptions**

    ``#[no_mangle]`` functions are guaranteed to have a single instance.

    .. rationale:: 
        :id: rat_KYSaunyoc6fa 
        :status: draft

        Compiler optimizations may cause function pointers originating from different crates to lose stable identity. Observed behaviors include:

        - Cross-crate inlining producing multiple code instantiations
        - Codegen-unit separation causing function emission in multiple units
        - Incremental builds producing variant symbol addresses
        - Link-time optimization merging or splitting functions unpredictably

        This behavior has resulted in real-world issues, such as the bug reported in rust-lang/rust#117047, where function pointer comparisons unexpectedly failed due to cross-crate inlining.

        Violating this rule may cause:

        - Silent logic failures: callbacks not matching, dispatch tables misbehaving.
        - Inappropriate branching: identity-based dispatch selecting wrong handler.
        - Security issues: adversary-controlled conditions bypassing function-based authorization/dispatch logic.
        - Nondeterministic behavior: correctness depending on build flags or incremental state.
        - Test-only correctness: function pointer equality passing in debug builds but failing in release/LTO builds.

        In short, dependence on function address stability introduces non-portable, build-profile-dependent behavior, which is incompatible with high-integrity Rust.

    .. non_compliant_example::
        :id: non_compl_ex_8POzcD6cToRD 
        :status: draft

        Due to cross-crate inlining or codegen-unit partitioning, the address of ``handler_a`` in crate ``B`` may differ from its address in crate A, causing comparisons to fail as shown in this noncompliant code example:

        .. code-block:: rust

            // crate A
            pub fn handler_a() {}
            pub fn handler_b() {}
            rust

            // crate B
            use crate_a::{handler_a, handler_b};

            fn dispatch(f: fn()) {
                if f == handler_a {
                    println!("Handled by A");
                } else if f == handler_b {
                    println!("Handled by B");
                }
            }

            dispatch(handler_a);

            //  Error:  This may fail unpredictably if handler_a is inlined or duplicated.

    .. compliant_example::
        :id: compl_ex_9DxUkSVH124z 
        :status: draft

        Replace function pointer comparison with an explicit enum as shown in this compliant example:

        .. code-block:: rust

            // crate A
            pub enum HandlerId { A, B }

            pub fn handler(id: HandlerId) {
                match id {
                    HandlerId::A => handler_a(),
                    HandlerId::B => handler_b(),
                }
            }

            // crate B
            use crate_a::{handler, HandlerId};

            fn dispatch(id: HandlerId) {
                handler(id);
            }

            dispatch(HandlerId::A);  // OK: semantically stable identity

---

_{🤖 This comment was automatically generated from the issue content. It will be updated when you edit the issue body.}

[rcseacord]

I generated a PR for this #256

[rcseacord]

Another possible version of this rule I'm stashing here for now:

.. guideline:: Do not rely on function pointer equality for determining function identity
   :id: gui_FnPtrEquality
   :category: required
   :status: draft
   :release: 1.85.0
   :decidability: undecidable
   :scope: module
   :tags: pointers, safety, undefined-behavior

   Do not compare function pointers for equality to determine if they refer to the same function.
   Function pointer equality is not guaranteed to be a reliable indicator of function identity.

   .. rationale::
      :id: rat_FnPtrEqualityReason
      :status: draft

      The Rust language specification does not guarantee that taking the address of the same function 
      multiple times will yield identical pointer values. Several compiler and runtime behaviors can 
      result in different addresses for the same logical function:

      * **Compilation unit boundaries**: When a function is used across different compilation units, 
        the compiler may generate multiple instances at different addresses.
      
      * **Optimization passes**: Compiler optimizations such as inlining, function cloning for 
        specialization, or code deduplication may create multiple copies of a function.
      
      * **Dynamic linking**: Functions accessed through dynamic libraries may have multiple addresses 
        due to procedure linkage tables (PLT), trampolines, or lazy binding mechanisms.
      
      * **Generic instantiation**: Generic functions monomorphized with the same type parameters 
        in different compilation units may not share the same address.
      
      * **Cross-crate boundaries**: Functions exported from one crate and imported into another 
        may be referenced through different mechanisms that yield different addresses.

      Relying on function pointer equality can lead to:
      
      * Logic errors when the same function is incorrectly identified as different
      * Non-deterministic behavior across builds or platforms
      * Subtle bugs that are difficult to reproduce and diagnose
      * Violations of assumptions in security-sensitive code

   .. non_compliant_example::
      :id: non_compl_ex_FnPtrEq1
      :status: draft

      This example attempts to use function pointer equality to check if a callback 
      has been registered, which may fail across compilation boundaries.

      .. code-block:: rust

         fn default_handler() {}
         fn custom_handler() {}

         struct EventSystem {
             handler: fn(),
         }

         impl EventSystem {
             fn new() -> Self {
                 Self { handler: default_handler }
             }

             fn is_default(&self) -> bool {
                 // Non-compliant: comparing function pointers
                 self.handler as *const () == default_handler as *const ()
             }

             fn set_handler(&mut self, handler: fn()) {
                 self.handler = handler;
             }
         }

   .. non_compliant_example::
      :id: non_compl_ex_FnPtrEq2
      :status: draft

      This example uses function pointer equality to deduplicate callback registrations,
      which may fail to recognize duplicates.

      .. code-block:: rust

         struct CallbackRegistry {
             callbacks: Vec<fn(i32)>,
         }

         impl CallbackRegistry {
             fn register(&mut self, callback: fn(i32)) {
                 // Non-compliant: using pointer equality for deduplication
                 if !self.callbacks.iter().any(|&cb| cb as *const () == callback as *const ()) {
                     self.callbacks.push(callback);
                 }
             }
         }

   .. non_compliant_example::
      :id: non_compl_ex_FnPtrEq3
      :status: draft

      This example compares function pointers from different sources, which is unreliable.

      .. code-block:: rust

         #[no_mangle]
         pub extern "C" fn signal_handler() {}

         fn verify_handler(handler_ptr: extern "C" fn()) -> bool {
             // Non-compliant: comparing external function pointer
             handler_ptr as *const () == signal_handler as *const ()
         }

   .. compliant_example::
      :id: compl_ex_FnPtrEq1
      :status: draft

      Use an explicit discriminator or enum to track function identity.

      .. code-block:: rust

         #[derive(Debug, Clone, Copy, PartialEq, Eq)]
         enum HandlerType {
             Default,
             Custom,
         }

         fn default_handler() {}
         fn custom_handler() {}

         struct EventSystem {
             handler: fn(),
             handler_type: HandlerType,
         }

         impl EventSystem {
             fn new() -> Self {
                 Self { 
                     handler: default_handler,
                     handler_type: HandlerType::Default,
                 }
             }

             fn is_default(&self) -> bool {
                 // Compliant: using explicit discriminator
                 self.handler_type == HandlerType::Default
             }

             fn set_handler(&mut self, handler: fn(), handler_type: HandlerType) {
                 self.handler = handler;
                 self.handler_type = handler_type;
             }
         }

   .. compliant_example::
      :id: compl_ex_FnPtrEq2
      :status: draft

      Use unique identifiers for callbacks instead of relying on pointer equality.

      .. code-block:: rust

         use std::collections::HashSet;

         type CallbackId = u64;

         struct Callback {
             id: CallbackId,
             function: fn(i32),
         }

         struct CallbackRegistry {
             callbacks: Vec<Callback>,
             registered_ids: HashSet<CallbackId>,
         }

         impl CallbackRegistry {
             fn register(&mut self, id: CallbackId, callback: fn(i32)) -> Result<(), &'static str> {
                 // Compliant: using explicit ID for deduplication
                 if self.registered_ids.contains(&id) {
                     return Err("Callback already registered");
                 }
                 self.callbacks.push(Callback { id, function: callback });
                 self.registered_ids.insert(id);
                 Ok(())
             }
         }

   .. compliant_example::
      :id: compl_ex_FnPtrEq3
      :status: draft

      Store and reuse a single function pointer instance when identity matters.

      .. code-block:: rust

         static DEFAULT_HANDLER: fn() = default_handler;

         fn default_handler() {}

         struct EventSystem {
             handler: fn(),
         }

         impl EventSystem {
             fn new() -> Self {
                 Self { handler: DEFAULT_HANDLER }
             }

             fn is_default(&self) -> bool {
                 // Compliant: comparing against a stored canonical reference
                 std::ptr::eq(
                     self.handler as *const (),
                     DEFAULT_HANDLER as *const ()
                 )
             }

             fn reset_to_default(&mut self) {
                 self.handler = DEFAULT_HANDLER;
             }
         }