: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 inherently "fragile", in
  that changing its implementation most likely will not affect callers in
  existing compiled binaries.

- Because of this, a ``@_transparent`` function MUST only reference public
  symbols, and MUST not be optimized based on knowledge of the module it's in.
  [This is not currently implemented or enforced.]

- 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. (Well, you can for now for
  ``internal``, but it'll break once we have libraries that aren't shipped with
  apps.)

- Is it okay if the function is *not* inlined? You'd just prefer that it were?
  Then you should use [the attribute we haven't designed yet], rather than
  ``@_transparent``. (If you really need this right now, try
  ``@inline(__always)``.)

- 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)``.

- 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.


Current implementation limitations
----------------------------------

- We don't have a general ``@inlineable`` attribute for functions that *allows*
  inlining but doesn't *require* it.

- As mentioned above, we don't enforce that inlineable things only refer to
  public symbols. rdar://problem/22666548

- We also don't keep from optimizing based on implementation details of the
  current module. [No Radar yet.]

- If you have local types in your inlineable function, serialization falls
  over. (As does textual SIL.) rdar://problem/17631278

- When compiling in non-single-frontend mode, SIL is generated for each file
  but then thrown away in the "merge modules" step. So none of it is inlineable
  for external callers. (Currently, ``-whole-module-optimization`` is
  equivalent to ``-force-single-frontend-invocation``.) rdar://problem/18913977

- Similarly, 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. This is
  semantically a bug. rdar://problem/15366167