mirror of
https://github.com/apple/swift.git
synced 2025-12-21 12:14:44 +01:00
80 lines
3.1 KiB
ReStructuredText
80 lines
3.1 KiB
ReStructuredText
:orphan:
|
|
|
|
``@_transparent``
|
|
=================
|
|
|
|
Semantically, ``@_transparent`` means something like "treat this operation as
|
|
if it were a primitive operation". The name is meant to imply that both the
|
|
compiler and the compiled program will "see through" the operation to its
|
|
implementation.
|
|
|
|
This has several consequences:
|
|
|
|
- Any calls to a function marked ``@_transparent`` MUST be inlined prior to
|
|
doing dataflow-related diagnostics, even under ``-Onone``. This may be
|
|
necessary to *catch* dataflow errors.
|
|
|
|
- Because of this, a ``@_transparent`` function is implicitly inlinable, in
|
|
that changing its implementation most likely will not affect callers in
|
|
existing compiled binaries.
|
|
|
|
- Because of this, a public or ``@usableFromInline`` ``@_transparent`` function
|
|
MUST only reference public symbols, and MUST not be optimized based on
|
|
knowledge of the module it's in. [The former is caught by checks in Sema.]
|
|
|
|
- Debug info SHOULD skip over the inlined operations when single-stepping
|
|
through the calling function.
|
|
|
|
This is all that ``@_transparent`` means.
|
|
|
|
|
|
.. _transparent-attribute:
|
|
|
|
When should you use ``@_transparent``?
|
|
--------------------------------------
|
|
|
|
- Does the implementation of this function ever have to change? Then you can't
|
|
allow it to be inlined.
|
|
|
|
- Does the implementation need to call private things---either true-``private``
|
|
functions, or ``internal`` functions that might go away in the next release?
|
|
Then you can't allow it to be inlined.
|
|
|
|
- Is it okay if the function is *not* inlined? You'd just prefer that it were?
|
|
Then you should use ``@inlinable``, rather than ``@_transparent``. (If you
|
|
really need this, you can add ``@inline(__always)`` as well.)
|
|
|
|
- Is it a problem if the function is inlined even under ``-Onone``? Then you're
|
|
really in the previous case. Trust the compiler.
|
|
|
|
- Is it a problem if you can't step through the function that's been inlined?
|
|
Then you don't want ``@_transparent``; you just want ``@inline(__always)``
|
|
(and probably ``@inlinable`` as well, for cross-module inlining).
|
|
|
|
- Is it okay if the inlining happens after all the dataflow diagnostics? Then
|
|
you don't want ``@_transparent``; you just want ``@inline(__always)``.
|
|
|
|
If you made it this far, it sounds like ``@_transparent`` is the right choice.
|
|
|
|
|
|
Interaction with other annotations
|
|
----------------------------------
|
|
|
|
- As mentioned above, putting ``@_transparent`` on a function that is
|
|
``public`` or ``@usableFromInline`` exposes its body to other modules. It is
|
|
not necessary to additionally include ``@inlinable``.
|
|
|
|
- Unlike ``@inlinable``, however, ``@_transparent`` does not imply
|
|
``@usableFromInline``. It is possible to have functions marked
|
|
``@_transparent`` that are only meant for use within the current module or
|
|
even the current file.
|
|
|
|
|
|
Current implementation limitations
|
|
----------------------------------
|
|
|
|
- When compiling in non-single-frontend mode, no SIL is generated for any
|
|
functions but those in the primary file (for each frontend invocation),
|
|
including ``@inline(__always)`` and ``@_transparent`` functions, which means
|
|
they will not be inlined. This is semantically a bug. rdar://problem/15366167
|