Nothing Special   »   [go: up one dir, main page]
Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[RFC] Add #[export_ordinal(n)] attribute #3641

Open
wants to merge 7 commits into
base: master
Choose a base branch
from
Open

[RFC] Add #[export_ordinal(n)] attribute #3641

Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
a0c43e4
Initial draft for rfc: export_function_ordinals
MeguminSama May 19, 2024
b728fa9
Specify that this attribute is only for windows targets
MeguminSama May 20, 2024
5f44f70
Better wording for windows-only effects
MeguminSama May 20, 2024
d0b70b9
Rename 0000-export-function-ordinals.md to 3641-export-function-ordin…
MeguminSama May 21, 2024
e5078bd
Add RFC PR link to the RFC Document
MeguminSama May 21, 2024
60b62ff
Resolve Feedback: Unresolved Questions
MeguminSama Jun 21, 2024
73ce649
Mark export_ordinal as unsafe. Remove re-export section.
MeguminSama Aug 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Mark export_ordinal as unsafe. Remove re-export section.
  • Loading branch information
@MeguminSama
MeguminSama authored Aug 2, 2024
commit 73ce649f806090ae394bdd68eaf58c1c4a28c5c5
27 changes: 10 additions & 17 deletions text/3641-export-function-ordinals.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
# Summary
[summary]: #summary

Adding an attribute, `#[export_ordinal(n)]`, that marks the ordinal position of an exported function in a cdylib on windows targets without creating a `lib.def` file.
Adding an unsafe attribute, `#[unsafe(export_ordinal(n))]`, that marks the ordinal position of an exported function in a cdylib on windows targets without creating a `lib.def` file.

# Motivation
[motivation]: #motivation
Expand Down Expand Up @@ -45,10 +45,10 @@ Function Ordinals refer to the position of an exported function in a Dynamically

## Usage

You can specify the ordinality of an exported function using the `export_ordinal` attribute on it.
You can specify the ordinality of an exported function using the `export_ordinal` attribute on it. The attribute must be marked as unsafe.

```rs
#[export_ordinal(1)]
#[unsafe(export_ordinal(1))]
pub extern "C" fn hello() {
println!("Hello, World!");
}
Expand All @@ -68,7 +68,7 @@ If `export_ordinal` isn't provided, an unused ordinal will be assigned during co
`export_ordinal` is a new attribute for functions which has a signature similar to the following:

```rs
#[export_ordinal(n)]
#[unsafe(export_ordinal(n))]
```

`n` must be:
Expand All @@ -79,30 +79,22 @@ If `export_ordinal` isn't provided, an unused ordinal will be assigned during co

The attribute should only affect windows targets, as ordinals are not a feature of shared libraries on other targets.

The attribute must be marked as unsafe.

The attribute must be placed above an exported function like so:

```rs
#[no_mangle]
#[export_ordinal(1)]
#[unsafe(export_ordinal(1))]
pub fn hello() {}

// Also works with extern and unsafe functions

#[no_mangle]
#[export_ordinal(2)]
#[unsafe(export_ordinal(2))]
pub unsafe extern "C" fn world() {}
```

This should also work with exported bindings, such as:

```rs
#[link(name = "external_library")]
extern "C" {
#[export_ordinal(2)]
pub fn external_function();
}
```

# Drawbacks
[drawbacks]: #drawbacks

Expand All @@ -113,6 +105,8 @@ extern "C" {

This design is consistent with the [`link_ordinal`](https://doc.rust-lang.org/reference/items/external-blocks.html#the-link_ordinal-attribute) attribute already in use.

The attribute is marked as unsafe as it shares the same concerns as `export_name`, which is [unsafe as of Rust 2024 Edition](https://github.com/ehuss/edition-guide/blob/b80cba8af64a9c52d56f7081c764e5396e406f6c/src/rust-2024/unsafe-attributes.md).

Some considered alternatives are:

1. Do nothing; keep using the `.def` files with `cargo:rustc-cdylib-link-arg=/DEF`
Expand All @@ -136,7 +130,6 @@ Some unresolved questions are:
1. Can ordinals be skipped? If you specify ordinals `1, 3, 4`, should this throw an error as `2` is skipped?
2. If ordinals `1, 3` are specified, and you have another exported function, should it use `2` (the next unused ordinal) or `4` (the next in the sequence)?
3. Instead of implementing this proposal, Could the usage of the `.def` file be changed to allow other functions to stay exported, even if they aren't included in the `.def` file?
4. When [RFC3325 - Unsafe Attributes](https://rust-lang.github.io/rfcs/3325-unsafe-attributes.html) is implemented, should `link_ordinal` be marked unsafe if there is a chance of collisions?

# Future possibilities
[future-possibilities]: #future-possibilities
Expand Down