results revision 0c27b3fe77ac1d5094ba3521e8142d9e7973133f
d6fa26d0adaec6c910115be34fe7a5a5f402c14fMark AndrewsCopyright (C) 1999-2001, 2004, 2016 Internet Systems Consortium, Inc. ("ISC")
33d0a7767d53cb366039fd0ac4f63cf8a9c351b0Tinderbox UserThis Source Code Form is subject to the terms of the Mozilla Public
663272199096ed57917f2bfb1d748a0a622b7b24Tinderbox UserLicense, v. 2.0. If a copy of the MPL was not distributed with this
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox Userfile, You can obtain one at http://mozilla.org/MPL/2.0/.
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User$Id: results,v 1.7 2004/03/05 05:04:50 marka Exp $
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark AndrewsThe use of global variables or a GetLastError() function to return results
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrewsdoesn't work well in a multithreaded application. The global variable has
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userobvious problems, as does a global GetLastError(). A per-object GetLastError()
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrewsseems more promising, e.g.
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews sometype_t s;
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User sometype_dosomething(s, buffer);
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User if (sometype_error(s)) {
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark AndrewsIf 's' is shared however this approach doesn't work unless the locking is
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userdone by the caller, e.g.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User sometype_lock();
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User sometype_dosomething(s, buffer);
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark Andrews if (sometype_error(s)) {
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User sometype_unlock();
0c91911b4d1e872b87eaf6431ed47fe24d18dd43Mark AndrewsThose ISC and DNS libraries which have locks almost universally put the
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userlocking inside of the called routines, since it's more convenient for
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userthe calling programmer, makes for a cleaner API, and puts the burden
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userof locking on the library programmer, who should know best what the
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userlocking needs of the routine are.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserBecause of this locking style the ISC and DNS libraries typically provide
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userresult information as the return value of the function. E.g.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User isc_result_t result;
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User result = isc_task_send(task, &event);
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserNote that an explicit result type is used, instead of mixing the error result
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Usertype with the normal result type. E.g. the C library routine getc() can
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userreturn a character or EOF, but the BIND 9 style keeps the types of the
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userfunction's return values separate.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User result = isc_io_getc(stream, &c);
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User if (result == ISC_R_SUCCESS) {
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User /* Do something with 'c'. */
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User } else if (result == ISC_R_EOF) {
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User /* Some other error. */
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserFunctions which cannot fail (assuming the caller has provided valid
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userarguments) need not return a result type. For example, dns_name_issubdomain()
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userreturns an isc_boolean_t, because it cannot fail.