Skip to content

[NFC] Re-alphabetize underscored attributes reference #60558

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

Merged
merged 1 commit into from
Aug 16, 2022
Merged

[NFC] Re-alphabetize underscored attributes reference #60558

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
99 changes: 48 additions & 51 deletions docs/ReferenceGuides/UnderscoredAttributes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,10 @@ the Swift ABI. This attribute is intended for the SIMD types in the standard
library which use it to increase the alignment of their internal storage to at
least 16 bytes.

## `@_alwaysEmitConformanceMetadata`

Forces conformances of the attributed protocol to always have their Type Metadata get emitted into the binary and prevents it from being optimized away or stripped by the linker.

## `@_alwaysEmitIntoClient`

Forces the body of a function to be emitted into client code.
Expand All @@ -39,6 +43,14 @@ Most notably, default argument expressions are implicitly
`@_alwaysEmitIntoClient`, which means that adding a default argument to a
function which did not have one previously does not break ABI.

## `@_assemblyVision`

Forces emission of assembly vision remarks for a function or method, showing
where various runtime calls and performance impacting hazards are in the code
at source level after optimization.

Adding this attribute to a type leads to remarks being emitted for all methods.

## `@_backDeploy(before: ...)`

Causes the body of a function to be emitted into the module interface to be
Expand All @@ -53,14 +65,6 @@ client is called instead.
For more details, see the [pitch thread](https://forums.swift.org/t/pitch-function-back-deployment/55769/)
in the forums.

## `@_assemblyVision`

Forces emission of assembly vision remarks for a function or method, showing
where various runtime calls and performance impacting hazards are in the code
at source level after optimization.

Adding this attribute to a type leads to remarks being emitted for all methods.

## `@_borrowed`

Indicates that the [conservative access pattern](/docs/Lexicon.md#access-pattern)
Expand Down Expand Up @@ -482,6 +486,19 @@ Fun fact: Rust has a very similar concept called
including one called `Send`,
which inspired the design of `Sendable`.

## `@_noAllocation`, `@_noLocks`

These attributes are performance annotations. If a function is annotated with
such an attribute, the compiler issues a diagnostic message if the function
calls a runtime function which allocates memory or locks, respectively.
The `@_noLocks` attribute implies `@_noAllocation` because a memory allocation
also locks.

## `@_noImplicitCopy`

Marks a var decl as a variable that must be copied explicitly using the builtin
function Builtin.copy.

## `@_nonEphemeral`

Marks a function parameter that cannot accept a temporary pointer produced from
Expand Down Expand Up @@ -755,6 +772,14 @@ Clients can access SPI by marking the import as `@_spi(spiName) import Module`.
This design makes it easy to find out which clients are using certain SPIs by
doing a textual search.

## `@_spi_available(platform, version)`

Like `@available`, this attribute indicates a decl is available only as an SPI.
This implies several behavioral changes comparing to regular `@available`:
1. Type checker diagnoses when a client accidently exposes such a symbol in library APIs.
2. When emitting public interfaces, `@_spi_available` is printed as `@available(platform, unavailable)`.
3. ClangImporter imports ObjC macros `SPI_AVAILABLE` and `__SPI_AVAILABLE` to this attribute.

## `@_staticInitializeObjCMetadata`

Indicates that a static initializer should be emitted to register the
Expand Down Expand Up @@ -789,19 +814,11 @@ A type eraser has the following restrictions:
This feature was designed to be used for compiler-driven type erasure for
dynamic replacement of functions with an opaque return type.

## `@_weakLinked`

Allows a declaration to be weakly-referenced, i.e., any references emitted by
client modules to the declaration's symbol will have weak linkage. This means
that client code will compile without the guarantee that the symbol will be
available at runtime. This requires a dynamic safety check (such as using
`dlsym (3)`); otherwise, accessing the symbol when it is unavailable leads
to a runtime crash.
## `@_unavailableFromAsync`

This is an unsafe alternative to using `@available`, which is statically checked.
If the availability of a library symbol is newer than the deployment target of
the client, the symbol will be weakly linked, but checking for `@available` and
`#(un)available` ensures that a symbol is not accessed when it is unavailable.
Marks a synchronous API as being unavailable from asynchronous contexts. Direct
usage of annotated API from asynchronous contexts will result in a warning from
the compiler.

## `@_unsafeMainActor`, `@_unsafeSendable`

Expand All @@ -812,38 +829,23 @@ within Swift 5 code that has adopted concurrency, but non-`@MainActor`
See the forum post on [Concurrency in Swift 5 and 6](https://forums.swift.org/t/concurrency-in-swift-5-and-6/49337)
for more details.

## `@_noImplicitCopy`

Marks a var decl as a variable that must be copied explicitly using the builtin
function Builtin.copy.

## `@_noAllocation`, `@_noLocks`

These attributes are performance annotations. If a function is annotated with
such an attribute, the compiler issues a diagnostic message if the function
calls a runtime function which allocates memory or locks, respectively.
The `@_noLocks` attribute implies `@_noAllocation` because a memory allocation
also locks.

## `@_unavailableFromAsync`

Marks a synchronous API as being unavailable from asynchronous contexts. Direct
usage of annotated API from asynchronous contexts will result in a warning from
the compiler.

## `@_unsafeInheritExecutor`

This `async` function uses the pre-SE-0338 semantics of unsafely inheriting the caller's executor. This is an underscored feature because the right way of inheriting an executor is to pass in the required executor and switch to it. Unfortunately, there are functions in the standard library which need to inherit their caller's executor but cannot change their ABI because they were not defined as `@_alwaysEmitIntoClient` in the initial release.

## `@_weakLinked`

## `@_spi_available(platform, version)`

Like `@available`, this attribute indicates a decl is available only as an SPI.
This implies several behavioral changes comparing to regular `@available`:
1. Type checker diagnoses when a client accidently exposes such a symbol in library APIs.
2. When emitting public interfaces, `@_spi_available` is printed as `@available(platform, unavailable)`.
3. ClangImporter imports ObjC macros `SPI_AVAILABLE` and `__SPI_AVAILABLE` to this attribute.
Allows a declaration to be weakly-referenced, i.e., any references emitted by
client modules to the declaration's symbol will have weak linkage. This means
that client code will compile without the guarantee that the symbol will be
available at runtime. This requires a dynamic safety check (such as using
`dlsym (3)`); otherwise, accessing the symbol when it is unavailable leads
to a runtime crash.

This is an unsafe alternative to using `@available`, which is statically checked.
If the availability of a library symbol is newer than the deployment target of
the client, the symbol will be weakly linked, but checking for `@available` and
`#(un)available` ensures that a symbol is not accessed when it is unavailable.

## `_local`

Expand All @@ -852,8 +854,3 @@ the distributed actor isolation checks. This is used for things like `whenLocal`
where the actor passed to the closure is known-to-be-local, and similarly a
`self` of obtained from an _isolated_ function inside a distributed actor is
also guaranteed to be local by construction.


## `@_alwaysEmitConformanceMetadata`

Forces conformances of the attributed protocol to always have their Type Metadata get emitted into the binary and prevents it from being optimized away or stripped by the linker.