TAO/tao/Environment.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file   Environment.h
   6  *
   7  * Declare the CORBA::Environment class.  Note that this header file
   8  * only requires a few forward declarations of CORBA classes, this
   9  * is *very* important because even the ORB needs to know about it;
  10  * make your changes with care.  It is also a good idea trying to
  11  * minimize cross dependencies between header files.
  12  *
  13  * @author Carlos O'Ryan <coryan@cs.wustl.edu>
  14  */
  15 //=============================================================================
  16
  17 #ifndef TAO_ENVIRONMENT_H
  18 #define TAO_ENVIRONMENT_H
  19
  20 #include /**/ "ace/pre.h"
  21
  22 #include /**/ "tao/TAO_Export.h"
  23
  24 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  25 # pragma once
  26 #endif /* ACE_LACKS_PRAGMA_ONCE */
  27
  28 #include "tao/Basic_Types.h"
  29 #include "tao/CORBA_methods.h"
  30 #include "tao/orbconf.h"
  31 #include "tao/Pseudo_VarOut_T.h"
  32 #include "tao/default_environment.h"
  33
  34 TAO_BEGIN_VERSIONED_NAMESPACE_DECL
  35
  36 class TAO_ORB_Core;
  37
  38 namespace CORBA
  39 {
  40   class Exception;
  41
  42   class Environment;
  43   typedef Environment *Environment_ptr;
  44   typedef TAO_Pseudo_Var_T<Environment> Environment_var;
  45   typedef TAO_Pseudo_Out_T<Environment> Environment_out;
  46
  47   /**
  48    * @class Environment
  49    *
  50    * @brief Environment
  51    *
  52    * A CORBA::Environment is a way to automagically ensure that
  53    * exception data is freed -- the "var" class for Exceptions.  It
  54    * adds just a bit of convenience function support, helping
  55    * classify exceptions as well as reducing memory leakage.
  56    * The thread has a default environment to simplify porting
  57    * between platforms that support native C++ exceptions and those
  58    * that don't. This is a TSS resource (always), but with a twist:
  59    * if the user creates a new environment the old one is "pushed"
  60    * (actually the new one remembers it), eventually the new
  61    * environment destructor pops itself from the stack and we
  62    * recover the old environment.  This means that if the user
  63    * create a new environment and somebody calls a function using
  64    * the default one the exception will still be received in the
  65    * environment created by the user.  The only drawback is that
  66    * environments life time must nest properly, this shouldn't be a
  67    * problem because environments are usually created on the stack,
  68    * but, the spec allows their creation on the heap and/or as class
  69    * members; we need to investigate the tradeoffs and take a
  70    * decision.
  71    */
  72   class TAO_Export Environment
  73   {
  74   public:
  75     /// The default constructor.  The environment will hold no
  76     /// exceptions.
  77     Environment () = default;
  78
  79     /// Copy constructor.
  80     Environment (const Environment &rhs);
  81
  82     /// Assingment.
  83     Environment &operator=(const Environment &rhs);
  84
  85     /// Destructor, release the exception.
  86     ~Environment ();
  87
  88     /// Some static methods that need to be defined in every pseudo object
  89     static Environment * _duplicate (Environment *);
  90     static Environment * _nil ();
  91
  92     /// Return the contained CORBA::Exception.
  93     /**
  94      * CORBA::Environment retains ownership of the exception, this is
  95      * contrary to the normal memory management rules in the C++
  96      * mapping, but actually mandated by the specification:
  97      *
  98      * "C++ Language Mapping" (formal/00-01-02). Section 1.27
  99      * Environment (page 1-113)
 100      */
 101     CORBA::Exception* exception () const;
 102
 103     /// Set the contained CORBA::Exception to @a ex
 104     /**
 105      * CORBA::Environment assumes ownership of the exception, this is
 106      * contrary to the normal memory management rules in the C++
 107      * mapping, but actually mandated by the specification:
 108      *
 109      * "C++ Language Mapping" (formal/00-01-02). Section 1.27
 110      * Environment (page 1-113)
 111      *
 112      */
 113     void exception (CORBA::Exception *ex);
 114
 115     /// Return if the exception is a user exception or a system
 116     /// exception.
 117     int exception_type () const;
 118
 119     /// return the repository ID for the exception.
 120     const char *exception_id () const;
 121
 122     /// Clear the exception.
 123     void clear ();
 124
 125     /// Print the exception to output determined by f.  This function
 126     /// is not CORBA compliant.
 127     void print_exception (const char *info, FILE *f=stdout) const;
 128
 129     // = Obtain a default environment to use with TAO.
 130     static CORBA::Environment &default_environment ();
 131
 132     // Useful for template programming.
 133     typedef CORBA::Environment_ptr _ptr_type;
 134     typedef CORBA::Environment_var _var_type;
 135     typedef CORBA::Environment_out _out_type;
 136
 137   private:
 138     /// Initialize using a well known ORB Core; this is intended for
 139     /// the bootstrapping of the ORB_Core, not for general
 140     /// consumption.
 141     Environment (TAO_ORB_Core *orb_core);
 142
 143     /// Pointer to the exception object contained in the environment.
 144     CORBA::Exception *exception_ {};
 145
 146     /// The previous environment on the "default environment stack".
 147     Environment *previous_ {};
 148   };
 149
 150   template<>
 151   inline void release (Environment_ptr env)
 152   {
 153     delete env;
 154   }
 155 } // End CORBA namespace
 156
 157 TAO_END_VERSIONED_NAMESPACE_DECL
 158
 159
 160 #if defined (__ACE_INLINE__)
 161 # include "tao/Environment.inl"
 162 #endif /* __ACE_INLINE__ */
 163
 164 #include /**/ "ace/post.h"
 165 #endif /* TAO_ENVIRONMENT_H */