Атрибуты генерации кода

Следующие атрибуты используются для управления генерацией кода.

Атрибут inline

Атрибут inline предлагает, следует ли разместить копию кода функции в месте вызова вместо генерации вызова функции.

Синтаксис атрибута inline:

Атрибут inline может применяться только к функциям с телами — замыканиям, async блокам, свободным функциям, ассоциированным функциям в неявной реализации или реализации трейта, и ассоциированным функциям в определении трейта, когда эти функции имеют определение по умолчанию.

Только первое использование inline на функции имеет эффект.

Атрибут inline поддерживает следующие режимы:

• #[inline] предлагает выполнить встраивание (inline expansion).
• #[inline(always)] предлагает, что встраивание должно выполняться всегда.
• #[inline(never)] предлагает, что встраивание никогда не должно выполняться.

Когда inline применяется к функции в трейте, он применяется только к коду определения по умолчанию.

Когда inline применяется к async функции или async замыканию, он применяется только к коду сгенерированной функции poll.

Атрибут inline игнорируется, если функция экспортируется внешне с no_mangle или export_name.

Атрибут cold

Атрибут cold предполагает, что функция вряд ли будет вызвана, что может помочь компилятору генерировать лучший код.

Атрибут cold использует синтаксис MetaWord.

Атрибут cold может применяться только к функциям с телами — замыканиям, async блокам, свободным функциям, ассоциированным функциям в неявной реализации или реализации трейта, и ассоциированным функциям в определении трейта, когда эти функции имеют определение по умолчанию.

Только первое использование cold на функции имеет эффект.

Когда cold применяется к функции в трейте, он применяется только к коду определения по умолчанию.

Атрибут naked

Атрибут naked предотвращает генерацию компилятором пролога и эпилога функции.

Тело функции должно состоять ровно из одного вызова макроса naked_asm!.

Для функции с атрибутом не генерируется пролог или эпилог. Ассемблерный код в блоке naked_asm! составляет полное тело naked-функции.

Атрибут naked является небезопасным атрибутом. Аннотирование функции с #[unsafe(naked)] накладывает обязательство безопасности, что тело должно учитывать соглашение о вызовах функции, соблюдать её сигнатуру и либо возвращаться, либо расходиться (т.е. не проходить через конец ассемблерного кода).

Ассемблерный код может предполагать, что стек вызовов и состояние регистров действительны при входе в соответствии с сигнатурой и соглашением о вызовах функции.

Ассемблерный код не может быть дублирован компилятором, кроме случаев мономорфизации полиморфных функций.

Линт unused_variables подавляется внутри naked-функций.

Атрибут inline не может быть применён к naked-функции.

Атрибут track_caller не может быть применён к naked-функции.

Атрибуты тестирования не могут быть применены к naked-функции.

Атрибут no_builtins

Атрибут no_builtins отключает оптимизацию определённых шаблонов кода, связанных с вызовами библиотечных функций, которые предполагаются существующими.

Атрибут no_builtins использует синтаксис MetaWord.

Атрибут no_builtins может применяться только к корню крейта.

Только первое использование атрибута no_builtins имеет эффект.

Атрибут target_feature

Атрибут target_feature может применяться к функции для включения генерации кода этой функции для определённых функций архитектуры платформы. Он использует синтаксис MetaListNameValueStr с единственным ключом enable, значение которого — строка с разделёнными запятыми именами функций для включения.

#![allow(unused)]
fn main() {
#[cfg(target_feature = "avx2")]
#[target_feature(enable = "avx2")]
fn foo_avx2() {}
}

Каждая целевая архитектура имеет набор функций, которые могут быть включены. Ошибкой указывать функцию для целевой архитектуры, для которой крейт не компилируется.

Замыкания, определённые внутри функции с аннотацией target_feature, наследуют атрибут от включающей функции.

Неопределённое поведение — вызывать функцию, которая скомпилирована с функцией, не поддерживаемой на текущей платформе, на которой выполняется код, за исключением случаев, когда платформа явно документирует, что это безопасно.

