include/sal/types.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_SAL_TYPES_H
  21 #define INCLUDED_SAL_TYPES_H
  22
  23 #include "sal/config.h"
  24
  25 #include <stddef.h>
  26
  27 #include "sal/macros.h"
  28 #include "sal/typesizes.h"
  29
  30 #if defined LIBO_INTERNAL_ONLY
  31 #include "config_global.h"
  32 #endif
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 typedef unsigned char sal_Bool;
  39 #   define sal_False ((sal_Bool)0)
  40 #   define sal_True  ((sal_Bool)1)
  41
  42 /* char is assumed to always be 1 byte long */
  43 typedef signed char         sal_Int8;
  44 typedef unsigned char       sal_uInt8;
  45
  46 #if SAL_TYPES_SIZEOFSHORT == 2
  47     typedef signed short      sal_Int16;
  48     typedef unsigned short    sal_uInt16;
  49 #else
  50      #error "Could not find 16-bit type, add support for your architecture"
  51 #endif
  52
  53 #if SAL_TYPES_SIZEOFLONG == 4
  54     typedef signed long       sal_Int32;
  55     typedef unsigned long     sal_uInt32;
  56     #define SAL_PRIdINT32 "ld"
  57     #define SAL_PRIuUINT32 "lu"
  58     #define SAL_PRIxUINT32 "lx"
  59     #define SAL_PRIXUINT32 "lX"
  60 #elif SAL_TYPES_SIZEOFINT == 4
  61     typedef signed int        sal_Int32;
  62     typedef unsigned int      sal_uInt32;
  63     #define SAL_PRIdINT32 "d"
  64     #define SAL_PRIuUINT32 "u"
  65     #define SAL_PRIxUINT32 "x"
  66     #define SAL_PRIXUINT32 "X"
  67 #else
  68      #error "Could not find 32-bit type, add support for your architecture"
  69 #endif
  70
  71 #ifdef _MSC_VER
  72     typedef __int64                  sal_Int64;
  73     typedef unsigned __int64         sal_uInt64;
  74
  75     /*  The following are macros that will add the 64 bit constant suffix. */
  76     #define SAL_CONST_INT64(x)       x##i64
  77     #define SAL_CONST_UINT64(x)      x##ui64
  78
  79     #define SAL_PRIdINT64 "I64d"
  80     #define SAL_PRIuUINT64 "I64u"
  81     #define SAL_PRIxUINT64 "I64x"
  82     #define SAL_PRIXUINT64 "I64X"
  83 #elif defined (__GNUC__)
  84     #if SAL_TYPES_SIZEOFLONG == 8
  85         typedef signed long int         sal_Int64;
  86         typedef unsigned long int       sal_uInt64;
  87
  88
  89         /*  The following are macros that will add the 64 bit constant suffix. */
  90         #define SAL_CONST_INT64(x)       x##l
  91         #define SAL_CONST_UINT64(x)      x##ul
  92
  93         #define SAL_PRIdINT64 "ld"
  94         #define SAL_PRIuUINT64 "lu"
  95         #define SAL_PRIxUINT64 "lx"
  96         #define SAL_PRIXUINT64 "lX"
  97     #elif SAL_TYPES_SIZEOFLONGLONG == 8
  98         typedef signed long long    sal_Int64;
  99         typedef unsigned long long  sal_uInt64;
 100
 101         /*  The following are macros that will add the 64 bit constant suffix. */
 102         #define SAL_CONST_INT64(x)       x##ll
 103         #define SAL_CONST_UINT64(x)      x##ull
 104
 105         #define SAL_PRIdINT64 "lld"
 106         #define SAL_PRIuUINT64 "llu"
 107         #define SAL_PRIxUINT64 "llx"
 108         #define SAL_PRIXUINT64 "llX"
 109     #else
 110         #error "Could not find 64-bit type, add support for your architecture"
 111     #endif
 112 #else
 113     #error "Please define the 64-bit types for your architecture/compiler in include/sal/types.h"
 114 #endif
 115
 116 /** A legacy synonym for `char`.
 117
 118     @deprecated use plain `char` instead.
 119 */
 120 typedef char sal_Char;
 121
 122 /** A legacy synonym for `signed char`.
 123
 124     @deprecated use plain `signed char` instead.
 125 */
 126 typedef signed char sal_sChar;
 127
 128 /** A legacy synonym for `unsigned char`.
 129
 130     @deprecated use plain `unsigned char` instead.
 131 */
 132 typedef unsigned char sal_uChar;
 133
 134 #if defined LIBO_INTERNAL_ONLY && defined __cplusplus
 135     #define SAL_UNICODE_NOTEQUAL_WCHAR_T
 136     typedef char16_t sal_Unicode;
 137 #elif defined(_WIN32)
 138     typedef wchar_t sal_Unicode;
 139 #else
 140     #define SAL_UNICODE_NOTEQUAL_WCHAR_T
 141     typedef sal_uInt16 sal_Unicode;
 142 #endif
 143
 144 typedef void *                   sal_Handle;
 145
 146 /* sal_Size should currently be the native width of the platform */
 147 #if SAL_TYPES_SIZEOFPOINTER == 4
 148     typedef sal_uInt32          sal_Size;
 149     typedef sal_Int32           sal_sSize;
 150 #elif SAL_TYPES_SIZEOFPOINTER == 8
 151     typedef sal_uInt64          sal_Size;
 152     typedef sal_Int64           sal_sSize;
 153 #else
 154     #error "Please make sure SAL_TYPES_SIZEOFPOINTER is defined for your architecture/compiler"
 155 #endif
 156
 157 /* sal_PtrDiff holds the result of a pointer subtraction */
 158 #if SAL_TYPES_SIZEOFPOINTER == 4
 159     typedef sal_Int32           sal_PtrDiff;
 160 #elif SAL_TYPES_SIZEOFPOINTER == 8
 161     typedef sal_Int64           sal_PtrDiff;
 162 #else
 163     #error "Please make sure SAL_TYPES_SIZEOFPOINTER is defined for your architecture/compiler"
 164 #endif
 165
 166 /* printf-style conversion specification length modifiers for size_t and
 167    ptrdiff_t (most platforms support C99, MSC has its own extension) */
 168 #if defined(_MSC_VER)
 169     #define SAL_PRI_SIZET "I"
 170     #define SAL_PRI_PTRDIFFT "I"
 171 #else
 172     #define SAL_PRI_SIZET "z"
 173     #define SAL_PRI_PTRDIFFT "t"
 174 #endif
 175
 176 /* sal_IntPtr, sal_uIntPtr are integer types designed to hold pointers so that any valid
 177  * pointer to void can be converted to this type and back to a pointer to void and the
 178  * result will compare to the original pointer */
 179 #if SAL_TYPES_SIZEOFPOINTER == 4
 180     typedef sal_Int32           sal_IntPtr;
 181     typedef sal_uInt32          sal_uIntPtr;
 182     #define SAL_PRIdINTPTR SAL_PRIdINT32
 183     #define SAL_PRIuUINTPTR SAL_PRIuUINT32
 184     #define SAL_PRIxUINTPTR SAL_PRIxUINT32
 185     #define SAL_PRIXUINTPTR SAL_PRIXUINT32
 186 #elif SAL_TYPES_SIZEOFPOINTER == 8
 187     typedef sal_Int64           sal_IntPtr;
 188     typedef sal_uInt64          sal_uIntPtr;
 189     #define SAL_PRIdINTPTR SAL_PRIdINT64
 190     #define SAL_PRIuUINTPTR SAL_PRIuUINT64
 191     #define SAL_PRIxUINTPTR SAL_PRIxUINT64
 192     #define SAL_PRIXUINTPTR SAL_PRIXUINT64
 193 #else
 194     #error "Please make sure SAL_TYPES_SIZEOFPOINTER is defined for your architecture/compiler"
 195 #endif
 196
 197 /* The following SAL_MIN_INTn defines codify the assumption that the signed
 198  * sal_Int types use two's complement representation.  Defining them as
 199  * "-0x7F... - 1" instead of as "-0x80..." prevents warnings about applying the
 200  * unary minus operator to unsigned quantities.
 201  */
 202 #define SAL_MIN_INT8          ((sal_Int8)   (-0x7F - 1))
 203 #define SAL_MAX_INT8          ((sal_Int8)   0x7F)
 204 #define SAL_MAX_UINT8         ((sal_uInt8)  0xFF)
 205 #define SAL_MIN_INT16         ((sal_Int16)  (-0x7FFF - 1))
 206 #define SAL_MAX_INT16         ((sal_Int16)  0x7FFF)
 207 #define SAL_MAX_UINT16        ((sal_uInt16) 0xFFFF)
 208 #define SAL_MIN_INT32         ((sal_Int32)  (-0x7FFFFFFF - 1))
 209 #define SAL_MAX_INT32         ((sal_Int32)  0x7FFFFFFF)
 210 #define SAL_MAX_UINT32        ((sal_uInt32) 0xFFFFFFFF)
 211 #define SAL_MIN_INT64         ((sal_Int64)  (SAL_CONST_INT64(-0x7FFFFFFFFFFFFFFF) - 1))
 212 #define SAL_MAX_INT64         ((sal_Int64)  SAL_CONST_INT64(0x7FFFFFFFFFFFFFFF))
 213 #define SAL_MAX_UINT64        ((sal_uInt64) SAL_CONST_UINT64(0xFFFFFFFFFFFFFFFF))
 214
 215 #if SAL_TYPES_SIZEOFPOINTER == 4
 216 #define SAL_MAX_SSIZE       SAL_MAX_INT32
 217 #define SAL_MAX_SIZE        SAL_MAX_UINT32
 218 #elif SAL_TYPES_SIZEOFPOINTER == 8
 219 #define SAL_MAX_SSIZE       SAL_MAX_INT64
 220 #define SAL_MAX_SIZE        SAL_MAX_UINT64
 221 #endif
 222
 223 #define SAL_MAX_ENUM 0x7fffffff
 224
 225 #if defined(_MSC_VER)
 226 #   define SAL_DLLPUBLIC_EXPORT    __declspec(dllexport)
 227 #   define SAL_JNI_EXPORT          __declspec(dllexport)
 228 #   define SAL_DLLPUBLIC_IMPORT    __declspec(dllimport)
 229 #   define SAL_DLLPRIVATE
 230 #   define SAL_DLLPUBLIC_TEMPLATE
 231 #   define SAL_DLLPUBLIC_RTTI
 232 #   define SAL_CALL         __cdecl
 233 #elif defined SAL_UNX
 234 #   if defined(__GNUC__)
 235 #     if defined(DISABLE_DYNLOADING)
 236 #       define SAL_DLLPUBLIC_EXPORT  __attribute__ ((visibility("hidden")))
 237 #       define SAL_JNI_EXPORT        __attribute__ ((visibility("default")))
 238 #       define SAL_DLLPUBLIC_IMPORT  __attribute__ ((visibility("hidden")))
 239 #       define SAL_DLLPRIVATE        __attribute__ ((visibility("hidden")))
 240 #       define SAL_DLLPUBLIC_TEMPLATE __attribute__ ((visibility("hidden")))
 241 #       define SAL_DLLPUBLIC_RTTI
 242 #     else
 243 #       define SAL_DLLPUBLIC_EXPORT  __attribute__ ((visibility("default")))
 244 #       define SAL_JNI_EXPORT        __attribute__ ((visibility("default")))
 245 #       define SAL_DLLPUBLIC_IMPORT  __attribute__ ((visibility("default")))
 246 #       define SAL_DLLPRIVATE        __attribute__ ((visibility("hidden")))
 247 #       define SAL_DLLPUBLIC_TEMPLATE __attribute__ ((visibility("default")))
 248 #       if defined __clang__
 249 #         if __has_attribute(type_visibility)
 250 #           define SAL_DLLPUBLIC_RTTI  __attribute__ ((type_visibility("default")))
 251 #         else
 252 #           define SAL_DLLPUBLIC_RTTI  __attribute__ ((visibility("default")))
 253 #         endif
 254 #       else
 255 #         define SAL_DLLPUBLIC_RTTI
 256 #       endif
 257 #     endif
 258 #   else
 259 #     define SAL_DLLPUBLIC_EXPORT
 260 #     define SAL_JNI_EXPORT
 261 #     define SAL_DLLPUBLIC_IMPORT
 262 #     define SAL_DLLPRIVATE
 263 #     define SAL_DLLPUBLIC_TEMPLATE
 264 #     define SAL_DLLPUBLIC_RTTI
 265 #   endif
 266 #   define SAL_CALL
 267 #else
 268 #   error("unknown platform")
 269 #endif
 270
 271 /**
 272    Exporting the symbols necessary for exception handling on GCC.
 273
 274    These macros are used for inline declarations of exception classes, as in
 275    rtl/malformeduriexception.hxx.
 276 */
 277 #if defined(__GNUC__)
 278 #   if defined(DISABLE_DYNLOADING)
 279 #      define SAL_EXCEPTION_DLLPUBLIC_EXPORT __attribute__((visibility("default")))
 280 #    else
 281 #      define SAL_EXCEPTION_DLLPUBLIC_EXPORT SAL_DLLPUBLIC_EXPORT
 282 #    endif
 283 #    define SAL_EXCEPTION_DLLPRIVATE SAL_DLLPRIVATE
 284 #else
 285 #    define SAL_EXCEPTION_DLLPUBLIC_EXPORT
 286 #    define SAL_EXCEPTION_DLLPRIVATE
 287 #endif
 288
 289 /** Use this as markup for functions and methods whose return value must be
 290     checked.
 291
 292     Compilers that support a construct of this nature will emit a compile
 293     time warning on unchecked return value.
 294 */
 295 #if defined LIBO_INTERNAL_ONLY && defined __cplusplus
 296 #define SAL_WARN_UNUSED_RESULT [[nodiscard]]
 297 #elif (defined __GNUC__ \
 298      && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 1))) \
 299     || defined __clang__
 300 #   define SAL_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
 301 #else
 302 #   define SAL_WARN_UNUSED_RESULT
 303 #endif
 304
 305 /** Use this for pure virtual classes, e.g. class SAL_NO_VTABLE Foo { ...
 306     This hinders the compiler from setting a generic vtable stating that
 307     a pure virtual function was called and thus slightly reduces code size.
 308 */
 309 #ifdef _MSC_VER
 310 #   define SAL_NO_VTABLE __declspec(novtable)
 311 #else
 312 #   define SAL_NO_VTABLE
 313 #endif
 314
 315 #ifdef _WIN32
 316 #   pragma pack(push, 8)
 317 #endif
 318
 319 /** This is the binary specification of a SAL sequence.
 320 */
 321 typedef struct _sal_Sequence
 322 {
 323     /** reference count of sequence<br>
 324     */
 325     sal_Int32           nRefCount;
 326     /** element count<br>
 327     */
 328     sal_Int32           nElements;
 329     /** elements array<br>
 330     */
 331     char                elements[1];
 332 } sal_Sequence;
 333
 334 #define SAL_SEQUENCE_HEADER_SIZE ((sal_Size) offsetof(sal_Sequence,elements))
 335
 336 #if defined( _WIN32)
 337 #pragma pack(pop)
 338 #endif
 339
 340 #if defined __cplusplus
 341
 342 /** Nothrow specification for C functions.
 343
 344     This is a macro so it can expand to nothing in C code.
 345 */
 346 #define SAL_THROW_EXTERN_C() throw ()
 347
 348 /** To markup destructors that coverity warns might throw exceptions
 349     which won't throw in practice, or where std::terminate is
 350     an acceptable response if they do
 351 */
 352 #if defined(LIBO_INTERNAL_ONLY) && defined(__COVERITY__)
 353 #   define COVERITY_NOEXCEPT_FALSE noexcept(false)
 354 #else
 355 #   define COVERITY_NOEXCEPT_FALSE
 356 #endif
 357
 358 #else
 359
 360 #define SAL_THROW_EXTERN_C()
 361
 362 #endif
 363
 364 #ifdef __cplusplus
 365 }
 366 #endif /* __cplusplus */
 367
 368 #ifdef __cplusplus
 369
 370 enum __sal_NoAcquire
 371 {
 372     /** definition of a no acquire enum for ctors
 373     */
 374     SAL_NO_ACQUIRE
 375 };
 376
 377 namespace com { namespace sun { namespace star { } } }
 378
 379 /** short-circuit extra-verbose API namespaces
 380
 381  @since LibreOffice 4.0
 382 */
 383 namespace css = ::com::sun::star;
 384
 385 /** C++11 "= delete" feature.
 386
 387     For LIBO_INTERNAL_ONLY, calling a deleted function will cause a compile-time
 388     error, while otherwise it will only cause a link-time error as the declared
 389     function is not defined.
 390
 391     @since LibreOffice 4.1
 392 */
 393 #if defined LIBO_INTERNAL_ONLY
 394 #define SAL_DELETED_FUNCTION = delete
 395 #else
 396 #define SAL_DELETED_FUNCTION
 397 #endif
 398
 399 /** C++11 "override" feature.
 400
 401     For LIBO_INTERNAL_ONLY, force the method to override a existing method in
 402     parent, error out if the method with the correct signature does not exist.
 403
 404     @since LibreOffice 4.1
 405 */
 406 #if defined LIBO_INTERNAL_ONLY
 407 #define SAL_OVERRIDE override
 408 #else
 409 #define SAL_OVERRIDE
 410 #endif
 411
 412 #endif /* __cplusplus */
 413
 414 #ifdef __cplusplus
 415
 416 namespace sal {
 417
 418 /**
 419    A static_cast between integral types, to avoid C++ compiler warnings.
 420
 421    In C++ source code, use sal::static_int_cast<T>(n) instead of
 422    static_cast<T>(n) whenever a compiler warning about integral type problems
 423    shall be silenced.  That way, source code that needs to be modified when the
 424    type of any of the expressions involved in the compiler warning is changed
 425    can be found more easily.
 426
 427    Both template arguments T1 and T2 must be integral types.
 428 */
 429 template< typename T1, typename T2 > inline T1 static_int_cast(T2 n) {
 430     return static_cast< T1 >(n);
 431 }
 432
 433 }
 434
 435 #else /* __cplusplus */
 436
 437 /**
 438    A cast between integer types, to avoid C compiler warnings.
 439
 440    In C source code, use SAL_INT_CAST(type, expr) instead of ((type) (expr))
 441    whenever a compiler warning about integer type problems shall be silenced.
 442    That way, source code that needs to be modified when the type of any of the
 443    expressions involved in the compiler warning is changed can be found more
 444    easily.
 445
 446    The argument 'type' must be an integer type and the argument 'expr' must be
 447    an integer expression.  Both arguments are evaluated exactly once.
 448 */
 449 #define SAL_INT_CAST(type, expr) ((type) (expr))
 450
 451 #endif /* __cplusplus */
 452
 453 /**
 454     Use as follows:
 455         SAL_DEPRECATED("Don't use, it's evil.") void doit(int nPara);
 456 */
 457
 458 #if HAVE_GCC_DEPRECATED_MESSAGE
 459 #    define SAL_DEPRECATED(message) __attribute__((deprecated(message)))
 460 #elif defined __GNUC__ || defined __clang__
 461 #    define SAL_DEPRECATED(message) __attribute__((deprecated))
 462 #elif defined(_MSC_VER)
 463 #    define SAL_DEPRECATED(message) __declspec(deprecated(message))
 464 #else
 465 #    define SAL_DEPRECATED(message)
 466 #endif
 467
 468 /**
 469    This macro is used in cppumaker-generated include files, to tag entities that
 470    are marked as @deprecated in UNOIDL.
 471
 472    It causes deprecation warnings to be generated in external code, but for now
 473    is silenced in internal code.  It would need some substantial clean-up of
 474    internal code to fix all warnings/errors generated by it.  (Once that is
 475    done, it can become a synonym for SAL_DEPRECATED under LIBO_INTERNAL_ONLY,
 476    too.  Completely removing the macro then would be incompatible, in case there
 477    are include files still around generated with a cppumaker that emitted it.)
 478  */
 479 #ifdef LIBO_INTERNAL_ONLY
 480 #    define SAL_DEPRECATED_INTERNAL(message)
 481 #else
 482 #    define SAL_DEPRECATED_INTERNAL(message) SAL_DEPRECATED(message)
 483 #endif
 484
 485 /**
 486     Use as follows:
 487         SAL_WNODEPRECATED_DECLARATIONS_PUSH
 488         \::std::auto_ptr<X> ...
 489         SAL_WNODEPRECATED_DECLARATIONS_POP
 490 */
 491
 492 #if HAVE_GCC_PRAGMA_OPERATOR
 493 #define SAL_WNODEPRECATED_DECLARATIONS_PUSH \
 494     _Pragma(SAL_STRINGIFY_ARG(GCC diagnostic push)) \
 495     _Pragma(SAL_STRINGIFY_ARG(GCC diagnostic ignored "-Wdeprecated-declarations"))
 496 #define SAL_WNODEPRECATED_DECLARATIONS_POP \
 497     _Pragma(SAL_STRINGIFY_ARG(GCC diagnostic pop))
 498 #else
 499 #   define SAL_WNODEPRECATED_DECLARATIONS_PUSH
 500 #   define SAL_WNODEPRECATED_DECLARATIONS_POP
 501 #endif
 502
 503 /**
 504    Use as follows:
 505
 506    SAL_WNOUNREACHABLE_CODE_PUSH
 507
 508    function definition
 509
 510    SAL_WNOUNREACHABLE_CODE_POP
 511
 512    Useful in cases where the compiler is "too clever" like when doing
 513    link-time code generation, and noticing that a called function
 514    always throws, and fixing the problem cleanly so that it produces
 515    no warnings in normal non-LTO compilations either is not easy.
 516
 517 */
 518
 519 #ifdef _MSC_VER
 520 #define SAL_WNOUNREACHABLE_CODE_PUSH \
 521     __pragma(warning(push)) \
 522     __pragma(warning(disable:4702)) \
 523     __pragma(warning(disable:4722))
 524 #define SAL_WNOUNREACHABLE_CODE_POP \
 525     __pragma(warning(pop))
 526 #else
 527 /* Add definitions for GCC and Clang if needed */
 528 #define SAL_WNOUNREACHABLE_CODE_PUSH
 529 #define SAL_WNOUNREACHABLE_CODE_POP
 530 #endif
 531
 532 /** Annotate unused but required C++ function parameters.
 533
 534     An unused parameter is required if the function needs to adhere to a given
 535     type (e.g., if its address is assigned to a function pointer of a specific
 536     type, or if it is called from template code).  This annotation helps static
 537     analysis tools suppress false warnings.  In the case of virtual functions
 538     (where unused required parameters are common, too), the annotation is not
 539     required (as static analysis tools can themselves derive the information
 540     whether a function is virtual).
 541
 542     Use the annotation in function definitions like
 543
 544       void f(SAL_UNUSED_PARAMETER int) {}
 545
 546     C does not allow unnamed parameters, anyway, so a function definition like
 547     the above needs to be written there as
 548
 549       void f(int dummy) { (void) dummy; / * avoid warnings * / }
 550
 551     without a SAL_UNUSED_PARAMETER annotation.
 552
 553     @since LibreOffice 3.6
 554  */
 555 #if defined __cplusplus
 556 #if defined __GNUC__ || defined __clang__
 557 #define SAL_UNUSED_PARAMETER __attribute__ ((unused))
 558 #else
 559 #define SAL_UNUSED_PARAMETER
 560 #endif
 561 #endif
 562
 563 /**
 564
 565  Annotate classes where a compiler should warn if an instance is unused.
 566
 567  The compiler cannot warn about unused instances if they have non-trivial
 568  or external constructors or destructors. Classes marked with SAL_WARN_UNUSED
 569  will be warned about.
 570
 571  @since LibreOffice 4.0
 572
 573 */
 574
 575 #if HAVE_GCC_ATTRIBUTE_WARN_UNUSED
 576 #define SAL_WARN_UNUSED __attribute__((warn_unused))
 577 #else
 578 #define SAL_WARN_UNUSED
 579 #endif
 580
 581 /// @cond INTERNAL
 582
 583 #if defined __GNUC__ || defined __clang__
 584 // Macro to try to catch and warn on assignments inside expr.
 585 #    define SAL_DETAIL_BOOLEAN_EXPR(expr)   \
 586         __extension__ ({                    \
 587             int sal_boolean_var_;           \
 588             if (expr)                       \
 589                sal_boolean_var_ = 1;        \
 590             else                            \
 591                sal_boolean_var_ = 0;        \
 592             sal_boolean_var_;               \
 593         })
 594
 595 /** An optimization annotation: denotes that expression is likely to be true.
 596
 597     Use it to annotate paths that we think are likely eg.
 598     if (SAL_LIKELY(ptr != nullptr))
 599        // this path is the one that is ~always taken.
 600
 601     @since LibreOffice 5.2
 602
 603     Returns: the boolean value of expr (expressed as either int 1 or 0)
 604  */
 605 #    define SAL_LIKELY(expr) __builtin_expect(SAL_DETAIL_BOOLEAN_EXPR((expr)), 1)
 606
 607 /** An optimization annotation: denotes that expression is unlikely to be true.
 608
 609     Use it to annotate paths that we think are likely eg.
 610     if (SAL_UNLIKELY(ptr != nullptr))
 611        // this path is the one that is ~never taken.
 612
 613     @since LibreOffice 5.2
 614
 615     Returns: the boolean value of expr (expressed as either int 1 or 0)
 616  */
 617 #    define SAL_UNLIKELY(expr) __builtin_expect(SAL_DETAIL_BOOLEAN_EXPR((expr)), 0)
 618
 619 /** An optimization annotation: tells the compiler to work harder at this code
 620
 621     If the SAL_HOT annotation is present on a function or a label then
 622     subsequent code statements may have more aggressive compiler
 623     optimization and in-lining work performed on them.
 624
 625     In addition this code can end up in a special section, to be
 626     grouped with other frequently used code.
 627
 628     @since LibreOffice 5.2
 629  */
 630 #    define SAL_HOT __attribute__((hot))
 631
 632 /** An optimization annotation: tells the compiler to work less on this code
 633
 634     If the SAL_COLD annotation is present on a function or a label then
 635     subsequent code statements are unlikely to be performed except in
 636     exceptional circumstances, and optimizing for code-size rather
 637     than performance is preferable.
 638
 639     In addition this code can end up in a special section, to be grouped
 640     with (and away from) other more frequently used code, to improve
 641     locality of reference.
 642
 643     @since LibreOffice 5.2
 644  */
 645 #    define SAL_COLD __attribute__((cold))
 646 #else
 647 #    define SAL_LIKELY(expr) (expr)
 648 #    define SAL_UNLIKELY(expr) (expr)
 649 #    define SAL_HOT
 650 #    define SAL_COLD
 651 #endif
 652
 653 /// @endcond
 654
 655 /// @cond INTERNAL
 656 /** Annotate pointer-returning functions to indicate that such a pointer
 657     is never nullptr.
 658
 659     Note that MSVC supports this feature via it's SAL _Ret_notnull_
 660     annotation, but since it's in a completely different place on
 661     the function declaration, it's a little hard to support both.
 662
 663     @since LibreOffice 5.5
 664 */
 665 #ifndef __has_attribute
 666 #define __has_attribute(x) 0
 667 #endif
 668
 669 #if defined LIBO_INTERNAL_ONLY && ((defined __GNUC__ && !defined __clang__) || (defined __clang__ && __has_attribute(returns_nonnull)))
 670 #define SAL_RETURNS_NONNULL  __attribute__((returns_nonnull))
 671 #else
 672 #define SAL_RETURNS_NONNULL
 673 #endif
 674 /// @endcond
 675
 676 #endif // INCLUDED_SAL_TYPES_H
 677
 678 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */