tdf#39631 - branch hints: comment, and tweak variously, also use.

Find a few million mis-predicted branches (according to callgrind)
and annotate them. Mark string acquire/release as hot, and a number of
deprecated methods as cold.

Change-Id: I678b3981794221c97f9ebb70fd0161c0fda5dceb

5 files changed, 90 insertions, 36 deletions

diff --git a/include/osl/process.h b/include/osl/process.h
index f1fec5017b60..8f25344e6c9a 100644
--- a/include/osl/process.h
+++ b/include/osl/process.h
@@ -275,7 +275,7 @@ SAL_DLLPUBLIC oslProcessError SAL_CALL osl_terminateProcess(
     @return the process handle on success, NULL in all other cases
  */
 SAL_DLLPUBLIC oslProcess SAL_CALL osl_getProcess(
-        oslProcessIdentifier Ident);
+        oslProcessIdentifier Ident) SAL_COLD;
 
 
 /** Free the specified process-handle.
diff --git a/include/osl/profile.h b/include/osl/profile.h
index c81507f131dc..fe0358260c9d 100644
--- a/include/osl/profile.h
+++ b/include/osl/profile.h
@@ -47,7 +47,7 @@ typedef void* oslProfile;
     @deprecated
 */
 SAL_DLLPUBLIC oslProfile SAL_CALL osl_openProfile(
-        rtl_uString *strProfileName, oslProfileOption Options);
+        rtl_uString *strProfileName, oslProfileOption Options) SAL_COLD;
 
 /** Deprecated API.
     Close the opened profile an flush all data to the disk.
@@ -55,14 +55,14 @@ SAL_DLLPUBLIC oslProfile SAL_CALL osl_openProfile(
     @deprecated
 */
 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_closeProfile(
-        oslProfile Profile);
+        oslProfile Profile) SAL_COLD;
 
 
 /** Deprecated API.
     @deprecated
 */
 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_flushProfile(
-        oslProfile Profile);
+        oslProfile Profile) SAL_COLD;
 /** Deprecated API.
     @deprecated
 */
@@ -70,14 +70,14 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_readProfileString(
                               oslProfile Profile,
                               const sal_Char* pszSection, const sal_Char* pszEntry,
                               sal_Char* pszString, sal_uInt32 MaxLen,
-                              const sal_Char* pszDefault);
+                              const sal_Char* pszDefault) SAL_COLD;
 /** Deprecated API.
     @deprecated
 */
 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_readProfileBool(
                             oslProfile Profile,
                             const sal_Char* pszSection, const sal_Char* pszEntry,
-                            sal_Bool Default);
+                            sal_Bool Default) SAL_COLD;
 /** Deprecated API.
     @deprecated
 */
@@ -85,7 +85,7 @@ SAL_DLLPUBLIC sal_uInt32 SAL_CALL osl_readProfileIdent(
                               oslProfile Profile,
                               const sal_Char* pszSection, const sal_Char* pszEntry,
                               sal_uInt32 FirstId, const sal_Char* Strings[],
-                              sal_uInt32 Default);
+                              sal_uInt32 Default) SAL_COLD;
 
 /** Deprecated API.
     @deprecated
@@ -93,14 +93,14 @@ SAL_DLLPUBLIC sal_uInt32 SAL_CALL osl_readProfileIdent(
 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_writeProfileString(
                                oslProfile Profile,
                                const sal_Char* pszSection, const sal_Char* pszEntry,
-                               const sal_Char* pszString);
+                               const sal_Char* pszString) SAL_COLD;
 /** Deprecated API.
     @deprecated
 */
 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_writeProfileBool(
                              oslProfile Profile,
                              const sal_Char* pszSection, const sal_Char* pszEntry,
-                             sal_Bool Value);
+                             sal_Bool Value) SAL_COLD;
 /** Deprecated API.
     @deprecated
 */