Следующие ограничения применяются, если иное не указано в правилах платформы ниже:

• Безопасные функции #[target_feature] (и замыкания, которые наследуют атрибут) могут быть безопасно вызваны только внутри вызывающего, который включает все target_feature, которые включает вызываемый. Это ограничение не применяется в небезопасном контексте.
• Безопасные функции #[target_feature] (и замыкания, которые наследуют атрибут) могут быть приведены к безопасным указателям на функции только в контекстах, которые включают все target_feature, которые включает приводимый. Это ограничение не применяется к небезопасным указателям на функции.

Неявно включённые функции включаются в это правило. Например, функция sse2 может вызывать функции, помеченные sse.

#![allow(unused)]
fn main() {
#[cfg(target_feature = "sse2")] {
#[target_feature(enable = "sse")]
fn foo_sse() {}

fn bar() {
    // Вызов `foo_sse` здесь небезопасен, так как мы должны сначала убедиться, что SSE
    // доступен, даже если `sse` включен по умолчанию на целевой
    // платформе или вручную включен как флаги компилятора.
    unsafe {
        foo_sse();
    }
}

#[target_feature(enable = "sse")]
fn bar_sse() {
    // Вызов `foo_sse` здесь безопасен.
    foo_sse();
    || foo_sse();
}

#[target_feature(enable = "sse2")]
fn bar_sse2() {
    // Вызов `foo_sse` здесь безопасен, потому что `sse2` подразумевает `sse`.
    foo_sse();
}
}
}

Функция с атрибутом #[target_feature] никогда не реализует семейство трейтов Fn, хотя замыкания, наследущие функции от включающей функции, делают это.

Атрибут #[target_feature] не разрешён в следующих местах:

• функция main
• функция panic_handler
• безопасные методы трейтов
• безопасные функции по умолчанию в трейтах

Функции, помеченные target_feature, не встраиваются в контекст, который не поддерживает данные функции. Атрибут #[inline(always)] не может использоваться с атрибутом target_feature.

Доступные функции

Ниже приведён список доступных имён функций.

x86 или x86_64

Выполнение кода с неподдерживаемыми функциями является неопределённым поведением на этой платформе. Следовательно, на этой платформе использование функций #[target_feature] следует вышеуказанным ограничениям.

aarch64

На этой платформе использование функций #[target_feature] следует вышеуказанным ограничениям.

Дополнительная документация по этим функциям может быть найдена в ARM Architecture Reference Manual или elsewhere на developer.arm.com.

loongarch

На этой платформе использование функций #[target_feature] следует вышеуказанным ограничениям.

riscv32 или riscv64

На этой платформе использование функций #[target_feature] следует вышеуказанным ограничениям.

Дополнительная документация по этим функциям может быть найдена в их соответствующих спецификациях. Многие спецификации описаны в RISC-V ISA Manual, version 20250508, или в другом руководстве, размещённом на RISC-V GitHub Account.

wasm32 или wasm64

Безопасные функции #[target_feature] могут всегда использоваться в безопасных контекстах на платформах Wasm. Невозможно вызвать неопределённое поведение через атрибут #[target_feature], потому что попытка использовать инструкции, не поддерживаемые движком Wasm, завершится ошибкой во время загрузки без риска быть интерпретированной способом, отличным от ожидаемого компилятором.

Дополнительная информация

См. опцию условной компиляции [target_feature] для выборочного включения или отключения компиляции кода на основе настроек времени компиляции. Обратите внимание, что эта опция не зависит от атрибута target_feature и управляется только функциями, включёнными для всего крейта.

См. макросы is_x86_feature_detected или is_aarch64_feature_detected в стандартной библиотеке для обнаружения функций во время выполнения на этих платформах.

Атрибут track_caller

Атрибут track_caller может применяться к любой функции с ABI "Rust" за исключением точки входа fn main.

При применении к функциям и методам в объявлениях трейтов атрибут применяется ко всем реализациям. Если трейт предоставляет реализацию по умолчанию с атрибутом, то атрибут также применяется к переопределяющим реализациям.

