DBC revision 9c3531d72aeaad6c5f01efe6a1c82023e1379e4d
fa9e4066f08beec538e775443c5be79dd423fcabahrensCopyright (C) 1999, 2000 Internet Software Consortium.
fa9e4066f08beec538e775443c5be79dd423fcabahrensSee COPYRIGHT in the source root or http://www.isc.org/copyright for terms.
fa9e4066f08beec538e775443c5be79dd423fcabahrens$Id: DBC,v 1.3 2000/06/22 21:54:01 tale Exp $
441d80aa4f613b6298fc8bd3151f4be02dbf84fcllingDesign By Contract
fa9e4066f08beec538e775443c5be79dd423fcabahrensBIND 9 uses the "Design by Contract" idea for most function calls.
fa9e4066f08beec538e775443c5be79dd423fcabahrensA quick summary of the idea is that a function and its caller make a
fa9e4066f08beec538e775443c5be79dd423fcabahrenscontract. If the caller meets certain preconditions, then the
fa9e4066f08beec538e775443c5be79dd423fcabahrensfunction promises to either fulfill its contract (i.e. guarantee a set
fa9e4066f08beec538e775443c5be79dd423fcabahrensof postconditions), or to clearly fail.
fa9e4066f08beec538e775443c5be79dd423fcabahrens"Clearly fail" means that if the function cannot succeed, then it will
fa9e4066f08beec538e775443c5be79dd423fcabahrensnot silently fail and return a value which the caller might interpret
fa9e4066f08beec538e775443c5be79dd423fcabahrensIf a caller doesn't meet the preconditions, then "further execution is
fa9e4066f08beec538e775443c5be79dd423fcabahrensundefined". The function can crash, compute a garbage result, fail silently,
ad135b5d644628e791c3188a6ecbd9c257961ef8Christopher Sidenetc. Allowing the function to define preconditions greatly simplifies many
fa9e4066f08beec538e775443c5be79dd423fcabahrensAPIs, because the API need not have a way of saying "hey caller, the values
3f9d6ad73e45c6823b409f93b0c8d4f62861d2d5Lin Lingyou passed in are garbage".
fa9e4066f08beec538e775443c5be79dd423fcabahrensTypically, preconditions are specified in the functions .h file, and encoded
fa9e4066f08beec538e775443c5be79dd423fcabahrensin its body with REQUIRE statements. The REQUIRE statements cause the program
fa9e4066f08beec538e775443c5be79dd423fcabahrensto dump core if they are not true, and can be used to identify callers that
fa9e4066f08beec538e775443c5be79dd423fcabahrensare not meeting their preconditions.
fa9e4066f08beec538e775443c5be79dd423fcabahrensPostconditions can be encoded with ENSURE statements. Within the body of
fa9e4066f08beec538e775443c5be79dd423fcabahrensa function, INSIST is used to assert that a particular expression must be
fa9e4066f08beec538e775443c5be79dd423fcabahrenstrue. Assertions must not have side effects that the function relies upon,
fa9e4066f08beec538e775443c5be79dd423fcabahrensbecause assertion checking can be turned off.