results revision 767d29c43d98bae8ea95f0ccd2b9653cbcd43310
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwResult Codes
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwThe use of global variables or a GetLastError() function to return results
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwdoesn't work well in a multithreaded application. The global variable has
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwobvious problems, as does a global GetLastError(). A per-object GetLastError()
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwseems more promising, e.g.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw sometype_t s;
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw sometype_dosomething(s, buffer);
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw if (sometype_error(s)) {
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwIf 's' is shared however this approach doesn't work unless the locking is
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwdone by the caller, e.g.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw sometype_lock();
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw sometype_dosomething(s, buffer);
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw if (sometype_error(s)) {
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw sometype_unlock();
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwThose ISC and DNS libraries which have locks almost universally put the
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwlocking inside of the called routines, since it's more convenient for
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwthe calling programmer, makes for a cleaner API, and puts the burden
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwof locking on the library programmer, who should know best what the
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwlocking needs of the routine are.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwBecause of this locking style the ISC and DNS libraries typically provide
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwresult information as the return value of the function. E.g.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw isc_result_t result;
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw result = isc_task_send(task, &event);
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwNote that an explicit result type is used, instead of mixing the error result
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwtype with the normal result type. E.g. the C library routine getc() can
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwreturn a character or EOF, but the BIND 9 style keeps the types of the
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwfunction's return values separate.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw result = isc_io_getc(stream, &c);
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw if (result == ISC_R_SUCCESS) {
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw /* Do something with 'c'. */
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw } else if (result == ISC_R_EOF) {
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw /* EOF. */
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw /* Some other error. */
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwFunctions which cannot fail (assuming the caller has provided valid
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwarguments) need not return a result type. For example, dns_name_issubdomain()
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwreturns an isc_boolean_t, because it cannot fail.