При применении к функции в блоке extern атрибут также должен быть применён к любым связанным реализациям, иначе результат — неопределённое поведение. При применении к функции, которая становится доступной для блока extern, объявление в блоке extern также должно иметь атрибут, иначе результат — неопределённое поведение.

Поведение

Применение атрибута к функции f позволяет коду внутри f получить подсказку о Location “самого верхнего” отслеживаемого вызова, который привёл к вызову f. В момент наблюдения реализация ведёт себя так, как если бы она поднималась по стеку от фрейма f, чтобы найти ближайший фрейм без атрибута функции outer, и возвращает Location отслеживаемого вызова в outer.

#![allow(unused)]
fn main() {
#[track_caller]
fn f() {
    println!("{}", std::panic::Location::caller());
}
}

Примеры

Когда f вызывается напрямую calls_f, код в f наблюдает место вызова внутри calls_f:

#![allow(unused)]
fn main() {
#[track_caller]
fn f() {
    println!("{}", std::panic::Location::caller());
}
fn calls_f() {
    f(); // <-- f() печатает это местоположение
}
}

Когда f вызывается другой атрибутированной функцией g, которая в свою очередь вызывается calls_g, код в обоих f и g наблюдает место вызова g внутри calls_g:

#![allow(unused)]
fn main() {
#[track_caller]
fn f() {
    println!("{}", std::panic::Location::caller());
}
#[track_caller]
fn g() {
    println!("{}", std::panic::Location::caller());
    f();
}

fn calls_g() {
    g(); // <-- g() печатает это местоположение дважды, один раз сама и один раз из f()
}
}

Когда g вызывается другой атрибутированной функцией h, которая в свою очередь вызывается calls_h, весь код в f, g и h наблюдает место вызова h внутри calls_h:

#![allow(unused)]
fn main() {
#[track_caller]
fn f() {
    println!("{}", std::panic::Location::caller());
}
#[track_caller]
fn g() {
    println!("{}", std::panic::Location::caller());
    f();
}
#[track_caller]
fn h() {
    println!("{}", std::panic::Location::caller());
    g();
}

fn calls_h() {
    h(); // <-- печатает это местоположение трижды, один раз сама, один раз из g(), один раз из f()
}
}

И так далее.

Ограничения

Эта информация является подсказкой, и реализации не обязаны её сохранять.

В частности, приведение функции с #[track_caller] к указателю на функцию создаёт обёртку (shim), которая для наблюдателей появляется так, как если бы она была вызвана в месте определения атрибутированной функции, теряя фактическую информацию о вызывающем при виртуальных вызовах. Распространённым примером этого приведения является создание объекта трейта, методы которого атрибутированы.

Атрибут instruction_set

Атрибут instruction_set указывает набор инструкций, который функция будет использовать во время генерации кода. Это позволяет смешивать более одного набора инструкций в одной программе.

Атрибут instruction_set использует синтаксис MetaListPaths для указания единственного пути, состоящего из имени семейства архитектуры и имени набора инструкций.

Атрибут instruction_set может применяться только к функциям с телами — замыканиям, async блокам, свободным функциям, ассоциированным функциям в неявной реализации или реализации трейта, и ассоциированным функциям в определении трейта, когда эти функции имеют определение по умолчанию.

Атрибут instruction_set может использоваться только один раз на функции.

Атрибут instruction_set может использоваться только с целью, которая поддерживает данное значение.

Когда используется атрибут instruction_set, любая встроенная ассемблерная вставка в функции должна использовать указанный набор инструкций вместо целевого по умолчанию.

instruction_set на ARM

При нацеливании на архитектуры ARMv4T и ARMv5te поддерживаемые значения для instruction_set:

• arm::a32 — Генерировать функцию как код A32 “ARM”.
• arm::t32 — Генерировать функцию как код T32 “Thumb”.

Если адрес функции берётся как указатель на функцию, младший бит адреса будет зависеть от выбранного набора инструкций:

• Для arm::a32 (“ARM”) он будет 0.
• Для arm::t32 (“Thumb”) он будет 1.