@@ -108,7 +108,7 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_writeProfileIdent(
                               oslProfile Profile,
                               const sal_Char* pszSection, const sal_Char* pszEntry,
                               sal_uInt32 FirstId, const sal_Char* Strings[],
-                              sal_uInt32 Value);
+                              sal_uInt32 Value) SAL_COLD;
 
 /** Deprecated API.
     Acquire the mutex, block if already acquired by another thread.
@@ -117,7 +117,7 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_writeProfileIdent(
 */
 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_removeProfileEntry(
                            oslProfile Profile,
-                           const sal_Char *pszSection, const sal_Char *pszEntry);
+                           const sal_Char *pszSection, const sal_Char *pszEntry) SAL_COLD;
 
 /** Deprecated API.
     Get all entries belonging to the specified section.
@@ -126,7 +126,7 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_removeProfileEntry(
 */
 SAL_DLLPUBLIC sal_uInt32 SAL_CALL osl_getProfileSectionEntries(
                             oslProfile Profile, const sal_Char *pszSection,
-                            sal_Char* pszBuffer, sal_uInt32 MaxLen);
+                            sal_Char* pszBuffer, sal_uInt32 MaxLen) SAL_COLD;
 
 /** Deprecated API.
     Get all section entries
@@ -134,7 +134,7 @@ SAL_DLLPUBLIC sal_uInt32 SAL_CALL osl_getProfileSectionEntries(
     @deprecated
 */
 SAL_DLLPUBLIC sal_uInt32 SAL_CALL osl_getProfileSections(
-        oslProfile Profile, sal_Char* pszBuffer, sal_uInt32 MaxLen);
+        oslProfile Profile, sal_Char* pszBuffer, sal_uInt32 MaxLen) SAL_COLD;
 
 #ifdef __cplusplus
 }
diff --git a/include/rtl/unload.h b/include/rtl/unload.h
index 53a5df18f515..412fad8a277b 100644
--- a/include/rtl/unload.h
+++ b/include/rtl/unload.h
@@ -68,19 +68,19 @@ typedef struct _rtl_StandardModuleCount
 
     @deprecated Do not use.
 */
-SAL_DLLPUBLIC void rtl_moduleCount_acquire(rtl_ModuleCount * that );
+SAL_DLLPUBLIC void rtl_moduleCount_acquire(rtl_ModuleCount * that ) SAL_COLD;
 
 /** Backwards-compatibility remainder of a removed library unloading feature.
 
     @deprecated Do not use.
 */
-SAL_DLLPUBLIC void rtl_moduleCount_release( rtl_ModuleCount * that );
+SAL_DLLPUBLIC void rtl_moduleCount_release( rtl_ModuleCount * that ) SAL_COLD;
 
 /** Backwards-compatibility remainder of a removed library unloading feature.
 
     @deprecated Do not use.
 */
-SAL_DLLPUBLIC sal_Bool rtl_moduleCount_canUnload( rtl_StandardModuleCount * that, TimeValue* libUnused);
+SAL_DLLPUBLIC sal_Bool rtl_moduleCount_canUnload( rtl_StandardModuleCount * that, TimeValue* libUnused) SAL_COLD;
 
 #ifdef __cplusplus
 }
