third_party/nlassert/repo/include/nlassert-nonproduction.h

   1 /*
   2  *   Copyright 2010-2016 Nest Labs Inc. All Rights Reserved.
   3  *
   4  *   Licensed under the Apache License, Version 2.0 (the "License");
   5  *   you may not use this file except in compliance with the License.
   6  *   You may obtain a copy of the License at
   7  *
   8  *   http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  *   Unless required by applicable law or agreed to in writing, software
  11  *   distributed under the License is distributed on an "AS IS" BASIS,
  12  *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  *   See the License for the specific language governing permissions and
  14  *   limitations under the License.
  15  *
  16  */
  17
  18 /**
  19  *    @file
  20  *      This file defines macros and interfaces for performing
  21  *      compile- and run-time assertion checking and run-time
  22  *      exception handling when #NL_ASSERT_PRODUCTION is false.
  23  *
  24  */
  25
  26 #ifndef NLCORE_NLASSERT_NONPRODUCTION_H
  27 #define NLCORE_NLASSERT_NONPRODUCTION_H
  28
  29 #include "nlassert-internal.h"
  30
  31 /**
  32  *  @ingroup check-style
  33  *
  34  *  @{
  35  *
  36  */
  37
  38 /**
  39  *  @def NL_ASSERT_CHECK_NONPRODUCTION_FLAGS_DEFAULT
  40  *
  41  *  @brief
  42  *    This defines the default behavioral flags for check-style
  43  *    exception family assertions when #NL_ASSERT_PRODUCTION is
  44  *    disabled.
  45  *
  46  *  This may be used to override #NL_ASSERT_CHECK_NONPRODUCTION_FLAGS as follows:
  47  *
  48  *  @code
  49  *    #define NL_ASSERT_CHECK_NONPRODUCTION_FLAGS NL_ASSERT_CHECK_NONPRODUCTION_FLAGS_DEFAULT
  50  *
  51  *    #include <nlassert.h>
  52  *  @endcode
  53  *
  54  *  @sa #NL_ASSERT_CHECK_NONPRODUCTION_FLAGS
  55  *
  56  *  @sa #NL_ASSERT_PRODUCTION
  57  *
  58  *  @sa #NL_ASSERT_FLAG_BACKTRACE
  59  *  @sa #NL_ASSERT_FLAG_LOG
  60  *  @sa #NL_ASSERT_FLAG_TRAP
  61  *
  62  */
  63 #define NL_ASSERT_CHECK_NONPRODUCTION_FLAGS_DEFAULT                             (NL_ASSERT_FLAG_BACKTRACE | NL_ASSERT_FLAG_LOG | NL_ASSERT_FLAG_TRAP)
  64
  65 /**
  66  *  @def NL_ASSERT_CHECK_NONPRODUCTION_FLAGS
  67  *
  68  *  @brief
  69  *    This defines the behavioral flags when #NL_ASSERT_PRODUCTION is
  70  *    disabled that govern the behavior for check-style exception
  71  *    family assertions when the assertion expression evaluates to
  72  *    false.
  73  *
  74  *  @sa #NL_ASSERT_USE_FLAGS_DEFAULT
  75  *
  76  *  @sa #NL_ASSERT_CHECK_NONPRODUCTION_FLAGS_DEFAULT
  77  *
  78  *  @sa #NL_ASSERT_PRODUCTION
  79  *
  80  *  @sa #NL_ASSERT_FLAG_BACKTRACE
  81  *  @sa #NL_ASSERT_FLAG_LOG
  82  *  @sa #NL_ASSERT_FLAG_TRAP
  83  */
  84 #if NL_ASSERT_USE_FLAGS_DEFAULT
  85 #define NL_ASSERT_CHECK_NONPRODUCTION_FLAGS                                     NL_ASSERT_CHECK_NONPRODUCTION_FLAGS_DEFAULT
  86 #elif !defined(NL_ASSERT_CHECK_NONPRODUCTION_FLAGS)
  87 #define NL_ASSERT_CHECK_NONPRODUCTION_FLAGS                                     (NL_ASSERT_FLAG_NONE)
  88 #endif
  89
  90 /**
  91  *  @def nlCHECK(aCondition)
  92  *
  93  *  @brief
  94  *    This checks for the specified condition, which is expected to
  95  *    commonly be true and takes action, based on configuration, if
  96  *    the condition is false.
  97  *
  98  *  @note If #NL_ASSERT_PRODUCTION is true, the check is made inactive. But
  99  *  side-effects, if any, in the asserted expression will still be produced.
 100  *
 101  *  @param[in]  aCondition  A Boolean expression to be evaluated.
 102  *
 103  *  @sa #NL_ASSERT_CHECK_NONPRODUCTION_FLAGS
 104  *
 105  *  @sa #nlVERIFY
 106  *
 107  */
 108 #define nlCHECK(aCondition)                                                     __nlCHECK(NL_ASSERT_CHECK_NONPRODUCTION_FLAGS, aCondition)
 109
 110 /**
 111  *  @def nlCHECK_ACTION(aCondition, anAction)
 112  *
 113  *  @brief
 114  *    This checks for the specified condition, which is expected to
 115  *    commonly be true and takes action, based on configuration, and
 116  *    executes @p anAction if the condition is false.
 117  *
 118  *  @note If #NL_ASSERT_PRODUCTION is true, the check is made inactive. But
 119  *  side-effects, if any, in the asserted expression will still be produced.
 120  *
 121  *  @param[in]  aCondition  A Boolean expression to be evaluated.
 122  *  @param[in]  anAction    An expression or block to execute when the
 123  *                          assertion fails. This will be executed
 124  *                          after #NL_ASSERT_LOG() and
 125  *                          #NL_ASSERT_BACKTRACE() but before
 126  *                          #NL_ASSERT_TRAP().
 127  *
 128  *  @sa #NL_ASSERT_CHECK_NONPRODUCTION_FLAGS
 129  *
 130  *  @sa #nlVERIFY_ACTION
 131  *
 132  */
 133 #define nlCHECK_ACTION(aCondition, anAction)                                    __nlCHECK_ACTION(NL_ASSERT_CHECK_NONPRODUCTION_FLAGS, aCondition, anAction)
 134
 135 /**
 136  *  @def nlCHECK_PRINT(aCondition, aMessage)
 137  *
 138  *  @brief
 139  *    This checks for the specified condition, which is expected to
 140  *    commonly be true and takes action, based on configuration, and
 141  *    prints @p aMessage if the condition is false.
 142  *
 143  *  @note If #NL_ASSERT_PRODUCTION is true, the check is made inactive. But
 144  *  side-effects, if any, in the asserted expression will still be produced.
 145  *
 146  *  @param[in]  aCondition  A Boolean expression to be evaluated.
 147  *  @param[in]  aMessage    A pointer to a NULL-terminated C string
 148  *                          containing a caller-specified message
 149  *                          further describing the assertion failure.
 150  *
 151  *  @sa #NL_ASSERT_CHECK_NONPRODUCTION_FLAGS
 152  *
 153  *  @sa #nlVERIFY_PRINT
 154  *
 155  */
 156 #define nlCHECK_PRINT(aCondition, aMessage)                                     __nlCHECK_PRINT(NL_ASSERT_CHECK_NONPRODUCTION_FLAGS, aCondition, aMessage)
 157
 158 /**
 159  *  @def nlCHECK_SUCCESS(aStatus)
 160  *
 161  *  @brief
 162  *    This checks for the specified status, which is expected to
 163  *    commonly be successful (i.e. zero (0)) and takes action, based
 164  *    on configuration, if the status is unsuccessful.
 165  *
 166  *  @note If #NL_ASSERT_PRODUCTION is true, the check is made inactive. But
 167  *  side-effects, if any, in the asserted expression will still be produced.
 168  *
 169  *  @param[in]  aStatus     A scalar status to be evaluated against zero (0).
 170  *
 171  *  @sa #NL_ASSERT_CHECK_NONPRODUCTION_FLAGS
 172  *
 173  *  @sa #nlVERIFY_SUCCESS
 174  *
 175  */
 176 #define nlCHECK_SUCCESS(aStatus)                                                __nlCHECK_SUCCESS(NL_ASSERT_CHECK_NONPRODUCTION_FLAGS, aStatus)
 177
 178 /**
 179  *  @def nlCHECK_SUCCESS_ACTION(aStatus, anAction)
 180  *
 181  *  @brief
 182  *    This checks for the specified status, which is expected to
 183  *    commonly be successful (i.e. zero (0)) and takes action, based
 184  *    on configuration, and executes @p anAction if the status is
 185  *    unsuccessful.
 186  *
 187  *  @note If #NL_ASSERT_PRODUCTION is true, the check is made inactive. But
 188  *  side-effects, if any, in the asserted expression will still be produced.
 189  *
 190  *  @param[in]  aStatus     A scalar status to be evaluated against zero (0).
 191  *  @param[in]  anAction    An expression or block to execute when the
 192  *                          assertion fails. This will be executed
 193  *                          after #NL_ASSERT_LOG() and
 194  *                          #NL_ASSERT_BACKTRACE() but before
 195  *                          #NL_ASSERT_TRAP().
 196  *
 197  *  @sa #NL_ASSERT_CHECK_NONPRODUCTION_FLAGS
 198  *
 199  *  @sa #nlVERIFY_SUCCESS_ACTION
 200  *
 201  */
 202 #define nlCHECK_SUCCESS_ACTION(aStatus, anAction)                               __nlCHECK_SUCCESS_ACTION(NL_ASSERT_CHECK_NONPRODUCTION_FLAGS, aStatus, anAction)
 203
 204 /**
 205  *  @def nlCHECK_SUCCESS_PRINT(aStatus, aMessage)
 206  *
 207  *  @brief
 208  *    This checks for the specified status, which is expected to
 209  *    commonly be successful (i.e. zero (0)) and takes action, based
 210  *    on configuration, and prints @p aMessage if the status is
 211  *    unsuccessful.
 212  *
 213  *  @note If #NL_ASSERT_PRODUCTION is true, the check is made inactive. But
 214  *  side-effects, if any, in the asserted expression will still be produced.
 215  *
 216  *  @param[in]  aStatus     A scalar status to be evaluated against zero (0).
 217  *  @param[in]  aMessage    A pointer to a NULL-terminated C string
 218  *                          containing a caller-specified message
 219  *                          further describing the assertion failure.
 220  *
 221  *  @sa #NL_ASSERT_CHECK_NONPRODUCTION_FLAGS
 222  *
 223  *  @sa #nlVERIFY_SUCCESS_PRINT
 224  *
 225  */
 226 #define nlCHECK_SUCCESS_PRINT(aStatus, aMessage)                                __nlCHECK_SUCCESS_PRINT(NL_ASSERT_CHECK_NONPRODUCTION_FLAGS, aStatus, aMessage)
 227
 228 /**
 229  *  @def nlNCHECK(aCondition)
 230  *
 231  *  @brief
 232  *    This checks for the specified condition, which is expected to
 233  *    commonly be false and takes action, based on configuration, if
 234  *    the condition is true.
 235  *
 236  *  @note This is the logical inverse of #nlCHECK
 237  *
 238  *  @note If #NL_ASSERT_PRODUCTION is true, the check is made inactive. But
 239  *  side-effects, if any, in the asserted expression will still be produced.
 240  *
 241  *  @param[in]  aCondition  A Boolean expression to be evaluated.
 242  *
 243  *  @sa #NL_ASSERT_CHECK_NONPRODUCTION_FLAGS
 244  *
 245  *  @sa #nlCHECK
 246  *  @sa #nlNVERIFY
 247  *
 248  */
 249 #define nlNCHECK(aCondition)                                                    __nlNCHECK(NL_ASSERT_CHECK_NONPRODUCTION_FLAGS, aCondition)
 250
 251 /**
 252  *  @def nlNCHECK_ACTION(aCondition, anAction)
 253  *
 254  *  @brief
 255  *    This checks for the specified condition, which is expected to
 256  *    commonly be false and takes action, based on configuration, and
 257  *    executes @p anAction if the condition is true.
 258  *
 259  *  @note This is the logical inverse of #nlCHECK_ACTION
 260  *
 261  *  @note If #NL_ASSERT_PRODUCTION is true, the check is made inactive. But
 262  *  side-effects, if any, in the asserted expression will still be produced.
 263  *
 264  *  @param[in]  aCondition  A Boolean expression to be evaluated.
 265  *  @param[in]  anAction    An expression or block to execute when the
 266  *                          assertion fails. This will be executed
 267  *                          after #NL_ASSERT_LOG() and
 268  *                          #NL_ASSERT_BACKTRACE() but before
 269  *                          #NL_ASSERT_TRAP().
 270  *
 271  *  @sa #NL_ASSERT_CHECK_NONPRODUCTION_FLAGS
 272  *
 273  *  @sa #nlCHECK_ACTION
 274  *  @sa #nlNVERIFY_ACTION
 275  *
 276  */
 277 #define nlNCHECK_ACTION(aCondition, anAction)                                   __nlNCHECK_ACTION(NL_ASSERT_CHECK_NONPRODUCTION_FLAGS, aCondition, anAction)
 278
 279 /**
 280  *  @def nlNCHECK_PRINT(aCondition, aMessage)
 281  *
 282  *  @brief
 283  *    This checks for the specified condition, which is expected to
 284  *    commonly be false and takes action, based on configuration, and
 285  *    prints @p aMessage if the condition is true.
 286  *
 287  *  @note This is the logical inverse of #nlCHECK_PRINT
 288  *
 289  *  @note If #NL_ASSERT_PRODUCTION is true, the check is made inactive. But
 290  *  side-effects, if any, in the asserted expression will still be produced.
 291  *
 292  *  @param[in]  aCondition  A Boolean expression to be evaluated.
 293  *  @param[in]  aMessage    A pointer to a NULL-terminated C string
 294  *                          containing a caller-specified message
 295  *                          further describing the assertion failure.
 296  *
 297  *  @sa #NL_ASSERT_CHECK_NONPRODUCTION_FLAGS
 298  *
 299  *  @sa #nlCHECK_PRINT
 300  *  @sa #nlNVERIFY_PRINT
 301  *
 302  */
 303 #define nlNCHECK_PRINT(aCondition, aMessage)                                    __nlNCHECK_PRINT(NL_ASSERT_CHECK_NONPRODUCTION_FLAGS, aCondition, aMessage)
 304
 305 /**
 306  *  @}
 307  *
 308  */
 309
 310 /**
 311  *  @ingroup verify-style
 312  *
 313  *  @{
 314  *
 315  */
 316
 317 /**
 318  *  @def NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS_DEFAULT
 319  *
 320  *  @brief
 321  *    This defines the default behavioral flags for verify-style
 322  *    exception family assertions when #NL_ASSERT_PRODUCTION is
 323  *    disabled.
 324  *
 325  *  This may be used to override #NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS as follows:
 326  *
 327  *  @code
 328  *    #define NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS_DEFAULT
 329  *
 330  *    #include <nlassert.h>
 331  *  @endcode
 332  *
 333  *  @sa #NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS
 334  *
 335  *  @sa #NL_ASSERT_PRODUCTION
 336  *
 337  *  @sa #NL_ASSERT_FLAG_BACKTRACE
 338  *  @sa #NL_ASSERT_FLAG_LOG
 339  *  @sa #NL_ASSERT_FLAG_TRAP
 340  *
 341  */
 342 #define NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS_DEFAULT                            (NL_ASSERT_FLAG_BACKTRACE | NL_ASSERT_FLAG_LOG | NL_ASSERT_FLAG_TRAP)
 343
 344 /**
 345  *  @def NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS
 346  *
 347  *  @brief
 348  *    This defines the behavioral flags when #NL_ASSERT_PRODUCTION is
 349  *    disabled that govern the behavior for verify-style exception
 350  *    family assertions when the assertion expression evaluates to
 351  *    false.
 352  *
 353  *  @sa #NL_ASSERT_USE_FLAGS_DEFAULT
 354  *
 355  *  @sa #NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS_DEFAULT
 356  *
 357  *  @sa #NL_ASSERT_PRODUCTION
 358  *
 359  *  @sa #NL_ASSERT_FLAG_BACKTRACE
 360  *  @sa #NL_ASSERT_FLAG_LOG
 361  *  @sa #NL_ASSERT_FLAG_TRAP
 362  */
 363 #if NL_ASSERT_USE_FLAGS_DEFAULT
 364 #define NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS                                    NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS_DEFAULT
 365 #elif !defined(NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS)
 366 #define NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS                                    (NL_ASSERT_FLAG_NONE)
 367 #endif
 368
 369 /**
 370  *  @def nlVERIFY(aCondition)
 371  *
 372  *  @brief
 373  *    This checks for the specified condition, which is expected to
 374  *    commonly be true and takes action, based on configuration, if
 375  *    the condition is false.
 376  *
 377  *  @param[in]  aCondition  A Boolean expression to be evaluated.
 378  *
 379  *  @sa #NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS
 380  *  @sa #NL_ASSERT_VERIFY_PRODUCTION_FLAGS
 381  *
 382  *  @sa #nlCHECK
 383  *
 384  */
 385 #define nlVERIFY(aCondition)                                                    __nlVERIFY(NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS, aCondition)
 386
 387 /**
 388  *  @def nlVERIFY_ACTION(aCondition, anAction)
 389  *
 390  *  @brief
 391  *    This checks for the specified condition, which is expected to
 392  *    commonly be true and takes action, based on configuration, and
 393  *    executes @p anAction if the condition is false.
 394  *
 395  *  @param[in]  aCondition  A Boolean expression to be evaluated.
 396  *  @param[in]  anAction    An expression or block to execute when the
 397  *                          assertion fails. This will be executed
 398  *                          after #NL_ASSERT_LOG() and
 399  *                          #NL_ASSERT_BACKTRACE() but before
 400  *                          #NL_ASSERT_TRAP().
 401  *
 402  *  @sa #NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS
 403  *  @sa #NL_ASSERT_VERIFY_PRODUCTION_FLAGS
 404  *
 405  *  @sa #nlCHECK_ACTION
 406  *
 407  */
 408 #define nlVERIFY_ACTION(aCondition, anAction)                                   __nlVERIFY_ACTION(NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS, aCondition, anAction)
 409
 410 /**
 411  *  @def nlVERIFY_PRINT(aCondition, aMessage)
 412  *
 413  *  @brief
 414  *    This checks for the specified condition, which is expected to
 415  *    commonly be true and takes action, based on configuration, and
 416  *    prints @p aMessage if the condition is false.
 417  *
 418  *  @param[in]  aCondition  A Boolean expression to be evaluated.
 419  *  @param[in]  aMessage    A pointer to a NULL-terminated C string
 420  *                          containing a caller-specified message
 421  *                          further describing the assertion failure.
 422  *
 423  *  @sa #NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS
 424  *  @sa #NL_ASSERT_VERIFY_PRODUCTION_FLAGS
 425  *
 426  *  @sa #nlCHECK_PRINT
 427  *
 428  */
 429 #define nlVERIFY_PRINT(aCondition, aMessage)                                    __nlVERIFY_PRINT(NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS, aCondition, aMessage)
 430
 431 /**
 432  *  @def nlVERIFY_SUCCESS(aStatus)
 433  *
 434  *  @brief
 435  *    This checks for the specified status, which is expected to
 436  *    commonly be successful (i.e. zero (0)) and takes action, based
 437  *    on configuration, if the status is unsuccessful.
 438  *
 439  *  @param[in]  aStatus     A scalar status to be evaluated against zero (0).
 440  *
 441  *  @sa #NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS
 442  *  @sa #NL_ASSERT_VERIFY_PRODUCTION_FLAGS
 443  *
 444  *  @sa #nlCHECK_SUCCESS
 445  *
 446  */
 447 #define nlVERIFY_SUCCESS(aStatus)                                               __nlVERIFY_SUCCESS(NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS, aStatus)
 448
 449 /**
 450  *  @def nlVERIFY_SUCCESS_ACTION(aStatus, anAction)
 451  *
 452  *  @brief
 453  *    This checks for the specified status, which is expected to
 454  *    commonly be successful (i.e. zero (0)) and takes action, based
 455  *    on configuration, and executes @p anAction if the status is
 456  *    unsuccessful.
 457  *
 458  *  @param[in]  aStatus     A scalar status to be evaluated against zero (0).
 459  *  @param[in]  anAction    An expression or block to execute when the
 460  *                          assertion fails. This will be executed
 461  *                          after #NL_ASSERT_LOG() and
 462  *                          #NL_ASSERT_BACKTRACE() but before
 463  *                          #NL_ASSERT_TRAP().
 464  *
 465  *  @sa #NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS
 466  *  @sa #NL_ASSERT_VERIFY_PRODUCTION_FLAGS
 467  *
 468  *  @sa #nlCHECK_SUCCESS_ACTION
 469  *
 470  */
 471 #define nlVERIFY_SUCCESS_ACTION(aStatus, anAction)                              __nlVERIFY_SUCCESS_ACTION(NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS, aStatus, anAction)
 472
 473 /**
 474  *  @def nlVERIFY_SUCCESS_PRINT(aStatus, aMessage)
 475  *
 476  *  @brief
 477  *    This checks for the specified status, which is expected to
 478  *    commonly be successful (i.e. zero (0)) and takes action, based
 479  *    on configuration, and prints @p aMessage if the status is
 480  *    unsuccessful.
 481  *
 482  *  @param[in]  aStatus     A scalar status to be evaluated against zero (0).
 483  *  @param[in]  aMessage    A pointer to a NULL-terminated C string
 484  *                          containing a caller-specified message
 485  *                          further describing the assertion failure.
 486  *
 487  *  @sa #NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS
 488  *  @sa #NL_ASSERT_VERIFY_PRODUCTION_FLAGS
 489  *
 490  *  @sa #nlCHECK_SUCCESS_PRINT
 491  *
 492  */
 493 #define nlVERIFY_SUCCESS_PRINT(aStatus, aMessage)                               __nlVERIFY_SUCCESS_PRINT(NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS, aStatus, aMessage)
 494
 495 /**
 496  *  @def nlNVERIFY(aCondition)
 497  *
 498  *  @brief
 499  *    This checks for the specified condition, which is expected to
 500  *    commonly be false and takes action, based on configuration, if
 501  *    the condition is true.
 502  *
 503  *  @note This is the logical inverse of #nlVERIFY
 504  *
 505  *  @param[in]  aCondition  A Boolean expression to be evaluated.
 506  *
 507  *  @sa #NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS
 508  *  @sa #NL_ASSERT_VERIFY_PRODUCTION_FLAGS
 509  *
 510  *  @sa #nlVERIFY
 511  *  @sa #nlNCHECK
 512  *
 513  */
 514 #define nlNVERIFY(aCondition)                                                   __nlNVERIFY(NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS, aCondition)
 515
 516 /**
 517  *  @def nlNVERIFY_ACTION(aCondition, anAction)
 518  *
 519  *  @brief
 520  *    This checks for the specified condition, which is expected to
 521  *    commonly be false and takes action, based on configuration, and
 522  *    executes @p anAction if the condition is true.
 523  *
 524  *  @note This is the logical inverse of #nlVERIFY_ACTION
 525  *
 526  *  @param[in]  aCondition  A Boolean expression to be evaluated.
 527  *  @param[in]  anAction    An expression or block to execute when the
 528  *                          assertion fails. This will be executed
 529  *                          after #NL_ASSERT_LOG() and
 530  *                          #NL_ASSERT_BACKTRACE() but before
 531  *                          #NL_ASSERT_TRAP().
 532  *
 533  *  @sa #NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS
 534  *  @sa #NL_ASSERT_VERIFY_PRODUCTION_FLAGS
 535  *
 536  *  @sa #nlVERIFY_ACTION
 537  *  @sa #nlNCHECK_ACTION
 538  *
 539  */
 540 #define nlNVERIFY_ACTION(aCondition, anAction)                                  __nlNVERIFY_ACTION(NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS, aCondition, anAction)
 541
 542 /**
 543  *  @def nlNVERIFY_PRINT(aCondition, aMessage)
 544  *
 545  *  @brief
 546  *    This checks for the specified condition, which is expected to
 547  *    commonly be false and takes action, based on configuration, and
 548  *    prints @p aMessage if the condition is true.
 549  *
 550  *  @note This is the logical inverse of #nlVERIFY_PRINT
 551  *
 552  *  @param[in]  aCondition  A Boolean expression to be evaluated.
 553  *  @param[in]  aMessage    A pointer to a NULL-terminated C string
 554  *                          containing a caller-specified message
 555  *                          further describing the assertion failure.
 556  *
 557  *  @sa #NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS
 558  *  @sa #NL_ASSERT_VERIFY_PRODUCTION_FLAGS
 559  *
 560  *  @sa #nlVERIFY_PRINT
 561  *  @sa #nlNCHECK_PRINT
 562  *
 563  */
 564 #define nlNVERIFY_PRINT(aCondition, aMessage)                                   __nlNVERIFY_PRINT(NL_ASSERT_VERIFY_NONPRODUCTION_FLAGS, aCondition, aMessage)
 565
 566 /**
 567  *  @}
 568  *
 569  */
 570
 571 /**
 572  *  @ingroup desire-style
 573  *
 574  *  @{
 575  *
 576  */
 577
 578 /**
 579  *  @def NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS_DEFAULT
 580  *
 581  *  @brief
 582  *    This defines the default behavioral flags for desire-style
 583  *    exception family assertions when #NL_ASSERT_PRODUCTION is
 584  *    disabled.
 585  *
 586  *  This may be used to override #NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS as follows:
 587  *
 588  *  @code
 589  *    #define NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS_DEFAULT
 590  *
 591  *    #include <nlassert.h>
 592  *  @endcode
 593  *
 594  *  @sa #NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS
 595  *
 596  *  @sa #NL_ASSERT_PRODUCTION
 597  *
 598  *  @sa #NL_ASSERT_FLAG_BACKTRACE
 599  *  @sa #NL_ASSERT_FLAG_LOG
 600  *  @sa #NL_ASSERT_FLAG_TRAP
 601  *
 602  */
 603 #define NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS_DEFAULT                            (NL_ASSERT_FLAG_LOG)
 604
 605 /**
 606  *  @def NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS
 607  *
 608  *  @brief
 609  *    This defines the behavioral flags when #NL_ASSERT_PRODUCTION is
 610  *    disabled that govern the behavior for desire-style exception
 611  *    family assertions when the assertion expression evaluates to
 612  *    false.
 613  *
 614  *  @sa #NL_ASSERT_USE_FLAGS_DEFAULT
 615  *
 616  *  @sa #NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS_DEFAULT
 617  *
 618  *  @sa #NL_ASSERT_PRODUCTION
 619  *
 620  *  @sa #NL_ASSERT_FLAG_BACKTRACE
 621  *  @sa #NL_ASSERT_FLAG_LOG
 622  *  @sa #NL_ASSERT_FLAG_TRAP
 623  */
 624 #if NL_ASSERT_USE_FLAGS_DEFAULT
 625 #define NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS                                    NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS_DEFAULT
 626 #elif !defined(NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS)
 627 #define NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS                                    (NL_ASSERT_FLAG_NONE)
 628 #endif
 629
 630 /**
 631  *  @def nlDESIRE(aCondition, aLabel)
 632  *
 633  *  @brief
 634  *    This checks for the specified condition, which is expected to
 635  *    commonly be true, and branches to @p aLabel if the condition is
 636  *    false.
 637  *
 638  *  __Anticipated Assertion Firing Frequency:__ Occasional
 639  *
 640  *  @param[in]  aCondition  A Boolean expression to be evaluated.
 641  *  @param[in]  aLabel      The local label to which execution branches
 642  *                          when @p aCondition evaluates to false (i.e.
 643  *                          compares equal to zero).
 644  *
 645  *  @sa #NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS
 646  *  @sa #NL_ASSERT_DESIRE_PRODUCTION_FLAGS
 647  *
 648  *  @sa #nlEXPECT
 649  *  @sa #nlREQUIRE
 650  *
 651  */
 652 #define nlDESIRE(aCondition, aLabel)                                            __nlEXPECT(NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS, aCondition, aLabel)
 653
 654 /**
 655  *  @def nlDESIRE_PRINT(aCondition, aLabel, aMessage)
 656  *
 657  *  @brief
 658  *    This checks for the specified condition, which is expected to
 659  *    commonly be true, and both prints @p aMessage and then branches
 660  *    to @p aLabel if the condition is false.
 661  *
 662  *  __Anticipated Assertion Firing Frequency:__ Occasional
 663  *
 664  *  @param[in]  aCondition  A Boolean expression to be evaluated.
 665  *  @param[in]  aLabel      The local label to which execution branches
 666  *                          when @p aCondition evaluates to false (i.e.
 667  *                          compares equal to zero).
 668  *  @param[in]  aMessage    A pointer to a NULL-terminated C string
 669  *                          containing a caller-specified message
 670  *                          further describing the assertion failure.
 671  *
 672  *  @sa #NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS
 673  *  @sa #NL_ASSERT_DESIRE_PRODUCTION_FLAGS
 674  *
 675  *  @sa #nlEXPECT_PRINT
 676  *  @sa #nlREQUIRE_PRINT
 677  *
 678  */
 679 #define nlDESIRE_PRINT(aCondition, aLabel, aMessage)                            __nlEXPECT_PRINT(NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS, aCondition, aLabel, aMessage)
 680
 681 /**
 682  *  @def nlDESIRE_ACTION(aCondition, aLabel, anAction)
 683  *
 684  *  @brief
 685  *    This checks for the specified condition, which is expected to
 686  *    commonly be true, and both executes @p anAction and branches to
 687  *    @p aLabel if the condition is false.
 688  *
 689  *  __Anticipated Assertion Firing Frequency:__ Occasional
 690  *
 691  *  @param[in]  aCondition  A Boolean expression to be evaluated.
 692  *  @param[in]  aLabel      The local label to which execution branches
 693  *                          when @p aCondition evaluates to false (i.e.
 694  *                          compares equal to zero).
 695  *  @param[in]  anAction    An expression or block to execute when the
 696  *                          assertion fails. This will be executed
 697  *                          after #NL_ASSERT_LOG() and
 698  *                          #NL_ASSERT_BACKTRACE() but before
 699  *                          #NL_ASSERT_TRAP().
 700  *
 701  *  @sa #NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS
 702  *  @sa #NL_ASSERT_DESIRE_PRODUCTION_FLAGS
 703  *
 704  *  @sa #nlEXPECT_ACTION
 705  *  @sa #nlREQUIRE_ACTION
 706  *
 707  */
 708 #define nlDESIRE_ACTION(aCondition, aLabel, anAction)                           __nlEXPECT_ACTION(NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS, aCondition, aLabel, anAction)
 709
 710 /**
 711  *  @def nlDESIRE_ACTION_PRINT(aCondition, aLabel, anAction, aMessage)
 712  *
 713  *  @brief
 714  *    This checks for the specified condition, which is expected to
 715  *    commonly be true, prints @p aMessage, executes @p anAction, and
 716  *    branches to @p aLabel if the condition is false.
 717  *
 718  *  __Anticipated Assertion Firing Frequency:__ Occasional
 719  *
 720  *  @param[in]  aCondition  A Boolean expression to be evaluated.
 721  *  @param[in]  aLabel      The local label to which execution branches
 722  *                          when @p aCondition evaluates to false (i.e.
 723  *                          compares equal to zero).
 724  *  @param[in]  anAction    An expression or block to execute when the
 725  *                          assertion fails. This will be executed
 726  *                          after #NL_ASSERT_LOG() and
 727  *                          #NL_ASSERT_BACKTRACE() but before
 728  *                          #NL_ASSERT_TRAP().
 729  *  @param[in]  aMessage    A pointer to a NULL-terminated C string
 730  *                          containing a caller-specified message
 731  *                          further describing the assertion failure.
 732  *
 733  *  @sa #NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS
 734  *  @sa #NL_ASSERT_DESIRE_PRODUCTION_FLAGS
 735  *
 736  *  @sa #nlEXPECT_ACTION_PRINT
 737  *  @sa #nlREQUIRE_ACTION_PRINT
 738  *
 739  */
 740 #define nlDESIRE_ACTION_PRINT(aCondition, aLabel, anAction, aMessage)           __nlEXPECT_ACTION_PRINT(NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS, aCondition, aLabel, anAction, aMessage)
 741
 742 /**
 743  *  @def nlDESIRE_SUCCESS(aStatus, aLabel)
 744  *
 745  *  @brief
 746  *    This checks for the specified status, which is expected to
 747  *    commonly be successful (i.e. zero (0)), and branches to @p
 748  *    aLabel if the status is unsuccessful.
 749  *
 750  *  __Anticipated Assertion Firing Frequency:__ Occasional
 751  *
 752  *  @param[in]  aStatus     A scalar status to be evaluated against zero (0).
 753  *  @param[in]  aLabel      The local label to which execution branches
 754  *                          when @p aStatus does not evaluate to zero
 755  *                          (0).
 756  *
 757  *  @sa #NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS
 758  *  @sa #NL_ASSERT_DESIRE_PRODUCTION_FLAGS
 759  *
 760  *  @sa #nlEXPECT_SUCCESS
 761  *  @sa #nlREQUIRE_SUCCESS
 762  *
 763  */
 764 #define nlDESIRE_SUCCESS(aStatus, aLabel)                                       __nlEXPECT_SUCCESS(NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS, aStatus, aLabel)
 765
 766 /**
 767  *  @def nlDESIRE_SUCCESS_PRINT(aStatus, aLabel, aMessage)
 768  *
 769  *  @brief
 770  *    This checks for the specified status, which is expected to
 771  *    commonly be successful (i.e. zero (0)), and both prints @p
 772  *    aMessage and then branches to @p aLabel if the status is
 773  *    unsuccessful.
 774  *
 775  *  __Anticipated Assertion Firing Frequency:__ Occasional
 776  *
 777  *  @param[in]  aStatus     A scalar status to be evaluated against zero (0).
 778  *  @param[in]  aLabel      The local label to which execution branches
 779  *                          when @p aStatus does not evaluate to zero
 780  *                          (0).
 781  *  @param[in]  aMessage    A pointer to a NULL-terminated C string
 782  *                          containing a caller-specified message
 783  *                          further describing the assertion failure.
 784  *
 785  *  @sa #NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS
 786  *  @sa #NL_ASSERT_DESIRE_PRODUCTION_FLAGS
 787  *
 788  *  @sa #nlEXPECT_SUCCESS_PRINT
 789  *  @sa #nlREQUIRE_SUCCESS_PRINT
 790  *
 791  */
 792 #define nlDESIRE_SUCCESS_PRINT(aStatus, aLabel, aMessage)                       __nlEXPECT_SUCCESS_PRINT(NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS, aStatus, aLabel, aMessage)
 793
 794 /**
 795  *  @def nlDESIRE_SUCCESS_ACTION(aStatus, aLabel, anAction)
 796  *
 797  *  @brief
 798  *    This checks for the specified status, which is expected to
 799  *    commonly be successful (i.e. zero (0)), and both executes @p
 800  *    anAction and branches to @p aLabel if the status is
 801  *    unsuccessful.
 802  *
 803  *  __Anticipated Assertion Firing Frequency:__ Occasional
 804  *
 805  *  @param[in]  aStatus     A scalar status to be evaluated against zero (0).
 806  *  @param[in]  aLabel      The local label to which execution branches
 807  *                          when @p aStatus does not evaluate to zero
 808  *                          (0).
 809  *  @param[in]  anAction    An expression or block to execute when the
 810  *                          assertion fails. This will be executed
 811  *                          after #NL_ASSERT_LOG() and
 812  *                          #NL_ASSERT_BACKTRACE() but before
 813  *                          #NL_ASSERT_TRAP().
 814  *
 815  *  @sa #NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS
 816  *  @sa #NL_ASSERT_DESIRE_PRODUCTION_FLAGS
 817  *
 818  *  @sa #nlEXPECT_SUCCESS_ACTION
 819  *  @sa #nlREQUIRE_SUCCESS_ACTION
 820  *
 821  */
 822 #define nlDESIRE_SUCCESS_ACTION(aStatus, aLabel, anAction)                      __nlEXPECT_SUCCESS_ACTION(NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS, aStatus, aLabel, anAction)
 823
 824 /**
 825  *  @def nlDESIRE_SUCCESS_ACTION_PRINT(aStatus, aLabel, anAction, aMessage)
 826  *
 827  *  @brief
 828  *    This checks for the specified status, which is expected to
 829  *    commonly be successful (i.e. zero (0)), prints @p aMessage,
 830  *    executes @p anAction, and branches to @p aLabel if the status is
 831  *    unsuccessful.
 832  *
 833  *  __Anticipated Assertion Firing Frequency:__ Occasional
 834  *
 835  *  @param[in]  aStatus     A scalar status to be evaluated against zero (0).
 836  *  @param[in]  aLabel      The local label to which execution branches
 837  *                          when @p aStatus does not evaluate to zero
 838  *                          (0).
 839  *  @param[in]  anAction    An expression or block to execute when the
 840  *                          assertion fails. This will be executed
 841  *                          after #NL_ASSERT_LOG() and
 842  *                          #NL_ASSERT_BACKTRACE() but before
 843  *                          #NL_ASSERT_TRAP().
 844  *  @param[in]  aMessage    A pointer to a NULL-terminated C string
 845  *                          containing a caller-specified message
 846  *                          further describing the assertion failure.
 847  *
 848  *  @sa #NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS
 849  *  @sa #NL_ASSERT_DESIRE_PRODUCTION_FLAGS
 850  *
 851  *  @sa #nlEXPECT_SUCCESS_ACTION_PRINT
 852  *  @sa #nlREQUIRE_SUCCESS_ACTION_PRINT
 853  *
 854  */
 855 #define nlDESIRE_SUCCESS_ACTION_PRINT(aStatus, aLabel, anAction, aMessage)      __nlEXPECT_SUCCESS_ACTION_PRINT(NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS, aStatus, aLabel, anAction, aMessage)
 856
 857 /**
 858  *  @def nlNDESIRE(aCondition, aLabel)
 859  *
 860  *  @brief
 861  *    This checks for the specified condition, which is expected to
 862  *    commonly be false, and branches to @p aLabel if the condition is
 863  *    true.
 864  *
 865  *  @note This is the logical inverse of #nlDESIRE.
 866  *
 867  *  __Anticipated Assertion Firing Frequency:__ Occasional
 868  *
 869  *  @param[in]  aCondition  A Boolean expression to be evaluated.
 870  *  @param[in]  aLabel      The local label to which execution branches
 871  *                          when @p aCondition evaluates to false (i.e.
 872  *                          compares equal to zero).
 873  *
 874  *  @sa #NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS
 875  *  @sa #NL_ASSERT_DESIRE_PRODUCTION_FLAGS
 876  *
 877  *  @sa #nlDESIRE
 878  *  @sa #nlNEXPECT
 879  *  @sa #nlNREQUIRE
 880  *
 881  */
 882 #define nlNDESIRE(aCondition, aLabel)                                           __nlNEXPECT(NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS, aCondition, aLabel)
 883
 884 /**
 885  *  @def nlNDESIRE_PRINT(aCondition, aLabel, aMessage)
 886  *
 887  *  @brief
 888  *    This checks for the specified condition, which is expected to
 889  *    commonly be false, and both prints @p aMessage and then branches
 890  *    to @p aLabel if the condition is true.
 891  *
 892  *  @note This is the logical inverse of #nlDESIRE_PRINT.
 893  *
 894  *  __Anticipated Assertion Firing Frequency:__ Occasional
 895  *
 896  *  @param[in]  aCondition  A Boolean expression to be evaluated.
 897  *  @param[in]  aLabel      The local label to which execution branches
 898  *                          when @p aCondition evaluates to false (i.e.
 899  *                          compares equal to zero).
 900  *  @param[in]  aMessage    A pointer to a NULL-terminated C string
 901  *                          containing a caller-specified message
 902  *                          further describing the assertion failure.
 903  *
 904  *  @sa #NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS
 905  *  @sa #NL_ASSERT_DESIRE_PRODUCTION_FLAGS
 906  *
 907  *  @sa #nlDESIRE_PRINT
 908  *  @sa #nlNEXPECT_PRINT
 909  *  @sa #nlNREQUIRE_PRINT
 910  *
 911  */
 912 #define nlNDESIRE_PRINT(aCondition, aLabel, aMessage)                           __nlNEXPECT_PRINT(NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS, aCondition, aLabel, aMessage)
 913
 914 /**
 915  *  @def nlNDESIRE_ACTION(aCondition, aLabel, anAction)
 916  *
 917  *  @brief
 918  *    This checks for the specified condition, which is expected to
 919  *    commonly be false, and both executes @p anAction and branches to
 920  *    @p aLabel if the condition is true.
 921  *
 922  *  @note This is the logical inverse of #nlDESIRE_ACTION.
 923  *
 924  *  __Anticipated Assertion Firing Frequency:__ Occasional
 925  *
 926  *  @param[in]  aCondition  A Boolean expression to be evaluated.
 927  *  @param[in]  aLabel      The local label to which execution branches
 928  *                          when @p aCondition evaluates to false (i.e.
 929  *                          compares equal to zero).
 930  *  @param[in]  anAction    An expression or block to execute when the
 931  *                          assertion fails. This will be executed
 932  *                          after #NL_ASSERT_LOG() and
 933  *                          #NL_ASSERT_BACKTRACE() but before
 934  *                          #NL_ASSERT_TRAP().
 935  *
 936  *  @sa #NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS
 937  *  @sa #NL_ASSERT_DESIRE_PRODUCTION_FLAGS
 938  *
 939  *  @sa #nlDESIRE_ACTION
 940  *  @sa #nlNEXPECT_ACTION
 941  *  @sa #nlNREQUIRE_ACTION
 942  *
 943  */
 944 #define nlNDESIRE_ACTION(aCondition, aLabel, anAction)                          __nlNEXPECT_ACTION(NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS, aCondition, aLabel, anAction)
 945
 946 /**
 947  *  @def nlNDESIRE_ACTION_PRINT(aCondition, aLabel, anAction, aMessage)
 948  *
 949  *  @brief
 950  *    This checks for the specified condition, which is expected to
 951  *    commonly be false, prints @p aMessage, executes @p anAction, and
 952  *    branches to @p aLabel if the condition is true.
 953  *
 954  *  @note This is the logical inverse of #nlDESIRE_ACTION_PRINT.
 955  *
 956  *  __Anticipated Assertion Firing Frequency:__ Occasional
 957  *
 958  *  @param[in]  aCondition  A Boolean expression to be evaluated.
 959  *  @param[in]  aLabel      The local label to which execution branches
 960  *                          when @p aCondition evaluates to false (i.e.
 961  *                          compares equal to zero).
 962  *  @param[in]  anAction    An expression or block to execute when the
 963  *                          assertion fails. This will be executed
 964  *                          after #NL_ASSERT_LOG() and
 965  *                          #NL_ASSERT_BACKTRACE() but before
 966  *                          #NL_ASSERT_TRAP().
 967  *  @param[in]  aMessage    A pointer to a NULL-terminated C string
 968  *                          containing a caller-specified message
 969  *                          further describing the assertion failure.
 970  *
 971  *  @sa #NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS
 972  *  @sa #NL_ASSERT_DESIRE_PRODUCTION_FLAGS
 973  *
 974  *  @sa #nlDESIRE_ACTION_PRINT
 975  *  @sa #nlNEXPECT_ACTION_PRINT
 976  *  @sa #nlNREQUIRE_ACTION_PRINT
 977  *
 978  */
 979 #define nlNDESIRE_ACTION_PRINT(aCondition, aLabel, anAction, aMessage)          __nlNEXPECT_ACTION_PRINT(NL_ASSERT_DESIRE_NONPRODUCTION_FLAGS, aCondition, aLabel, anAction, aMessage)
 980
 981 /**
 982  *  @}
 983  *
 984  */
 985
 986 /**
 987  *  @ingroup require-style
 988  *
 989  *  @{
 990  *
 991  */
 992
 993 /**
 994  *  @def NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS_DEFAULT
 995  *
 996  *  @brief
 997  *    This defines the default behavioral flags for require-style
 998  *    exception family assertions when #NL_ASSERT_PRODUCTION is
 999  *    disabled.
1000  *
1001  *  This may be used to override #NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS as follows:
1002  *
1003  *  @code
1004  *    #define NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS_DEFAULT
1005  *
1006  *    #include <nlassert.h>
1007  *  @endcode
1008  *
1009  *  @sa #NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS
1010  *
1011  *  @sa #NL_ASSERT_PRODUCTION
1012  *
1013  *  @sa #NL_ASSERT_FLAG_BACKTRACE
1014  *  @sa #NL_ASSERT_FLAG_LOG
1015  *  @sa #NL_ASSERT_FLAG_TRAP
1016  *
1017  */
1018 #define NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS_DEFAULT                           (NL_ASSERT_FLAG_BACKTRACE | NL_ASSERT_FLAG_LOG | NL_ASSERT_FLAG_TRAP)
1019
1020 /**
1021  *  @def NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS
1022  *
1023  *  @brief
1024  *    This defines the behavioral flags when #NL_ASSERT_PRODUCTION is
1025  *    disabled that govern the behavior for require-style exception
1026  *    family assertions when the assertion expression evaluates to
1027  *    false.
1028  *
1029  *  @sa #NL_ASSERT_USE_FLAGS_DEFAULT
1030  *
1031  *  @sa #NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS_DEFAULT
1032  *
1033  *  @sa #NL_ASSERT_PRODUCTION
1034  *
1035  *  @sa #NL_ASSERT_FLAG_BACKTRACE
1036  *  @sa #NL_ASSERT_FLAG_LOG
1037  *  @sa #NL_ASSERT_FLAG_TRAP
1038  */
1039 #if NL_ASSERT_USE_FLAGS_DEFAULT
1040 #define NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS                                   NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS_DEFAULT
1041 #elif !defined(NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS)
1042 #define NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS                                   (NL_ASSERT_FLAG_NONE)
1043 #endif
1044
1045 /**
1046  *  @def nlREQUIRE(aCondition, aLabel)
1047  *
1048  *  @brief
1049  *    This checks for the specified condition, which is expected to
1050  *    commonly be true, and branches to @p aLabel if the condition is
1051  *    false.
1052  *
1053  *  __Anticipated Assertion Firing Frequency:__ Rare
1054  *
1055  *  @param[in]  aCondition  A Boolean expression to be evaluated.
1056  *  @param[in]  aLabel      The local label to which execution branches
1057  *                          when @p aCondition evaluates to false (i.e.
1058  *                          compares equal to zero).
1059  *
1060  *  @sa #NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS
1061  *  @sa #NL_ASSERT_REQUIRE_PRODUCTION_FLAGS
1062  *
1063  *  @sa #nlEXPECT
1064  *  @sa #nlDESIRE
1065  *
1066  */
1067 #define nlREQUIRE(aCondition, aLabel)                                           __nlEXPECT(NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS, aCondition, aLabel)
1068
1069 /**
1070  *  @def nlREQUIRE_PRINT(aCondition, aLabel, aMessage)
1071  *
1072  *  @brief
1073  *    This checks for the specified condition, which is expected to
1074  *    commonly be true, and both prints @p aMessage and then branches
1075  *    to @p aLabel if the condition is false.
1076  *
1077  *  __Anticipated Assertion Firing Frequency:__ Rare
1078  *
1079  *  @param[in]  aCondition  A Boolean expression to be evaluated.
1080  *  @param[in]  aLabel      The local label to which execution branches
1081  *                          when @p aCondition evaluates to false (i.e.
1082  *                          compares equal to zero).
1083  *  @param[in]  aMessage    A pointer to a NULL-terminated C string
1084  *                          containing a caller-specified message
1085  *                          further describing the assertion failure.
1086  *
1087  *  @sa #NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS
1088  *  @sa #NL_ASSERT_REQUIRE_PRODUCTION_FLAGS
1089  *
1090  *  @sa #nlEXPECT_PRINT
1091  *  @sa #nlDESIRE_PRINT
1092  *
1093  */
1094 #define nlREQUIRE_PRINT(aCondition, aLabel, aMessage)                           __nlEXPECT_PRINT(NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS, aCondition, aLabel, aMessage)
1095
1096 /**
1097  *  @def nlREQUIRE_ACTION(aCondition, aLabel, anAction)
1098  *
1099  *  @brief
1100  *    This checks for the specified condition, which is expected to
1101  *    commonly be true, and both executes @p anAction and branches to
1102  *    @p aLabel if the condition is false.
1103  *
1104  *  __Anticipated Assertion Firing Frequency:__ Rare
1105  *
1106  *  @param[in]  aCondition  A Boolean expression to be evaluated.
1107  *  @param[in]  aLabel      The local label to which execution branches
1108  *                          when @p aCondition evaluates to false (i.e.
1109  *                          compares equal to zero).
1110  *  @param[in]  anAction    An expression or block to execute when the
1111  *                          assertion fails. This will be executed
1112  *                          after #NL_ASSERT_LOG() and
1113  *                          #NL_ASSERT_BACKTRACE() but before
1114  *                          #NL_ASSERT_TRAP().
1115  *
1116  *  @sa #NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS
1117  *  @sa #NL_ASSERT_REQUIRE_PRODUCTION_FLAGS
1118  *
1119  *  @sa #nlEXPECT_ACTION
1120  *  @sa #nlDESIRE_ACTION
1121  *
1122  */
1123 #define nlREQUIRE_ACTION(aCondition, aLabel, anAction)                          __nlEXPECT_ACTION(NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS, aCondition, aLabel, anAction)
1124
1125 /**
1126  *  @def nlREQUIRE_ACTION_PRINT(aCondition, aLabel, anAction, aMessage)
1127  *
1128  *  @brief
1129  *    This checks for the specified condition, which is expected to
1130  *    commonly be true, prints @p aMessage, executes @p anAction, and
1131  *    branches to @p aLabel if the condition is false.
1132  *
1133  *  __Anticipated Assertion Firing Frequency:__ Rare
1134  *
1135  *  @param[in]  aCondition  A Boolean expression to be evaluated.
1136  *  @param[in]  aLabel      The local label to which execution branches
1137  *                          when @p aCondition evaluates to false (i.e.
1138  *                          compares equal to zero).
1139  *  @param[in]  anAction    An expression or block to execute when the
1140  *                          assertion fails. This will be executed
1141  *                          after #NL_ASSERT_LOG() and
1142  *                          #NL_ASSERT_BACKTRACE() but before
1143  *                          #NL_ASSERT_TRAP().
1144  *  @param[in]  aMessage    A pointer to a NULL-terminated C string
1145  *                          containing a caller-specified message
1146  *                          further describing the assertion failure.
1147  *
1148  *  @sa #NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS
1149  *  @sa #NL_ASSERT_REQUIRE_PRODUCTION_FLAGS
1150  *
1151  *  @sa #nlEXPECT_ACTION_PRINT
1152  *  @sa #nlDESIRE_ACTION_PRINT
1153  *
1154  */
1155 #define nlREQUIRE_ACTION_PRINT(aCondition, aLabel, anAction, aMessage)          __nlEXPECT_ACTION_PRINT(NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS, aCondition, aLabel, anAction, aMessage)
1156
1157 /**
1158  *  @def nlREQUIRE_SUCCESS(aStatus, aLabel)
1159  *
1160  *  @brief
1161  *    This checks for the specified status, which is expected to
1162  *    commonly be successful (i.e. zero (0)), and branches to @p
1163  *    aLabel if the status is unsuccessful.
1164  *
1165  *  __Anticipated Assertion Firing Frequency:__ Rare
1166  *
1167  *  @param[in]  aStatus     A scalar status to be evaluated against zero (0).
1168  *  @param[in]  aLabel      The local label to which execution branches
1169  *                          when @p aStatus does not evaluate to zero
1170  *                          (0).
1171  *
1172  *  @sa #NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS
1173  *  @sa #NL_ASSERT_REQUIRE_PRODUCTION_FLAGS
1174  *
1175  *  @sa #nlEXPECT_SUCCESS
1176  *  @sa #nlDESIRE_SUCCESS
1177  *
1178  */
1179 #define nlREQUIRE_SUCCESS(aStatus, aLabel)                                      __nlEXPECT_SUCCESS(NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS, aStatus, aLabel)
1180
1181 /**
1182  *  @def nlREQUIRE_SUCCESS_PRINT(aStatus, aLabel, aMessage)
1183  *
1184  *  @brief
1185  *    This checks for the specified status, which is expected to
1186  *    commonly be successful (i.e. zero (0)), and both prints @p
1187  *    aMessage and then branches to @p aLabel if the status is
1188  *    unsuccessful.
1189  *
1190  *  __Anticipated Assertion Firing Frequency:__ Rare
1191  *
1192  *  @param[in]  aStatus     A scalar status to be evaluated against zero (0).
1193  *  @param[in]  aLabel      The local label to which execution branches
1194  *                          when @p aStatus does not evaluate to zero
1195  *                          (0).
1196  *  @param[in]  aMessage    A pointer to a NULL-terminated C string
1197  *                          containing a caller-specified message
1198  *                          further describing the assertion failure.
1199  *
1200  *  @sa #NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS
1201  *  @sa #NL_ASSERT_REQUIRE_PRODUCTION_FLAGS
1202  *
1203  *  @sa #nlEXPECT_SUCCESS_PRINT
1204  *  @sa #nlDESIRE_SUCCESS_PRINT
1205  *
1206  */
1207 #define nlREQUIRE_SUCCESS_PRINT(aStatus, aLabel, aMessage)                      __nlEXPECT_SUCCESS_PRINT(NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS, aStatus, aLabel, aMessage)
1208
1209 /**
1210  *  @def nlREQUIRE_SUCCESS_ACTION(aStatus, aLabel, anAction)
1211  *
1212  *  @brief
1213  *    This checks for the specified status, which is expected to
1214  *    commonly be successful (i.e. zero (0)), and both executes @p
1215  *    anAction and branches to @p aLabel if the status is
1216  *    unsuccessful.
1217  *
1218  *  __Anticipated Assertion Firing Frequency:__ Rare
1219  *
1220  *  @param[in]  aStatus     A scalar status to be evaluated against zero (0).
1221  *  @param[in]  aLabel      The local label to which execution branches
1222  *                          when @p aStatus does not evaluate to zero
1223  *                          (0).
1224  *  @param[in]  anAction    An expression or block to execute when the
1225  *                          assertion fails. This will be executed
1226  *                          after #NL_ASSERT_LOG() and
1227  *                          #NL_ASSERT_BACKTRACE() but before
1228  *                          #NL_ASSERT_TRAP().
1229  *
1230  *  @sa #NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS
1231  *  @sa #NL_ASSERT_REQUIRE_PRODUCTION_FLAGS
1232  *
1233  *  @sa #nlEXPECT_SUCCESS_ACTION
1234  *  @sa #nlDESIRE_SUCCESS_ACTION
1235  *
1236  */
1237 #define nlREQUIRE_SUCCESS_ACTION(aStatus, aLabel, anAction)                     __nlEXPECT_SUCCESS_ACTION(NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS, aStatus, aLabel, anAction)
1238
1239 /**
1240  *  @def nlREQUIRE_SUCCESS_ACTION_PRINT(aStatus, aLabel, anAction, aMessage)
1241  *
1242  *  @brief
1243  *    This checks for the specified status, which is expected to
1244  *    commonly be successful (i.e. zero (0)), prints @p aMessage,
1245  *    executes @p anAction, and branches to @p aLabel if the status is
1246  *    unsuccessful.
1247  *
1248  *  __Anticipated Assertion Firing Frequency:__ Rare
1249  *
1250  *  @param[in]  aStatus     A scalar status to be evaluated against zero (0).
1251  *  @param[in]  aLabel      The local label to which execution branches
1252  *                          when @p aStatus does not evaluate to zero
1253  *                          (0).
1254  *  @param[in]  anAction    An expression or block to execute when the
1255  *                          assertion fails. This will be executed
1256  *                          after #NL_ASSERT_LOG() and
1257  *                          #NL_ASSERT_BACKTRACE() but before
1258  *                          #NL_ASSERT_TRAP().
1259  *  @param[in]  aMessage    A pointer to a NULL-terminated C string
1260  *                          containing a caller-specified message
1261  *                          further describing the assertion failure.
1262  *
1263  *  @sa #NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS
1264  *  @sa #NL_ASSERT_REQUIRE_PRODUCTION_FLAGS
1265  *
1266  *  @sa #nlEXPECT_SUCCESS_ACTION_PRINT
1267  *  @sa #nlDESIRE_SUCCESS_ACTION_PRINT
1268  *
1269  */
1270 #define nlREQUIRE_SUCCESS_ACTION_PRINT(aStatus, aLabel, anAction, aMessage)     __nlEXPECT_SUCCESS_ACTION_PRINT(NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS, aStatus, aLabel, anAction, aMessage)
1271
1272 /**
1273  *  @def nlNREQUIRE(aCondition, aLabel)
1274  *
1275  *  @brief
1276  *    This checks for the specified condition, which is expected to
1277  *    commonly be false, and branches to @p aLabel if the condition is
1278  *    true.
1279  *
1280  *  @note This is the logical inverse of #nlREQUIRE.
1281  *
1282  *  __Anticipated Assertion Firing Frequency:__ Rare
1283  *
1284  *  @param[in]  aCondition  A Boolean expression to be evaluated.
1285  *  @param[in]  aLabel      The local label to which execution branches
1286  *                          when @p aCondition evaluates to false (i.e.
1287  *                          compares equal to zero).
1288  *
1289  *  @sa #NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS
1290  *  @sa #NL_ASSERT_REQUIRE_PRODUCTION_FLAGS
1291  *
1292  *  @sa #nlREQUIRE
1293  *  @sa #nlNEXPECT
1294  *  @sa #nlNDESIRE
1295  *
1296  */
1297 #define nlNREQUIRE(aCondition, aLabel)                                          __nlNEXPECT(NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS, aCondition, aLabel)
1298
1299 /**
1300  *  @def nlNREQUIRE_PRINT(aCondition, aLabel, aMessage)
1301  *
1302  *  @brief
1303  *    This checks for the specified condition, which is expected to
1304  *    commonly be false, and both prints @p aMessage and then branches
1305  *    to @p aLabel if the condition is true.
1306  *
1307  *  @note This is the logical inverse of #nlREQUIRE_PRINT.
1308  *
1309  *  __Anticipated Assertion Firing Frequency:__ Rare
1310  *
1311  *  @param[in]  aCondition  A Boolean expression to be evaluated.
1312  *  @param[in]  aLabel      The local label to which execution branches
1313  *                          when @p aCondition evaluates to false (i.e.
1314  *                          compares equal to zero).
1315  *  @param[in]  aMessage    A pointer to a NULL-terminated C string
1316  *                          containing a caller-specified message
1317  *                          further describing the assertion failure.
1318  *
1319  *  @sa #NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS
1320  *  @sa #NL_ASSERT_REQUIRE_PRODUCTION_FLAGS
1321  *
1322  *  @sa #nlREQUIRE_PRINT
1323  *  @sa #nlNEXPECT_PRINT
1324  *  @sa #nlNDESIRE_PRINT
1325  *
1326  */
1327 #define nlNREQUIRE_PRINT(aCondition, aLabel, aMessage)                          __nlNEXPECT_PRINT(NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS, aCondition, aLabel, aMessage)
1328
1329 /**
1330  *  @def nlNREQUIRE_ACTION(aCondition, aLabel, anAction)
1331  *
1332  *  @brief
1333  *    This checks for the specified condition, which is expected to
1334  *    commonly be false, and both executes @p anAction and branches to
1335  *    @p aLabel if the condition is true.
1336  *
1337  *  @note This is the logical inverse of #nlREQUIRE_ACTION.
1338  *
1339  *  __Anticipated Assertion Firing Frequency:__ Rare
1340  *
1341  *  @param[in]  aCondition  A Boolean expression to be evaluated.
1342  *  @param[in]  aLabel      The local label to which execution branches
1343  *                          when @p aCondition evaluates to false (i.e.
1344  *                          compares equal to zero).
1345  *  @param[in]  anAction    An expression or block to execute when the
1346  *                          assertion fails. This will be executed
1347  *                          after #NL_ASSERT_LOG() and
1348  *                          #NL_ASSERT_BACKTRACE() but before
1349  *                          #NL_ASSERT_TRAP().
1350  *
1351  *  @sa #NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS
1352  *  @sa #NL_ASSERT_REQUIRE_PRODUCTION_FLAGS
1353  *
1354  *  @sa #nlREQUIRE_ACTION
1355  *  @sa #nlNEXPECT_ACTION
1356  *  @sa #nlNDESIRE_ACTION
1357  *
1358  */
1359 #define nlNREQUIRE_ACTION(aCondition, aLabel, anAction)                         __nlNEXPECT_ACTION(NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS, aCondition, aLabel, anAction)
1360
1361 /**
1362  *  @def nlNREQUIRE_ACTION_PRINT(aCondition, aLabel, anAction, aMessage)
1363  *
1364  *  @brief
1365  *    This checks for the specified condition, which is expected to
1366  *    commonly be false, prints @p aMessage, executes @p anAction, and
1367  *    branches to @p aLabel if the condition is true.
1368  *
1369  *  @note This is the logical inverse of #nlREQUIRE_ACTION_PRINT.
1370  *
1371  *  __Anticipated Assertion Firing Frequency:__ Rare
1372  *
1373  *  @param[in]  aCondition  A Boolean expression to be evaluated.
1374  *  @param[in]  aLabel      The local label to which execution branches
1375  *                          when @p aCondition evaluates to false (i.e.
1376  *                          compares equal to zero).
1377  *  @param[in]  anAction    An expression or block to execute when the
1378  *                          assertion fails. This will be executed
1379  *                          after #NL_ASSERT_LOG() and
1380  *                          #NL_ASSERT_BACKTRACE() but before
1381  *                          #NL_ASSERT_TRAP().
1382  *  @param[in]  aMessage    A pointer to a NULL-terminated C string
1383  *                          containing a caller-specified message
1384  *                          further describing the assertion failure.
1385  *
1386  *  @sa #NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS
1387  *  @sa #NL_ASSERT_REQUIRE_PRODUCTION_FLAGS
1388  *
1389  *  @sa #nlREQUIRE_ACTION_PRINT
1390  *  @sa #nlNEXPECT_ACTION_PRINT
1391  *  @sa #nlNDESIRE_ACTION_PRINT
1392  *
1393  */
1394 #define nlNREQUIRE_ACTION_PRINT(aCondition, aLabel, anAction, aMessage)         __nlNEXPECT_ACTION_PRINT(NL_ASSERT_REQUIRE_NONPRODUCTION_FLAGS, aCondition, aLabel, anAction, aMessage)
1395
1396 /**
1397  *  @}
1398  *
1399  */
1400
1401 /**
1402  *  @ingroup precondition-style
1403  *
1404  *  @{
1405  *
1406  */
1407
1408 /**
1409  *  @def NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS_DEFAULT
1410  *
1411  *  @brief
1412  *    This defines the default behavioral flags for precondition-style
1413  *    exception family assertions when #NL_ASSERT_PRODUCTION is
1414  *    disabled.
1415  *
1416  *  This may be used to override #NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS as follows:
1417  *
1418  *  @code
1419  *    #define NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS_DEFAULT
1420  *
1421  *    #include <nlassert.h>
1422  *  @endcode
1423  *
1424  *  @sa #NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS
1425  *
1426  *  @sa #NL_ASSERT_PRODUCTION
1427  *
1428  *  @sa #NL_ASSERT_FLAG_BACKTRACE
1429  *  @sa #NL_ASSERT_FLAG_LOG
1430  *  @sa #NL_ASSERT_FLAG_TRAP
1431  *
1432  */
1433 #define NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS_DEFAULT                      (NL_ASSERT_FLAG_BACKTRACE | NL_ASSERT_FLAG_LOG | NL_ASSERT_FLAG_TRAP)
1434
1435 /**
1436  *  @def NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS
1437  *
1438  *  @brief
1439  *    This defines the behavioral flags when #NL_ASSERT_PRODUCTION is
1440  *    disabled that govern the behavior for precondition-style exception
1441  *    family assertions when the assertion expression evaluates to
1442  *    false.
1443  *
1444  *  @sa #NL_ASSERT_USE_FLAGS_DEFAULT
1445  *
1446  *  @sa #NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS_DEFAULT
1447  *
1448  *  @sa #NL_ASSERT_PRODUCTION
1449  *
1450  *  @sa #NL_ASSERT_FLAG_BACKTRACE
1451  *  @sa #NL_ASSERT_FLAG_LOG
1452  *  @sa #NL_ASSERT_FLAG_TRAP
1453  */
1454 #if NL_ASSERT_USE_FLAGS_DEFAULT
1455 #define NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS                              NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS_DEFAULT
1456 #elif !defined(NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS)
1457 #define NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS                              (NL_ASSERT_FLAG_NONE)
1458 #endif
1459
1460 /**
1461  *  @def nlPRECONDITION(aCondition)
1462  *
1463  *  @brief
1464  *    This checks for the specified condition, which is expected to
1465  *    commonly be true, and returns from the enclosing function if the
1466  *    condition is false.
1467  *
1468  *  @param[in]  aCondition  A Boolean expression to be evaluated.
1469  *
1470  *  @sa #NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS
1471  *  @sa #NL_ASSERT_PRECONDITION_PRODUCTION_FLAGS
1472  *
1473  *  @sa #nlEXPECT
1474  *  @sa #nlDESIRE
1475  *  @sa #nlREQUIRE
1476  *
1477  */
1478 #define nlPRECONDITION(aCondition)                                              __nlPRECONDITION(NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS, aCondition, return)
1479
1480 /**
1481  *  @def nlPRECONDITION_ACTION(aCondition, anAction)
1482  *
1483  *  @brief
1484  *    This checks for the specified condition, which is expected to
1485  *    commonly be true, and both executes @p anAction and returns from
1486  *    the enclosing function if the condition is false.
1487  *
1488  *  @param[in]  aCondition  A Boolean expression to be evaluated.
1489  *  @param[in]  anAction    An expression or block to execute when the
1490  *                          assertion fails. This will be executed
1491  *                          after #NL_ASSERT_LOG() and
1492  *                          #NL_ASSERT_BACKTRACE() but before
1493  *                          #NL_ASSERT_TRAP().
1494  *
1495  *  @sa #NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS
1496  *  @sa #NL_ASSERT_PRECONDITION_PRODUCTION_FLAGS
1497  *
1498  *  @sa #nlEXPECT_ACTION
1499  *  @sa #nlDESIRE_ACTION
1500  *  @sa #nlREQUIRE_ACTION
1501  *
1502  */
1503 #define nlPRECONDITION_ACTION(aCondition, anAction)                             __nlPRECONDITION_ACTION(NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS, aCondition, return, anAction)
1504
1505 /**
1506  *  @def nlPRECONDITION_PRINT(aCondition, aMessage)
1507  *
1508  *  @brief
1509  *    This checks for the specified condition, which is expected to
1510  *    commonly be true, and both prints @p aMessage and then returns
1511  *    from the enclosing function if the condition is false.
1512  *
1513  *  @param[in]  aCondition  A Boolean expression to be evaluated.
1514  *  @param[in]  aMessage    A pointer to a NULL-terminated C string
1515  *                          containing a caller-specified message
1516  *                          further describing the assertion failure.
1517  *
1518  *  @sa #NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS
1519  *  @sa #NL_ASSERT_PRECONDITION_PRODUCTION_FLAGS
1520  *
1521  *  @sa #nlEXPECT_PRINT
1522  *  @sa #nlDESIRE_PRINT
1523  *  @sa #nlREQUIRE_PRINT
1524  *
1525  */
1526 #define nlPRECONDITION_PRINT(aCondition, aMessage)                              __nlPRECONDITION_PRINT(NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS, aCondition, return, aMessage)
1527
1528 /**
1529  *  @def nlPRECONDITION_SUCCESS(aStatus)
1530  *
1531  *  @brief
1532  *    This checks for the specified status, which is expected to
1533  *    commonly be successful (i.e. zero (0)), and returns from the
1534  *    enclosing function if the status is unsuccessful.
1535  *
1536  *  @param[in]  aStatus     A scalar status to be evaluated against zero (0).
1537  *
1538  *  @sa #NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS
1539  *  @sa #NL_ASSERT_PRECONDITION_PRODUCTION_FLAGS
1540  *
1541  *  @sa #nlEXPECT_SUCCESS
1542  *  @sa #nlDESIRE_SUCCESS
1543  *  @sa #nlREQUIRE_SUCCESS
1544  *
1545  */
1546 #define nlPRECONDITION_SUCCESS(aStatus)                                         __nlPRECONDITION_SUCCESS(NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS, aStatus, return)
1547
1548 /**
1549  *  @def nlPRECONDITION_SUCCESS_ACTION(aStatus, anAction)
1550  *
1551  *  @brief
1552  *    This checks for the specified status, which is expected to
1553  *    commonly be successful (i.e. zero (0)), and both executes @p
1554  *    anAction and returns from the enclosing function if the status
1555  *    is unsuccessful.
1556  *
1557  *  @param[in]  aStatus     A scalar status to be evaluated against zero (0).
1558  *  @param[in]  anAction    An expression or block to execute when the
1559  *                          assertion fails. This will be executed
1560  *                          after #NL_ASSERT_LOG() and
1561  *                          #NL_ASSERT_BACKTRACE() but before
1562  *                          #NL_ASSERT_TRAP().
1563  *
1564  *  @sa #NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS
1565  *  @sa #NL_ASSERT_PRECONDITION_PRODUCTION_FLAGS
1566  *
1567  *  @sa #nlEXPECT_SUCCESS_ACTION
1568  *  @sa #nlDESIRE_SUCCESS_ACTION
1569  *  @sa #nlREQUIRE_SUCCESS_ACTION
1570  *
1571  */
1572 #define nlPRECONDITION_SUCCESS_ACTION(aStatus, anAction)                        __nlPRECONDITION_SUCCESS_ACTION(NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS, aStatus, return, anAction)
1573
1574 /**
1575  *  @def nlPRECONDITION_SUCCESS_PRINT(aStatus, aMessage)
1576  *
1577  *  @brief
1578  *    This checks for the specified status, which is expected to
1579  *    commonly be successful (i.e. zero (0)), and both prints @p
1580  *    aMessage and then returns from the enclosing function if the
1581  *    status is unsuccessful.
1582  *
1583  *  @param[in]  aStatus     A scalar status to be evaluated against zero (0).
1584  *  @param[in]  aMessage    A pointer to a NULL-terminated C string
1585  *                          containing a caller-specified message
1586  *                          further describing the assertion failure.
1587  *
1588  *  @sa #NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS
1589  *  @sa #NL_ASSERT_PRECONDITION_PRODUCTION_FLAGS
1590  *
1591  *  @sa #nlEXPECT_SUCCESS_PRINT
1592  *  @sa #nlDESIRE_SUCCESS_PRINT
1593  *  @sa #nlREQUIRE_SUCCESS_PRINT
1594  *
1595  */
1596 #define nlPRECONDITION_SUCCESS_PRINT(aStatus, aMessage)                         __nlPRECONDITION_SUCCESS_PRINT(NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS, aStatus, return, aMessage)
1597
1598 /**
1599  *  @def nlNPRECONDITION(aCondition)
1600  *
1601  *  @brief
1602  *    This checks for the specified condition, which is expected to
1603  *    commonly be false, and returns from the enclosing function if
1604  *    the condition is true.
1605  *
1606  *  @note This is the logical inverse of #nlPRECONDITION.
1607  *
1608  *  @param[in]  aCondition  A Boolean expression to be evaluated.
1609  *
1610  *  @sa #NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS
1611  *  @sa #NL_ASSERT_PRECONDITION_PRODUCTION_FLAGS
1612  *
1613  *  @sa #nlPRECONDITION
1614  *
1615  *  @sa #nlNEXPECT
1616  *  @sa #nlNDESIRE
1617  *  @sa #nlNREQUIRE
1618  *
1619  */
1620 #define nlNPRECONDITION(aCondition)                                             __nlNPRECONDITION(NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS, aCondition, return)
1621
1622 /**
1623  *  @def nlNPRECONDITION_ACTION(aCondition, anAction)
1624  *
1625  *  @brief
1626  *    This checks for the specified condition, which is expected to
1627  *    commonly be false, and both executes @p anAction and returns from
1628  *    the enclosing function if the condition is true.
1629  *
1630  *  @note This is the logical inverse of #nlPRECONDITION_ACTION.
1631  *
1632  *  @param[in]  aCondition  A Boolean expression to be evaluated.
1633  *  @param[in]  anAction    An expression or block to execute when the
1634  *                          assertion fails. This will be executed
1635  *                          after #NL_ASSERT_LOG() and
1636  *                          #NL_ASSERT_BACKTRACE() but before
1637  *                          #NL_ASSERT_TRAP().
1638  *
1639  *  @sa #NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS
1640  *  @sa #NL_ASSERT_PRECONDITION_PRODUCTION_FLAGS
1641  *
1642  *  @sa #nlPRECONDITION_ACTION
1643  *
1644  *  @sa #nlNEXPECT_ACTION
1645  *  @sa #nlNDESIRE_ACTION
1646  *  @sa #nlNREQUIRE_ACTION
1647  *
1648  */
1649 #define nlNPRECONDITION_ACTION(aCondition, anAction)                            __nlNPRECONDITION_ACTION(NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS, aCondition, return, anAction)
1650
1651 /**
1652  *  @def nlNPRECONDITION_PRINT(aCondition, aMessage)
1653  *
1654  *  @brief
1655  *    This checks for the specified condition, which is expected to
1656  *    commonly be false, and both prints @p aMessage and then returns
1657  *    from the enclosing function if the condition is true.
1658  *
1659  *  @note This is the logical inverse of #nlPRECONDITION_PRINT.
1660  *
1661  *  @param[in]  aCondition  A Boolean expression to be evaluated.
1662  *  @param[in]  aMessage    A pointer to a NULL-terminated C string
1663  *                          containing a caller-specified message
1664  *                          further describing the assertion failure.
1665  *
1666  *  @sa #NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS
1667  *  @sa #NL_ASSERT_PRECONDITION_PRODUCTION_FLAGS
1668  *
1669  *  @sa #nlPRECONDITION_PRINT
1670  *
1671  *  @sa #nlNEXPECT_PRINT
1672  *  @sa #nlNDESIRE_PRINT
1673  *  @sa #nlNREQUIRE_PRINT
1674  *
1675  */
1676 #define nlNPRECONDITION_PRINT(aCondition, aMessage)                             __nlNPRECONDITION_PRINT(NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS, aCondition, return, aMessage)
1677
1678 /**
1679  *  @def nlPRECONDITION_VALUE(aCondition, aValue)
1680  *
1681  *  @brief
1682  *    This checks for the specified condition, which is expected to
1683  *    commonly be true, and returns @p aValue from the enclosing
1684  *    function if the condition is false.
1685  *
1686  *  @param[in]  aCondition  A Boolean expression to be evaluated.
1687  *  @param[in]  aValue      The value to be returned when the assertion
1688  *                          fails.
1689  *
1690  *  @sa #NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS
1691  *  @sa #NL_ASSERT_PRECONDITION_PRODUCTION_FLAGS
1692  *
1693  *  @sa #nlEXPECT
1694  *  @sa #nlDESIRE
1695  *  @sa #nlREQUIRE
1696  *
1697  */
1698 #define nlPRECONDITION_VALUE(aCondition, aValue)                                __nlPRECONDITION(NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS, aCondition, return aValue)
1699
1700 /**
1701  *  @def nlPRECONDITION_VALUE_ACTION(aCondition, aValue, anAction)
1702  *
1703  *  @brief
1704  *    This checks for the specified condition, which is expected to
1705  *    commonly be true, and both executes @p anAction and returns @p
1706  *    aValue from the enclosing function if the condition is false.
1707  *
1708  *  @param[in]  aCondition  A Boolean expression to be evaluated.
1709  *  @param[in]  aValue      The value to be returned when the assertion
1710  *                          fails.
1711  *  @param[in]  anAction    An expression or block to execute when the
1712  *                          assertion fails. This will be executed
1713  *                          after #NL_ASSERT_LOG() and
1714  *                          #NL_ASSERT_BACKTRACE() but before
1715  *                          #NL_ASSERT_TRAP().
1716  *
1717  *  @sa #NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS
1718  *  @sa #NL_ASSERT_PRECONDITION_PRODUCTION_FLAGS
1719  *
1720  *  @sa #nlEXPECT_ACTION
1721  *  @sa #nlDESIRE_ACTION
1722  *  @sa #nlREQUIRE_ACTION
1723  *
1724  */
1725 #define nlPRECONDITION_VALUE_ACTION(aCondition, aValue, anAction)               __nlPRECONDITION_ACTION(NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS, aCondition, return aValue, anAction)
1726
1727 /**
1728  *  @def nlPRECONDITION_VALUE_PRINT(aCondition, aValue, aMessage)
1729  *
1730  *  @brief
1731  *    This checks for the specified condition, which is expected to
1732  *    commonly be true, and both prints @p aMessage and then returns
1733  *    @p aValue from the enclosing function if the condition is false.
1734  *
1735  *  @param[in]  aCondition  A Boolean expression to be evaluated.
1736  *  @param[in]  aValue      The value to be returned when the assertion
1737  *                          fails.
1738  *  @param[in]  aMessage    A pointer to a NULL-terminated C string
1739  *                          containing a caller-specified message
1740  *                          further describing the assertion failure.
1741  *
1742  *  @sa #NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS
1743  *  @sa #NL_ASSERT_PRECONDITION_PRODUCTION_FLAGS
1744  *
1745  *  @sa #nlEXPECT_PRINT
1746  *  @sa #nlDESIRE_PRINT
1747  *  @sa #nlREQUIRE_PRINT
1748  *
1749  */
1750 #define nlPRECONDITION_VALUE_PRINT(aCondition, aValue, aMessage)                __nlPRECONDITION_PRINT(NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS, aCondition, return aValue, aMessage)
1751
1752 /**
1753  *  @def nlPRECONDITION_VALUE_SUCCESS(aStatus, aValue)
1754  *
1755  *  @brief
1756  *    This checks for the specified status, which is expected to
1757  *    commonly be successful (i.e. zero (0)), and returns @p aValue
1758  *    from the enclosing function if the status is unsuccessful.
1759  *
1760  *  @param[in]  aStatus     A scalar status to be evaluated against zero (0).
1761  *  @param[in]  aValue      The value to be returned when the assertion
1762  *                          fails.
1763  *
1764  *  @sa #NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS
1765  *  @sa #NL_ASSERT_PRECONDITION_PRODUCTION_FLAGS
1766  *
1767  *  @sa #nlEXPECT_SUCCESS
1768  *  @sa #nlDESIRE_SUCCESS
1769  *  @sa #nlREQUIRE_SUCCESS
1770  *
1771  */
1772 #define nlPRECONDITION_VALUE_SUCCESS(aStatus, aValue)                           __nlPRECONDITION_SUCCESS(NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS, aStatus, return aValue)
1773
1774 /**
1775  *  @def nlPRECONDITION_VALUE_SUCCESS_ACTION(aStatus, aValue, anAction)
1776  *
1777  *  @brief
1778  *    This checks for the specified status, which is expected to
1779  *    commonly be successful (i.e. zero (0)), and both executes @p
1780  *    anAction and returns @p aValue from the enclosing function if
1781  *    the status is unsuccessful.
1782  *
1783  *  @param[in]  aStatus     A scalar status to be evaluated against zero (0).
1784  *  @param[in]  aValue      The value to be returned when the assertion
1785  *                          fails.
1786  *  @param[in]  anAction    An expression or block to execute when the
1787  *                          assertion fails. This will be executed
1788  *                          after #NL_ASSERT_LOG() and
1789  *                          #NL_ASSERT_BACKTRACE() but before
1790  *                          #NL_ASSERT_TRAP().
1791  *
1792  *  @sa #NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS
1793  *  @sa #NL_ASSERT_PRECONDITION_PRODUCTION_FLAGS
1794  *
1795  *  @sa #nlEXPECT_SUCCESS_ACTION
1796  *  @sa #nlDESIRE_SUCCESS_ACTION
1797  *  @sa #nlREQUIRE_SUCCESS_ACTION
1798  *
1799  */
1800 #define nlPRECONDITION_VALUE_SUCCESS_ACTION(aStatus, aValue, anAction)          __nlPRECONDITION_SUCCESS_ACTION(NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS, aStatus, return aValue, anAction)
1801
1802 /**
1803  *  @def nlPRECONDITION_VALUE_SUCCESS_PRINT(aStatus, aValue, aMessage)
1804  *
1805  *  @brief
1806  *    This checks for the specified status, which is expected to
1807  *    commonly be successful (i.e. zero (0)), and both prints @p
1808  *    aMessage and then returns @p aValue from the enclosing function
1809  *    if the status is unsuccessful.
1810  *
1811  *  @param[in]  aStatus     A scalar status to be evaluated against zero (0).
1812  *  @param[in]  aValue      The value to be returned when the assertion
1813  *                          fails.
1814  *  @param[in]  aMessage    A pointer to a NULL-terminated C string
1815  *                          containing a caller-specified message
1816  *                          further describing the assertion failure.
1817  *
1818  *  @sa #NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS
1819  *  @sa #NL_ASSERT_PRECONDITION_PRODUCTION_FLAGS
1820  *
1821  *  @sa #nlEXPECT_SUCCESS_PRINT
1822  *  @sa #nlDESIRE_SUCCESS_PRINT
1823  *  @sa #nlREQUIRE_SUCCESS_PRINT
1824  *
1825  */
1826 #define nlPRECONDITION_VALUE_SUCCESS_PRINT(aStatus, aValue, aMessage)           __nlPRECONDITION_SUCCESS_PRINT(NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS, aStatus, return aValue, aMessage)
1827
1828 /**
1829  *  @def nlNPRECONDITION_VALUE(aCondition, aValue)
1830  *
1831  *  @brief
1832  *    This checks for the specified condition, which is expected to
1833  *    commonly be false, and returns @p aValue from the enclosing
1834  *    function if the condition is true.
1835  *
1836  *  @note This is the logical inverse of #nlPRECONDITION_VALUE.
1837  *
1838  *  @param[in]  aCondition  A Boolean expression to be evaluated.
1839  *  @param[in]  aValue      The value to be returned when the assertion
1840  *                          fails.
1841  *
1842  *  @sa #NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS
1843  *  @sa #NL_ASSERT_PRECONDITION_PRODUCTION_FLAGS
1844  *
1845  *  @sa #nlPRECONDITION_VALUE
1846  *
1847  *  @sa #nlNEXPECT
1848  *  @sa #nlNDESIRE
1849  *  @sa #nlNREQUIRE
1850  *
1851  */
1852 #define nlNPRECONDITION_VALUE(aCondition, aValue)                               __nlNPRECONDITION(NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS, aCondition, return aValue)
1853
1854 /**
1855  *  @def nlNPRECONDITION_VALUE_ACTION(aCondition, aValue, anAction)
1856  *
1857  *  @brief
1858  *    This checks for the specified condition, which is expected to
1859  *    commonly be false, and both executes @p anAction and returns @p
1860  *    aValue from the enclosing function if the condition is true.
1861  *
1862  *  @note This is the logical inverse of #nlPRECONDITION_VALUE_ACTION.
1863  *
1864  *  @param[in]  aCondition  A Boolean expression to be evaluated.
1865  *  @param[in]  aValue      The value to be returned when the assertion
1866  *                          fails.
1867  *  @param[in]  anAction    An expression or block to execute when the
1868  *                          assertion fails. This will be executed
1869  *                          after #NL_ASSERT_LOG() and
1870  *                          #NL_ASSERT_BACKTRACE() but before
1871  *                          #NL_ASSERT_TRAP().
1872  *
1873  *  @sa #NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS
1874  *  @sa #NL_ASSERT_PRECONDITION_PRODUCTION_FLAGS
1875  *
1876  *  @sa #nlPRECONDITION_VALUE_ACTION
1877  *
1878  *  @sa #nlNEXPECT_ACTION
1879  *  @sa #nlNDESIRE_ACTION
1880  *  @sa #nlNREQUIRE_ACTION
1881  *
1882  */
1883 #define nlNPRECONDITION_VALUE_ACTION(aCondition, aValue, anAction)              __nlNPRECONDITION_ACTION(NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS, aCondition, return aValue, anAction)
1884
1885 /**
1886  *  @def nlNPRECONDITION_VALUE_PRINT(aCondition, aValue, aMessage)
1887  *
1888  *  @brief
1889  *    This checks for the specified condition, which is expected to
1890  *    commonly be false, and both prints @p aMessage and then returns
1891  *    @p aValue from the enclosing function if the condition is true.
1892  *
1893  *  @note This is the logical inverse of #nlPRECONDITION_VALUE_PRINT.
1894  *
1895  *  @param[in]  aCondition  A Boolean expression to be evaluated.
1896  *  @param[in]  aValue      The value to be returned when the assertion
1897  *                          fails.
1898  *  @param[in]  aMessage    A pointer to a NULL-terminated C string
1899  *                          containing a caller-specified message
1900  *                          further describing the assertion failure.
1901  *
1902  *  @sa #NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS
1903  *  @sa #NL_ASSERT_PRECONDITION_PRODUCTION_FLAGS
1904  *
1905  *  @sa #nlPRECONDITION_VALUE_PRINT
1906  *
1907  *  @sa #nlNEXPECT_PRINT
1908  *  @sa #nlNDESIRE_PRINT
1909  *  @sa #nlNREQUIRE_PRINT
1910  *
1911  */
1912 #define nlNPRECONDITION_VALUE_PRINT(aCondition, aValue, aMessage)               __nlNPRECONDITION_PRINT(NL_ASSERT_PRECONDITION_NONPRODUCTION_FLAGS, aCondition, return aValue, aMessage)
1913
1914 /**
1915  *  @}
1916  *
1917  */
1918
1919 /**
1920  *  @ingroup assert-style
1921  *
1922  *  @{
1923  *
1924  */
1925
1926 /**
1927  *  @def NL_ASSERT_ASSERT_NONPRODUCTION_FLAGS_DEFAULT
1928  *
1929  *  @brief
1930  *    This defines the default behavioral flags for assert-style
1931  *    exception family assertions when #NL_ASSERT_PRODUCTION is
1932  *    disabled.
1933  *
1934  *  This may be used to override #NL_ASSERT_ASSERT_NONPRODUCTION_FLAGS as follows:
1935  *
1936  *  @code
1937  *    #define NL_ASSERT_ASSERT_NONPRODUCTION_FLAGS NL_ASSERT_ASSERT_NONPRODUCTION_FLAGS_DEFAULT
1938  *
1939  *    #include <nlassert.h>
1940  *  @endcode
1941  *
1942  *  @sa #NL_ASSERT_ASSERT_NONPRODUCTION_FLAGS
1943  *
1944  *  @sa #NL_ASSERT_PRODUCTION
1945  *
1946  *  @sa #NL_ASSERT_FLAG_BACKTRACE
1947  *  @sa #NL_ASSERT_FLAG_LOG
1948  *  @sa #NL_ASSERT_FLAG_TRAP
1949  *
1950  */
1951 #define NL_ASSERT_ASSERT_NONPRODUCTION_FLAGS_DEFAULT                            (NL_ASSERT_FLAG_BACKTRACE | NL_ASSERT_FLAG_LOG)
1952
1953 /**
1954  *  @def NL_ASSERT_ASSERT_NONPRODUCTION_FLAGS
1955  *
1956  *  @brief
1957  *    This defines the behavioral flags when #NL_ASSERT_PRODUCTION is
1958  *    disabled that govern the behavior for assert-style exception
1959  *    family assertions when the assertion expression evaluates to
1960  *    false.
1961  *
1962  *  @sa #NL_ASSERT_USE_FLAGS_DEFAULT
1963  *
1964  *  @sa #NL_ASSERT_ASSERT_NONPRODUCTION_FLAGS_DEFAULT
1965  *
1966  *  @sa #NL_ASSERT_PRODUCTION
1967  *
1968  *  @sa #NL_ASSERT_FLAG_BACKTRACE
1969  *  @sa #NL_ASSERT_FLAG_LOG
1970  *  @sa #NL_ASSERT_FLAG_TRAP
1971  */
1972 #if NL_ASSERT_USE_FLAGS_DEFAULT
1973 #define NL_ASSERT_ASSERT_NONPRODUCTION_FLAGS                                     NL_ASSERT_ASSERT_NONPRODUCTION_FLAGS_DEFAULT
1974 #elif !defined(NL_ASSERT_ASSERT_NONPRODUCTION_FLAGS)
1975 #define NL_ASSERT_ASSERT_NONPRODUCTION_FLAGS                                    (NL_ASSERT_FLAG_NONE)
1976 #endif
1977
1978 /**
1979  *  @def nlASSERT(aCondition)
1980  *
1981  *  @brief
1982  *    This checks for the specified condition, which is expected to
1983  *    commonly be true and takes action, based on configuration, and
1984  *    invokes #NL_ASSERT_ABORT() if the condition is false.
1985  *
1986  *  @note If #NL_ASSERT_PRODUCTION is true, the check is made inactive. But
1987  *  side-effects, if any, in the asserted expression will still be produced.
1988  *
1989  *  @param[in]  aCondition  A Boolean expression to be evaluated.
1990  *
1991  *  @sa #NL_ASSERT_ASSERT_NONPRODUCTION_FLAGS
1992  *
1993  *  @sa #nlCHECK
1994  *  @sa #nlVERIFY
1995  *  @sa #nlABORT
1996  *
1997  */
1998 #define nlASSERT(aCondition)                                                    __nlABORT(NL_ASSERT_ASSERT_NONPRODUCTION_FLAGS, aCondition)
1999
2000 /**
2001  *  @def nlASSERT_ACTION(aCondition, anAction)
2002  *
2003  *  @brief
2004  *    This checks for the specified condition, which is expected to
2005  *    commonly be true and takes action, based on configuration, and
2006  *    both executes @p anAction and then invokes #NL_ASSERT_ABORT() if
2007  *    the condition is false.
2008  *
2009  *  @note If #NL_ASSERT_PRODUCTION is true, the check is made inactive. But
2010  *  side-effects, if any, in the asserted expression will still be produced.
2011  *
2012  *  @param[in]  aCondition  A Boolean expression to be evaluated.
2013  *  @param[in]  anAction    An expression or block to execute when the
2014  *                          assertion fails. This will be executed
2015  *                          after #NL_ASSERT_LOG() and
2016  *                          #NL_ASSERT_BACKTRACE() but before
2017  *                          #NL_ASSERT_TRAP().
2018  *
2019  *  @sa #NL_ASSERT_ASSERT_NONPRODUCTION_FLAGS
2020  *
2021  *  @sa #nlCHECK_ACTION
2022  *  @sa #nlVERIFY_ACTION
2023  *  @sa #nlABORT_ACTION
2024  *
2025  */
2026 #define nlASSERT_ACTION(aCondition, anAction)                                   __nlABORT_ACTION(NL_ASSERT_ASSERT_NONPRODUCTION_FLAGS, aCondition, anAction)
2027
2028 /**
2029  *  @}
2030  *
2031  */
2032
2033 /**
2034  *  @ingroup abort-style
2035  *
2036  *  @{
2037  *
2038  */
2039
2040 /**
2041  *  @def NL_ASSERT_ABORT_NONPRODUCTION_FLAGS_DEFAULT
2042  *
2043  *  @brief
2044  *    This defines the default behavioral flags for abort-style
2045  *    exception family assertions when #NL_ASSERT_PRODUCTION is
2046  *    disabled.
2047  *
2048  *  This may be used to override #NL_ASSERT_ABORT_NONPRODUCTION_FLAGS as follows:
2049  *
2050  *  @code
2051  *    #define NL_ASSERT_ABORT_NONPRODUCTION_FLAGS NL_ASSERT_ABORT_NONPRODUCTION_FLAGS_DEFAULT
2052  *
2053  *    #include <nlassert.h>
2054  *  @endcode
2055  *
2056  *  @sa #NL_ASSERT_ABORT_NONPRODUCTION_FLAGS
2057  *
2058  *  @sa #NL_ASSERT_PRODUCTION
2059  *
2060  *  @sa #NL_ASSERT_FLAG_BACKTRACE
2061  *  @sa #NL_ASSERT_FLAG_LOG
2062  *  @sa #NL_ASSERT_FLAG_TRAP
2063  *
2064  */
2065 #define NL_ASSERT_ABORT_NONPRODUCTION_FLAGS_DEFAULT                             (NL_ASSERT_FLAG_BACKTRACE | NL_ASSERT_FLAG_LOG)
2066
2067 /**
2068  *  @def NL_ASSERT_ABORT_NONPRODUCTION_FLAGS
2069  *
2070  *  @brief
2071  *    This defines the behavioral flags when #NL_ASSERT_PRODUCTION is
2072  *    disabled that govern the behavior for abort-style exception
2073  *    family assertions when the assertion expression evaluates to
2074  *    false.
2075  *
2076  *  @sa #NL_ASSERT_USE_FLAGS_DEFAULT
2077  *
2078  *  @sa #NL_ASSERT_ABORT_NONPRODUCTION_FLAGS_DEFAULT
2079  *
2080  *  @sa #NL_ASSERT_PRODUCTION
2081  *
2082  *  @sa #NL_ASSERT_FLAG_BACKTRACE
2083  *  @sa #NL_ASSERT_FLAG_LOG
2084  *  @sa #NL_ASSERT_FLAG_TRAP
2085  */
2086 #if NL_ASSERT_USE_FLAGS_DEFAULT
2087 #define NL_ASSERT_ABORT_NONPRODUCTION_FLAGS                                     NL_ASSERT_ABORT_NONPRODUCTION_FLAGS_DEFAULT
2088 #elif !defined(NL_ASSERT_ABORT_NONPRODUCTION_FLAGS)
2089 #define NL_ASSERT_ABORT_NONPRODUCTION_FLAGS                                     (NL_ASSERT_FLAG_NONE)
2090 #endif
2091
2092 /**
2093  *  @def nlABORT(aCondition)
2094  *
2095  *  @brief
2096  *    This checks for the specified condition, which is expected to
2097  *    commonly be true and takes action, based on configuration, and
2098  *    invokes #NL_ASSERT_ABORT() if the condition is false.
2099  *
2100  *  @param[in]  aCondition  A Boolean expression to be evaluated.
2101  *
2102  *  @sa #NL_ASSERT_ABORT_NONPRODUCTION_FLAGS
2103  *  @sa #NL_ASSERT_ABORT_PRODUCTION_FLAGS
2104  *
2105  *  @sa #nlCHECK
2106  *  @sa #nlVERIFY
2107  *  @sa #nlASSERT
2108  *
2109  */
2110 #define nlABORT(aCondition)                                                     __nlABORT(NL_ASSERT_ABORT_NONPRODUCTION_FLAGS, aCondition)
2111
2112 /**
2113  *  @def nlABORT_ACTION(aCondition, anAction)
2114  *
2115  *  @brief
2116  *    This checks for the specified condition, which is expected to
2117  *    commonly be true and takes action, based on configuration, and
2118  *    both executes @p anAction and then invokes #NL_ASSERT_ABORT() if
2119  *    the condition is false.
2120  *
2121  *  @param[in]  aCondition  A Boolean expression to be evaluated.
2122  *  @param[in]  anAction    An expression or block to execute when the
2123  *                          assertion fails. This will be executed
2124  *                          after #NL_ASSERT_LOG() and
2125  *                          #NL_ASSERT_BACKTRACE() but before
2126  *                          #NL_ASSERT_TRAP().
2127  *
2128  *  @sa #NL_ASSERT_ABORT_NONPRODUCTION_FLAGS
2129  *  @sa #NL_ASSERT_ABORT_PRODUCTION_FLAGS
2130  *
2131  *  @sa #nlCHECK_ACTION
2132  *  @sa #nlVERIFY_ACTION
2133  *  @sa #nlASSERT_ACTION
2134  *
2135  */
2136 #define nlABORT_ACTION(aCondition, anAction)                                    __nlABORT_ACTION(NL_ASSERT_ABORT_NONPRODUCTION_FLAGS, aCondition, anAction)
2137
2138 /**
2139  *  @}
2140  *
2141  */
2142
2143 #endif /* NLCORE_NLASSERT_NONPRODUCTION_H */