- All libbabeltrace2 definitions, macros, and enumerators start
with \c BT_.
-@section api-fund-pre-post Function precondition and postcondition checking
+@section api-fund-pre-post Function contract checking
-All the functions of libbabeltrace2 which have parameters check that
-the caller meets their
+All the functions of libbabeltrace2 check that the caller meets their
<a href="https://en.wikipedia.org/wiki/Precondition">preconditions</a>.
-All the functions of libbabeltrace2 which call a user function which
-returns something check that the returned value meets their
-<a href="https://en.wikipedia.org/wiki/Postcondition">postconditions</a>.
+All the functions of libbabeltrace2 which call a user function check
+that it meets its
+<a href="https://en.wikipedia.org/wiki/Postcondition">postconditions</a>
+when it returns.
The function descriptions in the
-<a class="el" href="modules.html">API reference modules</a>
+<a class="el" href="topics.html">API reference</a>
list all their preconditions and postconditions, if any.
-libbabeltrace2 is very strict regarding function preconditions and
-postconditions: when you break any of them, the library prints how the
-precondition or postcondition was not satisfied, with details, and then
-calls <code>abort()</code>.
+The libbabeltrace2 public functions offer a
+<strong>narrow contract</strong>: when you break it, the library
+prints how the precondition or postcondition was not satisfied, with
+details, and then calls <code>abort()</code>.
Here's an example of what the library prints to the standard error
-before aborting when you break a precondition:
+before aborting when you break a precondition (call
+bt_value_bool_set() with a \c NULL value);
+\ref api-fund-logging "logging" prefixes are removed for clarity:
@code{.unparsed}
-10-06 09:12:20.228 62362 62362 F LIB/VALUE bt_value_array_get_length@value.c:887 Babeltrace 2 library precondition not satisfied; error is:
-10-06 09:12:20.228 62362 62362 F LIB/VALUE bt_value_array_get_length@value.c:887 Value object is NULL:
-10-06 09:12:20.228 62362 62362 F LIB/VALUE bt_value_array_get_length@value.c:887 Aborting...
+Babeltrace 2 library precondition not satisfied.
+------------------------------------------------------------------------
+Condition ID: `pre:value-bool-set:not-null:value-object`.
+Function: bt_value_bool_set().
+------------------------------------------------------------------------
+Error is:
+Value object is NULL.
+Aborting...
@endcode
+In the output above:
+
+- <code>pre:value-bool-set:not-null:value-object</code> is the unique,
+ permanent ID of this precondition.
+
+ We use this ID for internal libbabeltrace2 testing.
+
+- The <code>Function:</code> line shows which function's contract was
+ broken.
+
Because precondition and postcondition checks detect programming errors,
libbabeltrace2's approach is to abort as soon as possible so that you
fix the error. Therefore, the libbabeltrace2 functions never return a
B API functions with an object of type A. For example, because an
\bt_enum_fc \em is conceptually an \bt_int_fc, you can use any integer
field class function with an enumeration field class.
-The <a class="el" href="modules.html">API reference modules</a> always
+The <a class="el" href="topics.html">API reference pages</a> always
indicate the inheritance relations.
@subsection api-fund-object-shared-unique Shared vs. unique objects
Because you cannot get a new unique object reference, you \em must
ensure that you own the unique object's owner to keep it alive. The
- <a class="el" href="modules.html">API reference modules</a> make it
+ <a class="el" href="topics.html">API reference pages</a> make it
clear, depending on the context, which
shared object is the ultimate owner of a given unique object.
</dd>
</dl>
-In the <a class="el" href="modules.html">API reference</a>, each module
+In the <a class="el" href="topics.html">API reference</a>, each page
indicates whether the documented objects are shared or unique.
@subsection api-fund-freezing Object freezing
become frozen, recursively.
There's no function to check whether or not a given object is frozen.
-Because the <a class="el" href="modules.html">API reference modules</a>
+Because the <a class="el" href="topics.html">API reference pages</a>
document which functions freeze which objects,
the "frozen" property is only useful for libbabeltrace2 to catch
programming errors (\ref api-fund-pre-post "precondition checks").
the type #bt_value because an \bt_array_val can contain different
types of values. You must be careful to only call the functions which
apply to a specific type of such objects.
-The <a class="el" href="modules.html">API reference modules</a> make
+The <a class="el" href="topics.html">API reference pages</a> make
this clear in the precondition section. Such objects always have a
<code>*_get_type()</code> function to get the object's exact type
enumerator. For example, bt_value_get_type() returns the type enumerator
}
@endcode
-The <a class="el" href="modules.html">API reference modules</a>
+The <a class="el" href="topics.html">API reference pages</a>
document, for each function, what each return status enumerator means.
Some functions return properties or objects by output parameter. When
different developers.
An error cause contains information about the source location where the
-error occured, the actor involved in the error, and a message.
+error occurred, the actor involved in the error, and a message.
When you "catch" an error, that is, react to a function returning an
error status code without returning an error status code yourself,