200N/ACopyright (C) 1999, 2000 Internet Software Consortium.

200N/ASee COPYRIGHT in the source root or http://www.isc.org/copyright for terms.

200N/A

200N/A$Id: results,v 1.4 2000/08/01 01:18:25 tale Exp $

200N/A

200N/AResult Codes

200N/A

200N/AThe use of global variables or a GetLastError() function to return results

200N/Adoesn't work well in a multithreaded application. The global variable has

200N/Aobvious problems, as does a global GetLastError(). A per-object GetLastError()

200N/Aseems more promising, e.g.

200N/A

200N/A sometype_t s;

200N/A

200N/A sometype_dosomething(s, buffer);

200N/A if (sometype_error(s)) {

200N/A /* ... */

200N/A }

200N/A

200N/AIf 's' is shared however this approach doesn't work unless the locking is

200N/Adone by the caller, e.g.

200N/A

200N/A sometype_lock();

200N/A sometype_dosomething(s, buffer);

200N/A if (sometype_error(s)) {

200N/A /* ... */

200N/A }

206N/A sometype_unlock();

206N/A

200N/AThose ISC and DNS libraries which have locks almost universally put the

200N/Alocking inside of the called routines, since it's more convenient for

200N/Athe calling programmer, makes for a cleaner API, and puts the burden

200N/Aof locking on the library programmer, who should know best what the

200N/Alocking needs of the routine are.

206N/A

200N/ABecause of this locking style the ISC and DNS libraries typically provide

200N/Aresult information as the return value of the function. E.g.

200N/A

200N/A isc_result_t result;

200N/A

200N/A result = isc_task_send(task, &event);

200N/A

200N/ANote that an explicit result type is used, instead of mixing the error result

200N/Atype with the normal result type. E.g. the C library routine getc() can

200N/Areturn a character or EOF, but the BIND 9 style keeps the types of the

206N/Afunction's return values separate.

200N/A

206N/A char c;

200N/A

200N/A result = isc_io_getc(stream, &c);

206N/A if (result == ISC_R_SUCCESS) {

206N/A /* Do something with 'c'. */

206N/A } else if (result == ISC_R_EOF) {

206N/A /* EOF. */

206N/A } else {

200N/A /* Some other error. */

206N/A }

200N/A

200N/AFunctions which cannot fail (assuming the caller has provided valid

200N/Aarguments) need not return a result type. For example, dns_name_issubdomain()

206N/Areturns an isc_boolean_t, because it cannot fail.

200N/A