module xdc.runtime.Assert |
|
|
|
Runtime assertion manager
The
Assert module provides configurable diagnostics to the program.
Similar to the standard C
assert() macro,
Assert methods are
interspersed with other code to add diagnostics to a program. Unlike
the standard C assert support, the
Assert module provides greater
flexibility in managing the messages displayed, the message string
space overhead, and the runtime handling of failures. In addition,
because the
Assert methods build atop the Diags module, you can
precisely control which asserts remain in the final application, if any.
[
more ... ]
#include <xdc/runtime/Assert.h>
module-wide constants & types
module-wide config parameters
module-wide functions
module-wide built-ins
XDCscript usage |
meta-domain |
var Assert = xdc.useModule('xdc.runtime.Assert');
module-wide constants & types
module-wide config parameters
msg: "assertion failure%s%s"
};
module Assert {
module-wide constants & types
};
module-wide config parameters
msg: "assertion failure%s%s"
};
module-wide functions
}
DETAILS
The Assert module provides configurable diagnostics to the program.
Similar to the standard C assert() macro, Assert methods are
interspersed with other code to add diagnostics to a program. Unlike
the standard C assert support, the Assert module provides greater
flexibility in managing the messages displayed, the message string
space overhead, and the runtime handling of failures. In addition,
because the Assert methods build atop the Diags module, you can
precisely control which asserts remain in the final application, if any.
The
Assert module works in conjunction with the
Diags module.
Assert statements are added to the code using the
Assert_isTrue() function. Execution of assert
statements is controlled by the
Diags.ASSERT and
Diags.INTERNAL bits in a module's diagnostics mask. By default,
all module's
Diags_ASSERT bit is enabled and the
Diags_INTERNAL bit
is disabled. See
Types.Common$ for the
declaration of the bits in the diagnostics mask and
Default.common$ for the default module settings.
Two types of asserts are supported: public asserts and internal asserts.
- Public asserts have an assert ID and are, by default, controlled
by the Diags.ASSERT bit.
- Internal asserts don't have an assert ID (other than NULL) and
are active only when both the Diags.ASSERT and
Diags.INTERNAL bits of the module's diagnostics mask are set.
Assert IDs are small integer values that index into a table of
assertion descriptors. These descriptors hold an error message
and a diagnostics mask that is used to enable and disable the
assertion at runtime.
You can remap individual public asserts to different bits in the
diagnostics mask, or can disable the assert altogether. This is
done by setting the mask property of the assert ID. Setting the
mask to 0 disables the assert. In all other cases, the Diags.ASSERT
bit is OR'd together with the mask to define the controlling bits.
For example, the module's diagnostics mask must have the Diags.ASSERT
bit set and any other bit specified in the mask property of the
assert ID in order to activate the assert.
EXAMPLES
Example 1: The following C code adds an assert to application code
which is not in a module. This assert does not have an assert
identifier (the second argument is NULL); this makes it an internal
assert.
// file.c
#include <xdc/runtime/Assert.h>
Assert_isTrue(count > 0, NULL);
The following XDC configuration statements set both the ASSERT and
INTERNAL bits in the diagnostics mask to enable the internal assert
created in the previous C code. Since the C code is not in a module,
you must set the bits in the diagnostics mask of the
xdc.runtime.Main module. The Main module
is used to control all
Log and
Assert statements that are
not part of the implementation of a module; for example, top-level
application code or any existing sources that simply call the
Log or
Assert methods.
// program.cfg
var Assert = xdc.useModule('xdc.runtime.Assert');
var Diags = xdc.useModule('xdc.runtime.Diags');
var Main = xdc.useModule('xdc.runtime.Main');
Main.common$.diags_ASSERT = Diags.ALWAYS_ON;
Main.common$.diags_INTERNAL = Diags.ALWAYS_ON;
Example 2: The following example shows how to use and configure an
assert ID that is declared by a module. It adds that assert to the
application's C source code, and configures the application to
execute the assert.
This is part of the XDC file for the module that declares an Assert Id:
// Mod.xdc
import xdc.runtime.Assert;
import xdc.runtime.Diags;
config Assert.Id A_nonZero = {
msg: "A_nonZero: value must be non-zero"
};
This is part of the C code for the application:
// Mod.c
#include <xdc/runtime/Assert.h>
Assert_isTrue(x != 0, Mod_A_nonZero);
This is part of the XDC configuration file for the application:
// program.cfg
var Diags = xdc.useModule('xdc.runtime.Diags');
var Mod = xdc.useModule('my.pkg.Mod');
Mod.common$.diags_ASSERT = Diags.ALWAYS_ON;
typedef Assert.Id |
|
Assert identifier
typedef opaque Assert_Id;
DETAILS
Each metaonly assert descriptor is encoded into a target accessable
assert Id type which can be passed to the
isTrue function.
metaonly struct Assert.Desc |
|
Assert descriptor
XDCscript usage |
meta-domain |
var obj = new Assert.Desc;
obj.mask = Bits16 ...
obj.msg = String ...
FIELDS
mask
Specifies which bits enable the assert.
msg
The message printed when the assert fails.
DETAILS
Each public assert is defined with an assert descriptor. This
structure defines which bits in the module's diagnostics mask
control this assert, and the message raised when the assert fails.
The mask property is optional, it defaults to the
Diags.ASSERT bit.
config Assert.E_assertFailed // module-wide |
|
The Error.Id raised when an assertion violation is detected
XDCscript usage |
meta-domain |
msg: "assertion failure%s%s"
};
extern const Error_Id Assert_E_assertFailed;
DETAILS
When an assertion violation is triggered, an error is raised via
Error_raise().
E_assert_Failed is the
Error.Id passed
to
Error_raise().
The first string argument (%s) will be either "", if the assertion Id
is
NULL (for internal asserts), or ": " (for public asserts).
The second string argument (%s) is the
Assert.Desc.msg string associated with the assertion Id; if the
Id is
NULL (an internal assert) or if text is not loaded
(
!Text.isLoaded()), this string is "".
SEE
metaonly config Assert.common$ // module-wide |
|
Common module configuration parameters
XDCscript usage |
meta-domain |
DETAILS
All modules have this configuration parameter. Its name
contains the '$' character to ensure it does not conflict with
configuration parameters declared by the module. This allows
new configuration parameters to be added in the future without
any chance of breaking existing modules.
Assert.isTrue( ) // module-wide |
|
Test an assertion
macro Void Assert_isTrue(
Bool expr,
Assert_Id id );
ARGUMENTS
expr
the expression which should evaluate to true
id
identifies the assert being raised
DETAILS
Assert_isTrue() statements may be conditionally enabled (disabled)
on a per module basis by setting the calling module's
$common.diags_ASSERT configuration
parameter. If
the
Assert_isTrue() statement is not in a module, the calling
module is the
Main module. You must enable the
Diags.ASSERT bit in the module's diagnostics mask for this
call to be enabled. If a
NULL assert id is specified, then you
must enable the
Diags.INTERNAL in addition to the
ASSERT bit.
If the
Assert_isTrue() statement is enabled and
expr evaluates to
false, the assert specified by
id is raised; i.e., the
E_assertFailed error is raised with a
NULL
error block. In other words, the standard
Error.raise
handling hooks will be run,
System.abort() will be called,
and control does not return to the caller. The
id may be
null, in
which case you will get a generic assert message.
EXAMPLES
C Code
#include <xdc/runtime/Assert.h>
Assert_isTrue(count > 0, NULL);
module-wide built-ins |
|
// Get this module's unique id
Bool Assert_Module_startupDone( );
// Test if this module has completed startup
// The heap from which this module allocates memory
Bool Assert_Module_hasMask( );
// Test whether this module has a diagnostics mask
Bits16 Assert_Module_getMask( );
// Returns the diagnostics mask for this module
Void Assert_Module_setMask( Bits16 mask );
// Set the diagnostics mask for this module
generated on Wed, 06 Jan 2010 18:40:41 GMT