1 /* EINA - EFL data type library 2 * Copyright (C) 2007-2008 Carsten Haitzler, Vincent Torri, Jorge Luis Zapata Muga 3 * 4 * This library is free software; you can redistribute it and/or 5 * modify it under the terms of the GNU Lesser General Public 6 * License as published by the Free Software Foundation; either 7 * version 2.1 of the License, or (at your option) any later version. 8 * 9 * This library is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 * Lesser General Public License for more details. 13 * 14 * You should have received a copy of the GNU Lesser General Public 15 * License along with this library; 16 * if not, see <http://www.gnu.org/licenses/>. 17 */ 18 19 #ifndef EINA_TYPES_H_ 20 #define EINA_TYPES_H_ 21 22 /** 23 * @addtogroup Eina_Core_Group Core 24 * 25 * @{ 26 */ 27 28 /** 29 * @defgroup Eina_Types_Group Types 30 * 31 * @brief Definition for eina types and core functions. 32 * 33 * @{ 34 */ 35 36 #ifdef EAPI 37 # undef EAPI 38 #endif 39 40 #ifdef _WIN32 41 # ifdef EFL_BUILD 42 # ifdef DLL_EXPORT 43 # define EAPI __declspec(dllexport) 44 # else 45 # define EAPI 46 # endif 47 # else 48 # define EAPI __declspec(dllimport) 49 # endif 50 # define EAPI_WEAK 51 #else 52 # ifdef __GNUC__ 53 # if __GNUC__ >= 4 54 # define EAPI __attribute__ ((visibility("default"))) 55 # define EAPI_WEAK __attribute__ ((weak)) 56 # else 57 # define EAPI 58 # define EAPI_WEAK 59 # endif 60 # else 61 /** 62 * @def EAPI 63 * @brief Used to export functions (by changing visibility). 64 */ 65 # define EAPI 66 /** 67 * @def EAPI_WEAK 68 * @brief Weak symbol, primarily useful in defining library functions which 69 * can be overridden in user code. 70 * Note: Not supported on all platforms. 71 */ 72 # define EAPI_WEAK 73 # endif 74 #endif 75 76 /** 77 * @def EWAPI 78 * @brief Weak symbols part of the EFL API. 79 * Note: Not supported on all platforms. 80 */ 81 #define EWAPI EAPI EAPI_WEAK 82 83 #ifdef _WIN32 84 # ifdef DLL_EXPORT 85 # define EXPORTAPI __declspec(dllexport) 86 # else 87 # define EXPORTAPI 88 # endif /* ! DLL_EXPORT */ 89 #else 90 # ifdef __GNUC__ 91 # if __GNUC__ >= 4 92 # define EXPORTAPI __attribute__ ((visibility("default"))) 93 # else 94 # define EXPORTAPI 95 # endif 96 # else 97 /** 98 * @def EXPORTAPI 99 * @brief An alias for #EAPI. 100 */ 101 # define EXPORTAPI 102 # endif 103 #endif 104 105 #include "eina_config.h" 106 107 #ifndef __WORDSIZE 108 # if defined(__OPENBSD__) && (INTPTR_MAX == INT32_MAX) 109 # define __WORDSIZE 32 110 # else 111 /** 112 * @def __WORDSIZE 113 * @brief Architecture's word size (32 or 64 bits). Defined by Eina if 114 * its definition cannot be found in the system's headers. 115 */ 116 # define __WORDSIZE 64 117 # endif 118 #endif 119 120 /* Do not turn the following #define as meaning EFL64. We are only 121 interested to know if sizeof (void*) == 64bits or not. Those means 122 something else. 123 124 defined(__x86_64__) || defined(__x86_64) || defined(__amd64__) || defined(__amd64) 125 */ 126 #if defined(_WIN64) || defined(__LP64__) || defined(_LP64) || defined(__ppc64__) 127 # define EFL64 128 #endif 129 130 #ifdef EINA_UNUSED 131 # undef EINA_UNUSED 132 #endif 133 #ifdef EINA_WARN_UNUSED_RESULT 134 # undef EINA_WARN_UNUSED_RESULT 135 #endif 136 #ifdef EINA_ARG_NONNULL 137 # undef EINA_ARG_NONNULL 138 #endif 139 #ifdef EINA_DEPRECATED 140 # undef EINA_DEPRECATED 141 #endif 142 #ifdef EINA_MALLOC 143 # undef EINA_MALLOC 144 #endif 145 #ifdef EINA_PURE 146 # undef EINA_PURE 147 #endif 148 #ifdef EINA_PRINTF 149 # undef EINA_PRINTF 150 #endif 151 #ifdef EINA_SCANF 152 # undef EINA_SCANF 153 #endif 154 #ifdef EINA_FORMAT 155 # undef EINA_FORMAT 156 #endif 157 #ifdef EINA_CONST 158 # undef EINA_CONST 159 #endif 160 #ifdef EINA_NOINSTRUMENT 161 # undef EINA_NOINSTRUMENT 162 #endif 163 #ifdef EINA_UNLIKELY 164 # undef EINA_UNLIKELY 165 #endif 166 #ifdef EINA_LIKELY 167 # undef EINA_LIKELY 168 #endif 169 #ifdef EINA_SENTINEL 170 # undef EINA_SENTINEL 171 #endif 172 #ifdef EINA_FALLTHROUGH 173 # undef EINA_FALLTHROUGH 174 #endif 175 #ifdef EINA_PREFETCH 176 # undef EINA_PREFETCH 177 #endif 178 #ifdef EINA_PREFETCH_WRITE 179 # undef EINA_PREFETCH_WRITE 180 #endif 181 #ifdef EINA_PREFETCH_NOCACHE 182 # undef EINA_PREFETCH_NOCACHE 183 #endif 184 #ifdef EINA_PREFETCH_NOCACHE_WRITE 185 # undef EINA_PREFETCH_NOCACHE_WRITE 186 #endif 187 188 #ifdef __GNUC__ 189 190 # if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1) 191 # define EINA_UNUSED __attribute__ ((__unused__)) 192 # else 193 # define EINA_UNUSED 194 # endif 195 196 # if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4) 197 # define EINA_WARN_UNUSED_RESULT __attribute__ ((__warn_unused_result__)) 198 # else 199 # define EINA_WARN_UNUSED_RESULT 200 # endif 201 202 # if (!defined(EINA_SAFETY_CHECKS)) && (__GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 3)) 203 # define EINA_ARG_NONNULL(...) __attribute__ ((__nonnull__(__VA_ARGS__))) 204 # else 205 # define EINA_ARG_NONNULL(...) 206 # endif 207 208 # if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1) 209 # define EINA_DEPRECATED __attribute__ ((__deprecated__)) 210 # else 211 # define EINA_DEPRECATED 212 # endif 213 214 # if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 96) 215 # define EINA_MALLOC __attribute__ ((__malloc__)) 216 # define EINA_PURE __attribute__ ((__pure__)) 217 # else 218 # define EINA_MALLOC 219 # define EINA_PURE 220 # endif 221 222 # if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 8) 223 # define EINA_HOT __attribute__ ((hot)) 224 # define EINA_COLD __attribute__ ((cold)) 225 # else 226 # define EINA_HOT 227 # define EINA_COLD 228 # endif 229 230 # if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ > 4) 231 # if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ > 3) 232 # define EINA_PRINTF(fmt, arg) __attribute__((__format__ (__gnu_printf__, fmt, arg))) 233 # else 234 # define EINA_PRINTF(fmt, arg) __attribute__((__format__ (__printf__, fmt, arg))) 235 # endif 236 # define EINA_SCANF(fmt, arg) __attribute__((__format__ (__scanf__, fmt, arg))) 237 # define EINA_FORMAT(fmt) __attribute__((__format_arg__(fmt))) 238 # define EINA_CONST __attribute__((__const__)) 239 # define EINA_NOINSTRUMENT __attribute__((__no_instrument_function__)) 240 # define EINA_UNLIKELY(exp) __builtin_expect((exp), 0) 241 # define EINA_LIKELY(exp) __builtin_expect((exp), 1) 242 # define EINA_SENTINEL __attribute__((__sentinel__)) 243 # ifndef __clang__ 244 # if __GNUC__ >= 7 245 # define EINA_FALLTHROUGH __attribute__ ((fallthrough)); 246 # else 247 # define EINA_FALLTHROUGH 248 # endif 249 # define EINA_PREFETCH(arg) (arg ? __builtin_prefetch(arg) : (void) arg) 250 # define EINA_PREFETCH_WRITE(arg) (arg ? __builtin_prefetch(arg, 1) : (void) arg) 251 # define EINA_PREFETCH_NOCACHE(arg) (arg ? __builtin_prefetch(arg, 0, 0) : (void) arg) 252 # define EINA_PREFETCH_NOCACHE_WRITE(arg) (arg ? __builtin_prefetch(arg, 1, 0) : (void) arg) 253 # else 254 /* LLVM Clang workaround (crash on compilation) */ 255 # define EINA_FALLTHROUGH 256 # define EINA_PREFETCH(arg) ((void) (arg)) 257 # define EINA_PREFETCH_WRITE(arg) ((void) (arg)) 258 # define EINA_PREFETCH_NOCACHE(arg) ((void) (arg)) 259 # define EINA_PREFETCH_NOCACHE_WRITE(arg) ((void) (arg)) 260 # endif 261 # else 262 # define EINA_PRINTF(fmt, arg) 263 # define EINA_SCANF(fmt, arg) 264 # define EINA_FORMAT(fmt) 265 # define EINA_CONST 266 # define EINA_NOINSTRUMENT 267 # define EINA_UNLIKELY(exp) (exp) 268 # define EINA_LIKELY(exp) (exp) 269 # define EINA_SENTINEL 270 # define EINA_FALLTHROUGH 271 # define EINA_PREFETCH(arg) ((void) (arg)) 272 # define EINA_PREFETCH_WRITE(arg) ((void) (arg)) 273 # define EINA_PREFETCH_NOCACHE(arg) ((void) (arg)) 274 # define EINA_PREFETCH_NOCACHE_WRITE(arg) ((void) (arg)) 275 # endif 276 277 #elif defined(_MSC_VER) 278 # define EINA_UNUSED 279 # define EINA_WARN_UNUSED_RESULT 280 # define EINA_ARG_NONNULL(...) 281 # if _MSC_VER >= 1300 282 # define EINA_DEPRECATED __declspec(deprecated) 283 # else 284 # define EINA_DEPRECATED 285 # endif 286 # define EINA_MALLOC 287 # define EINA_PURE 288 # define EINA_PRINTF(fmt, arg) 289 # define EINA_SCANF(fmt, arg) 290 # define EINA_FORMAT(fmt) 291 # define EINA_CONST 292 # define EINA_NOINSTRUMENT 293 # define EINA_UNLIKELY(exp) (exp) 294 # define EINA_LIKELY(exp) (exp) 295 # define EINA_SENTINEL 296 # define EINA_FALLTHROUGH 297 # define EINA_PREFETCH(arg) ((void) (arg)) 298 # define EINA_PREFETCH_WRITE(arg) ((void) (arg)) 299 # define EINA_PREFETCH_NOCACHE(arg) ((void) (arg)) 300 # define EINA_PREFETCH_NOCACHE_WRITE(arg) ((void) (arg)) 301 302 #elif defined(__SUNPRO_C) 303 # define EINA_UNUSED 304 # define EINA_WARN_UNUSED_RESULT 305 # define EINA_ARG_NONNULL(...) 306 # define EINA_DEPRECATED 307 # if __SUNPRO_C >= 0x590 308 # define EINA_MALLOC __attribute__ ((malloc)) 309 # define EINA_PURE __attribute__ ((pure)) 310 # else 311 # define EINA_MALLOC 312 # define EINA_PURE 313 # endif 314 # define EINA_PRINTF(fmt, arg) 315 # define EINA_SCANF(fmt, arg) 316 # define EINA_FORMAT(fmt) 317 # if __SUNPRO_C >= 0x590 318 # define EINA_CONST __attribute__ ((const)) 319 # else 320 # define EINA_CONST 321 # endif 322 # define EINA_NOINSTRUMENT 323 # define EINA_UNLIKELY(exp) (exp) 324 # define EINA_LIKELY(exp) (exp) 325 # define EINA_SENTINEL 326 # define EINA_FALLTHROUGH 327 # define EINA_PREFETCH(arg) ((void) (arg)) 328 # define EINA_PREFETCH_WRITE(arg) ((void) (arg)) 329 # define EINA_PREFETCH_NOCACHE(arg) ((void) (arg)) 330 # define EINA_PREFETCH_NOCACHE_WRITE(arg) ((void) (arg)) 331 332 #else /* ! __GNUC__ && ! _MSC_VER && ! __SUNPRO_C */ 333 334 /** 335 * @def EINA_UNUSED 336 * Used to indicate that a function parameter is purposely unused. 337 * This silences some compiler's warning about unused parameters. 338 */ 339 # define EINA_UNUSED 340 341 /** 342 * @def EINA_WARN_UNUSED_RESULT 343 * Used to warn when the returned value of the function is not used. 344 */ 345 # define EINA_WARN_UNUSED_RESULT 346 347 /** 348 * @def EINA_ARG_NONNULL 349 * Used to warn when the specified arguments of the function are @c NULL. 350 * 351 * @param[in] ... Ordinals of the parameters to check for nullity (1..n) 352 * 353 * @return Nothing, but Doxygen will complain if it's not documented :-P 354 * 355 */ 356 # define EINA_ARG_NONNULL(...) 357 358 /** 359 * @def EINA_DEPRECATED 360 * Used to warn when the function is considered as deprecated. 361 */ 362 # define EINA_DEPRECATED 363 364 /** 365 * @def EINA_MALLOC 366 * @brief EINA_MALLOC is used to tell the compiler that a function may be treated 367 * as if any non-NULL pointer it returns cannot alias any other pointer valid when 368 * the function returns and that the memory has undefined content. 369 */ 370 # define EINA_MALLOC 371 372 /** 373 * @def EINA_PURE 374 * @brief EINA_PURE is used to tell the compiler this function has no effect 375 * except the return value and its return value depends only on the parameters 376 * and/or global variables. 377 */ 378 # define EINA_PURE 379 380 /** 381 * @def EINA_PRINTF 382 * @brief Indicates that this function accepts a printf-style format string. 383 * This allows some compilers to perform additional checks on the parameters 384 * passed to the function. 385 * @param[in] fmt The 1-based index of the parameter specifying the format string. 386 * @param[in] arg The 1-based index of the first data parameter. 387 */ 388 # define EINA_PRINTF(fmt, arg) 389 390 /** 391 * @def EINA_SCANF 392 * @brief Indicates that this function accepts a scanf-style format string. 393 * This allows some compilers to perform additional checks on the parameters 394 * passed to the function. 395 * @param[in] fmt The 1-based index of the parameter specifying the format string. 396 * @param[in] arg The 1-based index of the first data parameter. 397 */ 398 # define EINA_SCANF(fmt, arg) 399 400 /** 401 * @def EINA_FORMAT 402 * @brief Indicates that the output of this function can be used as a format string 403 * in printf-style functions. Some compilers will check that the return value of 404 * this function is consistent with the @p fmt parameter. 405 * @param[in] fmt The 1-based index of the parameter specifying the format string. 406 */ 407 # define EINA_FORMAT(fmt) 408 409 /** 410 * @def EINA_CONST 411 * @brief Attribute from gcc to prevent the function to read/modify any global memory. 412 */ 413 # define EINA_CONST 414 415 /** 416 * @def EINA_NOINSTRUMENT 417 * @brief Attribute from gcc to disable instrumentation for a specific function. 418 */ 419 # define EINA_NOINSTRUMENT 420 421 /** 422 * @def EINA_UNLIKELY 423 * @brief Indicates that the expression is likely to be @c FALSE. Some compilers and 424 * processor architectures can then optimize the more likely path. 425 * @param[in] exp The expression to be used. 426 */ 427 # define EINA_UNLIKELY(exp) (exp) 428 429 /** 430 * @def EINA_LIKELY 431 * @brief Indicates that the expression is likely to be @c TRUE. Some compilers and 432 * processor architectures can then optimize the more likely path. 433 * @param[in] exp The expression to be used. 434 */ 435 # define EINA_LIKELY(exp) (exp) 436 437 /** 438 * @def EINA_SENTINEL 439 * @brief Attribute from gcc to prevent calls without the necessary NULL 440 * sentinel in certain variadic functions 441 * 442 * @since 1.7 443 */ 444 # define EINA_SENTINEL 445 446 /** 447 * @def EINA_FALLTHROUGH 448 * @brief Attribute from gcc to prevent warning and indicate that we expect 449 * to actually go to the next switch statement 450 * 451 * @since 1.20 452 */ 453 # define EINA_FALLTHROUGH 454 455 /** 456 * @def EINA_PREFETCH 457 * @brief Hints that the pointer @p arg needs to be pre-fetched into cache 458 * 459 * This hints to the compiler to probably issue a prefetch command for the 460 * memory address @p arg and ensure it goes into all levels of cache. For 461 * just writing to an address look at EINA_PREFETCH_WRITE(). 462 * 463 * Note that the pointer @p arg does not have to be a valid pointer and 464 * will not cause any exceptions (like segfaults) if it is invalid. 465 * 466 * @since 1.19 467 */ 468 # define EINA_PREFETCH(arg) 469 470 /** 471 * @def EINA_PREFETCH_WRITE 472 * @brief Hints that the pointer @p arg needs to be pre-fetched into cache 473 * 474 * This hints to the compiler to probably issue a prefetch command for the 475 * memory address @p arg and ensure it goes into all levels of cache. This 476 * specifically indicates that the address is going to be written to as 477 * opposed to being read from as with EINA_PREFETCH(). 478 * 479 * Note that the pointer @p arg does not have to be a valid pointer and 480 * will not cause any exceptions (like segfaults) if it is invalid. 481 * 482 * @since 1.19 483 */ 484 # define EINA_PREFETCH_WRITE(arg) 485 486 /** 487 * @def EINA_PREFETCH_NOCACHE 488 * @brief Hints that the pointer @p arg needs to be pre-fetched into cache 489 * 490 * This hints to the compiler to probably issue a prefetch command for the 491 * memory address @p arg and ensure it goes into just the closest(l1) cache. 492 * For just writing to an address look at EINA_PREFETCH_WRITE_NOCACHE(). 493 * 494 * Note that the pointer @p arg does not have to be a valid pointer and 495 * will not cause any exceptions (like segfaults) if it is invalid. 496 * 497 * @since 1.19 498 */ 499 # define EINA_PREFETCH_NOCACHE(arg) 500 501 /** 502 * @def EINA_PREFETCH_NOCACHE_WRITE 503 * 504 * @brief Hints that the pointer @p arg needs to be pre-fetched into cache 505 * 506 * This hints to the compiler to probably issue a prefetch command for the 507 * memory address @p arg and ensure it goes into just the closest(l1) cache. 508 * This specifically indicates that the address is going to be written to as 509 * opposed to being read from as with EINA_PREFETCH_NOCACHE(). 510 * Note that the pointer @p arg does not have to be a valid pointer and 511 * will not cause any exceptions (like segfaults) if it is invalid. 512 * 513 * @since 1.19 514 */ 515 # define EINA_PREFETCH_NOCACHE_WRITE(arg) 516 517 #endif /* ! __GNUC__ && ! _WIN32 && ! __SUNPRO_C */ 518 519 /** 520 * @typedef Eina_Bool 521 * Type to mimic a boolean. 522 * 523 * @note it differs from stdbool.h as this is defined as an unsigned 524 * char to make it usable by bitfields (Eina_Bool name:1) and 525 * also take as few bytes as possible. 526 */ 527 typedef unsigned char Eina_Bool; 528 529 /** 530 * @def EINA_FALSE 531 * boolean value FALSE (numerical value 0) 532 */ 533 #define EINA_FALSE ((Eina_Bool)0) 534 535 /** 536 * @def EINA_TRUE 537 * boolean value TRUE (numerical value 1) 538 */ 539 #define EINA_TRUE ((Eina_Bool)1) 540 541 /** 542 * @typedef Eina_Compare_Cb 543 * Function used in functions using sorting. It compares @p data1 and 544 * @p data2. If @p data1 is 'less' than @p data2, -1 must be returned, 545 * if it is 'greater', 1 must be returned, and if they are equal, 0 546 * must be returned. 547 */ 548 typedef int (*Eina_Compare_Cb)(const void *data1, const void *data2); 549 550 /** 551 * @def EINA_COMPARE_CB 552 * Macro to cast to Eina_Compare_Cb. 553 */ 554 #define EINA_COMPARE_CB(function) ((Eina_Compare_Cb)function) 555 556 /** 557 * @typedef Eina_Random_Cb 558 * Function used in shuffling functions. An integer between min and max 559 * inclusive must be returned. 560 * 561 * @since 1.8 562 */ 563 typedef int (*Eina_Random_Cb)(const int min, const int max); 564 565 /** 566 * @def EINA_RANDOM_CB 567 * Macro to cast to Eina_Random_Cb. 568 */ 569 #define EINA_RANDOM_CB(function) ((Eina_Random_Cb)function) 570 571 /** 572 * @typedef Eina_Process_Cb 573 * Method that processes some data and returns new data. 574 * It's meant to be used as a callback to process all nodes inside a container 575 * (See eina_iterator_processed_new, for example.) 576 * @param data The data to process. 577 * @param fdata Context data. 578 * @return The processed data. 579 */ 580 typedef void* (*Eina_Process_Cb)(const void *container, void *data, void *fdata); 581 582 /** 583 * @def EINA_PROCESS_CB 584 * Macro to cast to Eina_Process. 585 */ 586 #define EINA_PROCESS_CB(Function) ((Eina_Process_Cb)Function) 587 /** 588 * @typedef Eina_Each_Cb 589 * A callback type used when iterating over a container. 590 */ 591 typedef Eina_Bool (*Eina_Each_Cb)(const void *container, void *data, void *fdata); 592 593 /** 594 * @def EINA_EACH_CB 595 * Macro to cast to Eina_Each. 596 */ 597 #define EINA_EACH_CB(Function) ((Eina_Each_Cb)Function) 598 599 /** 600 * @typedef Eina_Free_Cb 601 * A callback type used to free data when iterating over a container. 602 */ 603 typedef void (*Eina_Free_Cb)(void *data); 604 605 /** 606 * @def EINA_FREE_CB 607 * Macro to cast to Eina_Free_Cb. 608 */ 609 #define EINA_FREE_CB(Function) ((Eina_Free_Cb)Function) 610 611 /** 612 * @def EINA_C_ARRAY_LENGTH 613 * Macro to return the array length of a standard c array. 614 * 615 * For example: 616 * int foo[] = { 0, 1, 2, 3 }; 617 * would return 4 and not 4 * sizeof(int). 618 * 619 * @since 1.2.0 620 */ 621 #define EINA_C_ARRAY_LENGTH(arr) (sizeof(arr) / sizeof((arr)[0])) 622 623 /** 624 * @def EINA_DOUBLE_EQUAL 625 * Macro to compare 2 double floating point values and deal with precision 626 * loss issues. 627 * 628 * @since 1.18 629 */ 630 #define EINA_DOUBLE_EQUAL(x, y) \ 631 (fabs((x) - (y)) <= (2.2204460492503131e-16) * fabs((x))) 632 633 /** 634 * @} 635 */ 636 637 /** 638 * @} 639 */ 640 641 #endif /* EINA_TYPES_H_ */ 642