docs/TransparentAttr.rst

: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