220N/ACopyright (C) 1999-2001 Internet Software Consortium.
220N/A$Id: DBC,v 1.5 2001/01/09 21:46:58 bwelling Exp $
220N/ABIND 9 uses the "Design by Contract" idea for most function calls.
220N/AA quick summary of the idea is that a function and its caller make a
220N/Acontract. If the caller meets certain preconditions, then the
220N/Afunction promises to either fulfill its contract (
i.e. guarantee a set
220N/Aof postconditions), or to clearly fail.
220N/A"Clearly fail" means that if the function cannot succeed, then it will
220N/Anot silently fail and return a value which the caller might interpret
1472N/AIf a caller doesn't meet the preconditions, then "further execution is
1472N/Aundefined". The function can crash, compute a garbage result, fail silently,
1472N/Aetc. Allowing the function to define preconditions greatly simplifies many
220N/AAPIs, because the API need not have a way of saying "hey caller, the values
220N/Ayou passed in are garbage".
220N/ATypically, preconditions are specified in the functions .h file, and encoded
220N/Ain its body with REQUIRE statements. The REQUIRE statements cause the program
220N/Ato dump core if they are not true, and can be used to identify callers that
220N/Aare not meeting their preconditions.
220N/APostconditions can be encoded with ENSURE statements. Within the body of
220N/Aa function, INSIST is used to assert that a particular expression must be
220N/Atrue. Assertions must not have side effects that the function relies upon,
220N/Abecause assertion checking can be turned off.