averello/swift-mirror
1
0
Fork 0
mirror of https://github.com/apple/swift.git synced 2025-12-14 20:36:38 +01:00
Code Issues Packages Projects Releases Wiki Activity

[Gardening] De-RST TransparentAttr

Browse Source
This commit is contained in:
Robert Widmann
2020-05-02 02:17:49 -07:00
parent 309f86433d
commit 00b46f3653
4 changed files with 77 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/LibraryEvolution.rst
View File

@@ -210,7 +210,7 @@ any future use of the function must take this into account.
Although they are not a supported feature for arbitrary libraries at this time,
public `transparent`_ functions are implicitly marked ``@inlinable``.
.. _transparent: https://github.com/apple/swift/blob/master/docs/TransparentAttr.rst
.. _transparent: https://github.com/apple/swift/blob/master/docs/TransparentAttr.md
Restrictions on Inlinable Functions

2
docs/StandardLibraryProgrammersManual.md
View File

@@ -180,7 +180,7 @@ let theBits = unsafeBitCast(&x, ...)
Should only be used if necessary. This has the effect of forcing inlining to occur before any dataflow analyses take place. Unless you specifically need this behavior, use `@_inline(__always)` or some other mechanism. Its primary purpose is to force the compiler's static checks to peer into the body for diagnostic purposes.
Use of this attribute imposes limitations on what can be in the body. For more details, refer to the [documentation](https://github.com/apple/swift/blob/master/docs/TransparentAttr.rst).
Use of this attribute imposes limitations on what can be in the body. For more details, refer to the [documentation](https://github.com/apple/swift/blob/master/docs/TransparentAttr.md).
#### `@unsafe_no_objc_tagged_pointer`

75
docs/TransparentAttr.md Normal file
View File

@@ -0,0 +1,75 @@
`@_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.
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

79
docs/TransparentAttr.rst
View File

@@ -1,79 +0,0 @@
: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