<table border="1" cellspacing="0" cellpadding="8">
    <tr>
        <th>Issue</th>
        <td>
            <a href=https://github.com/llvm/llvm-project/issues/58189>58189</a>
        </td>
    </tr>

    <tr>
        <th>Summary</th>
        <td>
            Document PGO policy regarding explicit user optimization hint behavior
        </td>
    </tr>

    <tr>
      <th>Labels</th>
      <td>
            clang:documentation,
            PGO
      </td>
    </tr>

    <tr>
      <th>Assignees</th>
      <td>
      </td>
    </tr>

    <tr>
      <th>Reporter</th>
      <td>
          AaronBallman
      </td>
    </tr>
</table>

<pre>
    We document PGO at https://clang.llvm.org/docs/UsersManual.html#profile-guided-optimization but we do not document the behavior of PGO in the presence of user-provided optimization hints. It would be good to document how PGO handles conflicts between the hints the user explicitly wrote in their code and the profile they're optimizing against. For example, how do the following (non-exhaustive) hints behave: `[[likely]]` and other optimization attributes, `register` or `inline` use, `__builtin_expect`, etc.

This will help to set user expectations -- some users expect explicit optimization hints to be ignored by PGO while other users assume the hints are still honored (at least sometimes). If hints are honored, they should be clearly documented as doing so if that behavior is intentional.
</pre>
<img width="1px" height="1px" alt="" src="http://email.email.llvm.org/o/eJxtVE2PmzAQ_TVwsYKISUg4cNhtlKqHqj206nFlYAC3xka2SZr--j47H7urVkIhtmfevHlvTGO6S_2DWGfaZSLt2dePX5jwbPR-dknxlPAjnlYJPWRKnabM2AEbCHd4fXdk3WehF6Gy0U8q4cVsTS8VrYZFdtStzOzlJP8IL41mzeLZOdRi2vjXkn4k1tAoTtJYZvpIQeq4PVtypFsK2wuKrQB_CsDsHfAotXcZ-wR4s6gOaGwwpmPevFYZzTkij0J3ihxrje6VbL1DtD8TXQtGpPgvlGP0e0aM9OrCztZ4uvGSFukdMUDdaMamw_9LwneW7vSkHpgYhNTOZ-xoAqCYZkUJ_xAJQYqQ3xulzDkEJ3yvjV7R71EszssTIqsbqSgRwROWlHmyfcaj5C9Sl2R7CE-ZRz4GgPa9PMJ7KyE-uVAXgZYG6TzZkANSeEmtpKawRt-3qJeXZpHKS_0CGaj1oSxOyLdZkh-S_On6-22Ujp2lUmwkNQfNHfmHfMiLJBxbrZgz01VYdzt6CPwfPwMSjJSDNhaGN5do33kMQl-bvCIJ5-DwG_cE9Id2gZC55kJVzLQi4XzkgFJBiwoj079JuoWHJoOTzI33aWqRazEE92kCpnBYBcucYbJHAio8phiKABWB6AZ3I6V6XZbbfLtf76q0q4uuKiqRegwW1Ye3V282kOPCYJCwXUB_CBQF_UelR8l0sap-f2sH6celyVozYREu7-0VLtHP4Cc_SmgXlDiC2b5Kx7qttvtNu-735aYQDfHdpmrKot-2RZVzqjapwq5ydZg_zuN3AfXuskRe2I8DxDkaCovtIZU1zzlf53m55jl6z3ZVyftd0_RluRFNXiSbnCYh1eMjk9o6cm2WweFQYV7d6yE8x1wQRR7AF4sfja2fhDX6WSg1CZ3G3urY2F-0u7F2">