results revision 40f53fa8d9c6a4fc38c0014495e7a42b08f52481
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinCopyright (C) 1999, 2000 Internet Software Consortium.
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark AndrewsSee COPYRIGHT in the source root or http://www.isc.org/copyright for terms.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein$Id: results,v 1.4 2000/08/01 01:18:25 tale Exp $
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThe use of global variables or a GetLastError() function to return results
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeindoesn't work well in a multithreaded application. The global variable has
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinobvious problems, as does a global GetLastError(). A per-object GetLastError()
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinseems more promising, e.g.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein sometype_t s;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein sometype_dosomething(s, buffer);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein if (sometype_error(s)) {
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinIf 's' is shared however this approach doesn't work unless the locking is
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeindone by the caller, e.g.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein sometype_lock();
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein sometype_dosomething(s, buffer);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein if (sometype_error(s)) {
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein sometype_unlock();
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThose ISC and DNS libraries which have locks almost universally put the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinlocking inside of the called routines, since it's more convenient for
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinthe calling programmer, makes for a cleaner API, and puts the burden
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinof locking on the library programmer, who should know best what the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinlocking needs of the routine are.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinBecause of this locking style the ISC and DNS libraries typically provide
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinresult information as the return value of the function. E.g.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein isc_result_t result;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein result = isc_task_send(task, &event);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinNote that an explicit result type is used, instead of mixing the error result
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeintype with the normal result type. E.g. the C library routine getc() can
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinreturn a character or EOF, but the BIND 9 style keeps the types of the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinfunction's return values separate.
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark Andrews result = isc_io_getc(stream, &c);
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark Andrews if (result == ISC_R_SUCCESS) {
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark Andrews /* Do something with 'c'. */
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein } else if (result == ISC_R_EOF) {
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein /* Some other error. */
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinFunctions which cannot fail (assuming the caller has provided valid
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinarguments) need not return a result type. For example, dns_name_issubdomain()
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinreturns an isc_boolean_t, because it cannot fail.