diff --git a/include/rtl/ustring.h b/include/rtl/ustring.h
index 01bcd0e8202a..aa58e5814911 100644
--- a/include/rtl/ustring.h
+++ b/include/rtl/ustring.h
@@ -1193,7 +1193,7 @@ typedef struct SAL_DLLPUBLIC_RTTI _rtl_uString
     a string.
  */
 SAL_DLLPUBLIC void SAL_CALL rtl_uString_acquire(
-        rtl_uString * str ) SAL_THROW_EXTERN_C();
+        rtl_uString * str ) SAL_THROW_EXTERN_C() SAL_HOT;
 
 /** Decrement the reference count of a string.
 
@@ -1203,7 +1203,7 @@ SAL_DLLPUBLIC void SAL_CALL rtl_uString_acquire(
     a string.
  */
 SAL_DLLPUBLIC void SAL_CALL rtl_uString_release(
-        rtl_uString * str ) SAL_THROW_EXTERN_C();
+        rtl_uString * str ) SAL_THROW_EXTERN_C() SAL_HOT;
 
 /** Allocate a new string containing no characters.
 
diff --git a/include/sal/types.h b/include/sal/types.h
index 9eb45a6ced24..3dc5f71718cd 100644
--- a/include/sal/types.h
+++ b/include/sal/types.h
@@ -612,26 +612,80 @@ template< typename T1, typename T2 > inline T1 static_int_cast(T2 n) {
 #define SAL_WARN_UNUSED
 #endif
 
-#if defined(__GNUC__) && defined(__OPTIMIZE__)
-#define _SAL_BOOLEAN_EXPR(expr)                   \
- __extension__ ({                               \
-   int _sal_boolean_var_;                         \
-   if (expr)                                    \
-      _sal_boolean_var_ = 1;                      \
-   else                                         \
-      _sal_boolean_var_ = 0;                      \
-   _sal_boolean_var_;                             \
-})
-#define SAL_LIKELY(expr) (__builtin_expect (_SAL_BOOLEAN_EXPR(expr), 1))
-#define SAL_UNLIKELY(expr) (__builtin_expect (_SAL_BOOLEAN_EXPR(expr), 0))
-#define SAL_HOT __attribute__((hot))
-#define SAL_COLD __attribute__((cold))
+/// @cond INTERNAL
+
+#if defined(__GNUC__)
+// Macro to try to catch and warn on assignments inside expr.
+#    define _SAL_BOOLEAN_EXPR(expr)                   \
+     __extension__ ({                               \
+       int _sal_boolean_var_;                         \
+       if (expr)                                    \
+          _sal_boolean_var_ = 1;                      \
+       else                                         \
+          _sal_boolean_var_ = 0;                      \
+       _sal_boolean_var_;                             \
+    })
+
+/** An optimization annotation: denotes that expression is likely to be true.
+
+    Use it to annotate paths that we think are likely eg.
+    if (SAL_LIKELY(ptr != nullptr))
+       // this path is the one that is ~always taken.
+
+    @since LibreOffice 5.2
+
+    Returns: the boolean value of expr (expressed as either int 1 or 0)
+ */
+#    define SAL_LIKELY(expr) (__builtin_expect (_SAL_BOOLEAN_EXPR(expr), 1))
+
+/** An optimization annotation: denotes that expression is unlikely to be true.
+
+    Use it to annotate paths that we think are likely eg.
+    if (SAL_UNLIKELY(ptr != nullptr))
+       // this path is the one that is ~never taken.
+
+    @since LibreOffice 5.2
+
+    Returns: the boolean value of expr (expressed as either int 1 or 0)
+ */
+#    define SAL_UNLIKELY(expr) (__builtin_expect (_SAL_BOOLEAN_EXPR(expr), 0))
+
+/** An optimization annotation: tells the compiler to work harder at this code
+
+    If the SAL_HOT annotation is present on a function or a label then
+    subsequent code statements may have more aggressive compiler
+    optimization and in-lining work performed on them.
+
+    In addition this code can end up in a special section, to be
+    grouped with other frequently used code.
+
+    @since LibreOffice 5.2
+ */
+#    define SAL_HOT __attribute__((hot))
+
+/** An optimization annotation: tells the compiler to work less on this code
+
+    If the SAL_COLD annotation is present on a function or a label then
+    subsequent code statements are unlikely to be performed except in
+    exceptional circumstances, and optimizing for code-size rather
+    than performance is preferable.
+
+    In addition this code can end up in a special section, to be grouped
+    with (and away from) other more frequently used code, to improve
+    locality of reference.
+
+    @since LibreOffice 5.2
+ */
+#    define SAL_COLD __attribute__((cold))
 #else
-#define SAL_LIKELY(expr) (expr)
-#define SAL_UNLIKELY(expr) (expr)
-#define SAL_HOT
-#define SAL_COLD
+#    define SAL_LIKELY(expr) (expr)
+#    define SAL_UNLIKELY(expr) (expr)
+#    define SAL_HOT
+#    define SAL_COLD
 #endif
+
+/// @endcond
+
 #endif // INCLUDED_SAL_TYPES_H
 
 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */