nucleus/library/basis/outcome.h

   1 #ifndef OUTCOME_CLASS
   2 #define OUTCOME_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : outcome                                                           *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 1990-$now By Author.  This program is free software; you can  *
  11 * redistribute it and/or modify it under the terms of the GNU General Public  *
  12 * License as published by the Free Software Foundation; either version 2 of   *
  13 * the License or (at your option) any later version.  This is online at:      *
  14 *     http://www.fsf.org/copyleft/gpl.html                                    *
  15 * Please send any updates to: fred@gruntose.com                               *
  16 \*****************************************************************************/
  17
  18 #include "definitions.h"
  19
  20 namespace basis {
  21
  22 //! Outcomes describe the state of completion for an operation.
  23 /*!
  24   These are an extremely simple representation of a non-exceptional exit
  25   value as an integer.  The range of expression is from 0 to MAXINT.
  26   Outcomes are meant to represent the category of 'how' the operation
  27   completed; they do not carry along any results of 'what' was produced.
  28 */
  29
  30 class outcome
  31 {
  32 public:
  33   outcome(int value = 0) : c_outcome_value(value) {}
  34     //!< Represents the completion of an operation as a particular "value".
  35     /*!< The outcomes partition the input space of the operation and represent
  36     the different conclusions possible during processing.  Values for outcomes
  37     must be maintained on a system-wide basis as unique identifiers for them
  38     to be meaningful.  Note that zero is reserved as a default outcome value.
  39     This usually translates to an outcome of OKAY. */
  40
  41   ~outcome() { c_outcome_value = 0; }  //!< destructor resets outcome value.
  42
  43   bool equal_to(const outcome &to_compare) const
  44       { return c_outcome_value == to_compare.c_outcome_value; }
  45     //!< Returns true if this outcome is equal to "to_compare".
  46     /*!< comparisons between outcomes will operate properly provided that
  47     all system-wide outcome values are unique. */
  48
  49   bool operator == (int to_compare) const
  50       { return c_outcome_value == to_compare; }
  51     //!< Returns true if this outcome is equal to the integer "to_compare".
  52
  53   int value() const { return c_outcome_value; }
  54     //<! returns the numerical value for the outcome.
  55
  56   int packed_size() const { return 4; }
  57     //!< a convenience function for those packing outcomes.
  58     /*!< this is inconveniently hard-coded, since packing is only available in the structures
  59     library and not at the base. */
  60
  61 private:
  62   int c_outcome_value;  //<! the numerical id for the outcome.
  63 };
  64
  65 //////////////
  66
  67 //! checks if the outcome indicates non-okay completion and returns it if so.
  68 #define PROMOTE_OUTCOME(outc) \
  69   if (outc != common::OKAY) return outc
  70
  71 //////////////
  72
  73 //! Provides a way to define auto-generated outcome values.
  74 /*! This macro provides a way to mark our outcome values so that parsers
  75 can find all of them when needed.
  76 NOTE: do not use the macro in CPP files; it's only for headers.  if you
  77 define outcomes in CPP files, they will not be added to the build
  78 manifest, nor will they be guaranteed to be unique or auto-generated. */
  79
  80 #define DEFINE_OUTCOME(NAME, CURRENT_VALUE, INFO_STRING) \
  81   NAME = CURRENT_VALUE
  82
  83 //! Similar to standard outcomes (above), but these cannot be auto-incremented.
  84 /*! This macro specifies an outcome definition where the value is constant,
  85 because it must participate in a network API.  Standard outcomes are just
  86 return values from method calls signifying completion, but the API style
  87 outcomes can be used to describe remote procedural invocations.  Thus, once
  88 they are established with unique values, those values cannot change. */
  89
  90 #define DEFINE_API_OUTCOME(NAME, CURRENT_VALUE, INFO_STRING) \
  91   NAME = CURRENT_VALUE
  92
  93 //////////////
  94
  95 } //namespace.
  96
  97 #endif
  98