libphobos/libdruntime/core/builtins.d

   1 /**********************************************
   2 To provide access to features that would be otherwise counterproductive or
   3 difficult to implement, compilers provide an interface consisting of a set
   4 of builtins (also called intrinsics) which can be called like normal functions.
   5
   6 This module exposes builtins both common to all D compilers
   7 (those provided by the frontend) and specific to the host compiler i.e. those
   8 specific to either LLVM or GCC (`ldc.intrinsics` and `gcc.builtins` are publicly imported, respectively).
   9 Host-specific intrinsics cannot be reliably listed here, however listings can be found
  10 at the documentation for the relevant backends, i.e.
  11 $(LINK2 https://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html, GCC) and
  12 $(LINK2 https://llvm.org/docs/LangRef.html, LLVM). It should be noted that not all
  13 builtins listed are necessarily supported by the host compiler, please file a bug
  14 if this is the case for your workload.
  15
  16 Use of this module reduces the amount of conditional compilation needed
  17 to use a given builtin. For example, to write a target independent function
  18 that uses prefetching we can write the following:
  19 ---
  20 float usePrefetch(float[] x)
  21 {
  22     // There is only one import statement required rather than two (versioned) imports
  23     import core.builtins;
  24     version (GNU)
  25         __builtin_prefetch(x.ptr);
  26     version (LDC)
  27         /+
  28             For the curious: 0, 3, 1 mean `x` will only be read-from (0), it will be used
  29             very often (3), and it should be fetched to the data-cache (1).
  30         +/
  31         llvm_prefetch(x.ptr, 0, 3, 1);
  32     const doMath = blahBlahBlah;
  33     return doMath;
  34 }
  35 ---
  36
  37
  38 Copyright: Copyright © 2021, The D Language Foundation
  39 License:   $(LINK2 http://www.boost.org/LICENSE_1_0.txt, Boost License 1.0)
  40 Authors:   Walter Bright
  41 Source:    $(DRUNTIMESRC core/builtins.d)
  42 */
  43
  44 module core.builtins;
  45
  46 version (GNU)
  47     public import gcc.builtins;
  48
  49 version (LDC)
  50     public import ldc.intrinsics;
  51
  52 /// Writes `s` to `stderr` during CTFE (does nothing at runtime).
  53 void __ctfeWrite(scope const(char)[] s) @nogc @safe pure nothrow {}
  54
  55 version (GNU)
  56 {
  57     /// https://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html#index-_005f_005fbuiltin_005fexpect
  58     alias expect = __builtin_expect;
  59     /// https://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html#index-_005f_005fbuiltin_005ftrap
  60     alias trap = __builtin_trap;
  61 }
  62 else version (LDC)
  63 {
  64     /// https://llvm.org/docs/LangRef.html#llvm-expect-intrinsic
  65     alias expect = llvm_expect;
  66     debug
  67         /// https://llvm.org/docs/LangRef.html#llvm-debugtrap-intrinsic
  68         alias trap = llvm_debugtrap;
  69     else
  70         /// https://llvm.org/docs/LangRef.html#llvm-trap-intrinsic
  71         alias trap = llvm_trap;
  72 }
  73 else version (DigitalMars)
  74 {
  75     pragma(inline, true)
  76     T expect(T)(T val, T expected) if (__traits(isIntegral, T))
  77     {
  78         return val;
  79     }
  80
  81     /// Execute target dependent trap instruction, if supported.
  82     /// Otherwise, abort execution.
  83     pragma(inline, true)
  84     void trap()
  85     {
  86         debug
  87         {
  88             version(D_InlineAsm_X86)
  89                 asm nothrow @nogc pure @trusted { int 3; }
  90         }
  91         assert(0);
  92     }
  93 }
  94
  95 /// Provide static branch and value hints for the LDC/GDC compilers.
  96 /// DMD ignores these hints.
  97 pragma(inline, true) bool likely()(bool b)   { return !!expect(b, true);  }
  98 /// ditto
  99 pragma(inline, true) bool unlikely()(bool b) { return !!expect(b, false); }
 100
 101 ///
 102 @nogc nothrow pure @safe unittest
 103 {
 104     int x = 12;
 105
 106     expect(x, 12);
 107
 108     if (likely(x > 0))
 109     {
 110         // ...
 111     }
 112     else if (unlikely(x == int.min))
 113     {
 114         // ...
 115     }
 116 }