results revision 9c3531d72aeaad6c5f01efe6a1c82023e1379e4d
9bff67898d55cddfcec9ce30cc2b1bb6211ec691David LawrenceCopyright (C) 1999, 2000 Internet Software Consortium.
9bff67898d55cddfcec9ce30cc2b1bb6211ec691David LawrenceSee COPYRIGHT in the source root or http://www.isc.org/copyright for terms.
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley
9c3531d72aeaad6c5f01efe6a1c82023e1379e4dDavid Lawrence$Id: results,v 1.3 2000/06/22 21:54:07 tale Exp $
9c3531d72aeaad6c5f01efe6a1c82023e1379e4dDavid Lawrence
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyResult Codes
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyThe use of global variables or a GetLastError() function to return results
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleydoesn't work well in a multithreaded application. The global variable has
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyobvious problems, as does a global GetLastError(). A per-object GetLastError()
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyseems more promising, e.g.
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley sometype_t s;
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley sometype_dosomething(s, buffer);
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley if (sometype_error(s)) {
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley /* ... */
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley }
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyIf 's' is shared however this approach doesn't work unless the locking is
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleydone by the caller, e.g.
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley sometype_lock();
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley sometype_dosomething(s, buffer);
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley if (sometype_error(s)) {
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley /* ... */
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley }
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley sometype_unlock();
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyThose ISC and DNS libraries which have locks almost universally put the
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleylocking inside of the called routines, since it's more convenient for
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleythe calling programmer, makes for a cleaner API, and puts the burden
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyof locking on the library programmer, who should know best what the
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleylocking needs of the routine are.
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyBecause of this locking style the ISC and DNS libraries typically provide
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyresult information as the return value of the function. E.g.
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley isc_result_t result;
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley result = isc_task_send(task, &event);
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyNote that an explicit result type is used, instead of mixing the error result
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleytype with the normal result type. E.g. the C library routine getc() can
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyreturn a character or EOF, but the BIND 9 style keeps the types of the
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyfunction's return values separate.
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley char c;
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley result = isc_io_getc(stream, &c);
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley if (result == ISC_R_SUCCESS) {
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley /* Do something with 'c'. */
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley } else if (result == ISC_R_EOF) {
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley /* EOF. */
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley } else {
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley /* Some other error. */
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley }
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halley
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob HalleyFunctions which cannot fail (assuming the caller has provided valid
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyarguments) need not return a result type. For example, dns_name_issubdomain()
767d29c43d98bae8ea95f0ccd2b9653cbcd43310Bob Halleyreturns an isc_boolean_t, because it cannot fail.