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