doc/dev/results

   1 Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   2 Copyright (C) 1999-2001  Internet Software Consortium.
   3 See COPYRIGHT in the source root or http://isc.org/copyright.html for terms.
   4
   5 $Id: results,v 1.7 2004/03/05 05:04:50 marka Exp $
   6
   7 Result Codes
   8
   9 The use of global variables or a GetLastError() function to return results
  10 doesn't work well in a multithreaded application.  The global variable has
  11 obvious problems, as does a global GetLastError().  A per-object GetLastError()
  12 seems more promising, e.g.
  13
  14         sometype_t s;
  15
  16         sometype_dosomething(s, buffer);
  17         if (sometype_error(s)) {
  18                 /* ... */
  19         }
  20
  21 If 's' is shared however this approach doesn't work unless the locking is
  22 done by the caller, e.g.
  23
  24         sometype_lock();
  25         sometype_dosomething(s, buffer);
  26         if (sometype_error(s)) {
  27                 /* ... */
  28         }
  29         sometype_unlock();
  30
  31 Those ISC and DNS libraries which have locks almost universally put the
  32 locking inside of the called routines, since it's more convenient for
  33 the calling programmer, makes for a cleaner API, and puts the burden
  34 of locking on the library programmer, who should know best what the
  35 locking needs of the routine are.
  36
  37 Because of this locking style the ISC and DNS libraries typically provide
  38 result information as the return value of the function.  E.g.
  39
  40         isc_result_t result;
  41
  42         result = isc_task_send(task, &event);
  43
  44 Note that an explicit result type is used, instead of mixing the error result
  45 type with the normal result type.  E.g. the C library routine getc() can
  46 return a character or EOF, but the BIND 9 style keeps the types of the
  47 function's return values separate.
  48
  49         char c;
  50
  51         result = isc_io_getc(stream, &c);
  52         if (result == ISC_R_SUCCESS) {
  53                 /* Do something with 'c'. */
  54         } else if (result == ISC_R_EOF) {
  55                 /* EOF. */
  56         } else {
  57                 /* Some other error. */
  58         }
  59
  60 Functions which cannot fail (assuming the caller has provided valid
  61 arguments) need not return a result type.  For example, dns_name_issubdomain()
  62 returns an isc_boolean_t, because it cannot fail.