Main Page   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members   Related Pages  

Environment.h

Go to the documentation of this file.
00001 // This may look like C, but it's really -*- C++ -*-
00002 
00003 //=============================================================================
00004 /**
00005  *  @file   Environment.h
00006  *
00007  *  $Id: Environment.h,v 1.1.1.4 2003/02/21 18:36:44 chad Exp $
00008  *
00009  * Declare the CORBA_Environment class.  Note that this header file
00010  * only requires a few forward declarations of CORBA classes, this
00011  * is *very* important because even the ORB needs to know about it;
00012  * make your changes with care.  It is also a good idea trying to
00013  * minimize cross dependencies between header files.
00014  *
00015  *
00016  *  @author Carlos O'Ryan <coryan@cs.wustl.edu>
00017  */
00018 //=============================================================================
00019 
00020 
00021 #ifndef TAO_ENVIRONMENT_H
00022 #define TAO_ENVIRONMENT_H
00023 #include "ace/pre.h"
00024 
00025 #include "tao/corbafwd.h"
00026 
00027 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00028 # pragma once
00029 #endif /* ACE_LACKS_PRAGMA_ONCE */
00030 
00031 class TAO_ORB_Core;
00032 
00033 /**
00034  * @class CORBA_Environment
00035  *
00036  * @brief CORBA_Environment
00037  *
00038  * A CORBA_Environment is a way to automagically ensure that
00039  * exception data is freed -- the "var" class for Exceptions.  It
00040  * adds just a bit of convenience function support, helping
00041  * classify exceptions as well as reducing memory leakage.
00042  * The thread has a default environment to simplify porting
00043  * between platforms that support native C++ exceptions and those
00044  * that don't. This is a TSS resource (always), but with a twist:
00045  * if the user creates a new environment the old one is "pushed"
00046  * (actually the new one remembers it), eventually the new
00047  * environment destructor pops itself from the stack and we
00048  * recover the old environment.  This means that if the user
00049  * create a new environment and somebody calls a function using
00050  * the default one the exception will still be received in the
00051  * environment created by the user.  The only drawback is that
00052  * environments life time must nest properly, this shouldn't be a
00053  * problem because environments are usually created on the stack,
00054  * but, the spec allows their creation on the heap and/or as class
00055  * members; we need to investigate the tradeoffs and take a
00056  * decision.
00057  */
00058 class TAO_Export CORBA_Environment
00059 {
00060 public:
00061   // = Initialization and termination methods.
00062   /// The default constructor, the environment will hold no exceptions.
00063   CORBA_Environment (void);
00064 
00065   /// Copy constructor.
00066   CORBA_Environment (const CORBA_Environment &ACE_TRY_ENV);
00067 
00068   /// Assingment.
00069   CORBA_Environment &operator=(const CORBA_Environment &ACE_TRY_ENV);
00070 
00071   /// Destructor, release the exception.
00072   ~CORBA_Environment (void);
00073 
00074   /// Some static methods that need to be defined in every pseudo object
00075   static CORBA_Environment * _duplicate (CORBA_Environment *);
00076   static CORBA_Environment * _nil (void);
00077 
00078   /// Return the contained CORBA::Exception.
00079   /**
00080    * CORBA::Environment retains ownership of the exception, this is
00081    * contrary to the normal memory management rules in the C++
00082    * mapping, but actually mandated by the specification:
00083    *
00084    * "C++ Language Mapping" (formal/00-01-02). Section 1.27
00085    * Environment (page 1-113)
00086    *
00087    */
00088   CORBA_Exception* exception (void) const;
00089 
00090   /// Set the contained CORBA::Exception to <ex>
00091   /**
00092    * CORBA::Environment assumes ownership of the exception, this is
00093    * contrary to the normal memory management rules in the C++
00094    * mapping, but actually mandated by the specification:
00095    *
00096    * "C++ Language Mapping" (formal/00-01-02). Section 1.27
00097    * Environment (page 1-113)
00098    *
00099    */
00100   void exception (CORBA_Exception *ex);
00101 
00102   /// Return if the exception is a user exception or a system
00103   /// exception.
00104   int exception_type (void) const;
00105 
00106   /// return the repository ID for the exception.
00107   const char *exception_id (void) const;
00108 
00109   /// Clear the exception.
00110   void clear (void);
00111 
00112   /// Print the exception to output determined by f.  This function is
00113   /// not CORBA compliant.
00114   void print_exception (const char *info,
00115                         FILE *f=stdout) const;
00116 
00117   // = Obtain a default environment to use with TAO.
00118   static CORBA_Environment &default_environment (void);
00119 
00120 #if !defined(__GNUC__) || __GNUC__ > 2 || __GNUC_MINOR__ >= 8
00121   typedef CORBA_Environment_ptr _ptr_type;
00122   typedef CORBA_Environment_var _var_type;
00123 #endif /* __GNUC__ */
00124   // Useful for template programming.
00125 
00126 private:
00127 
00128   /// Initialize using a well known ORB Core; this is intended for the
00129   /// bootstraping of the ORB_Core, not for general consumption.
00130   friend class TAO_ORB_Core;
00131   CORBA_Environment (TAO_ORB_Core *orb_core);
00132 
00133   /// Pointer to the exception object contained in the environment.
00134   CORBA_Exception *exception_;
00135 
00136   /// The previous environment on the "default environment stack".
00137   CORBA_Environment *previous_;
00138 };
00139 
00140 /**
00141  * @class CORBA_Environment_var
00142  *
00143  * @brief CORBA_Environment_var
00144  *
00145  * Provide for automatic storage deallocation on going out of
00146  * scope.
00147  */
00148 class TAO_Export CORBA_Environment_var
00149 {
00150 public:
00151   /**
00152    * default constructor
00153    * copy constructor
00154    * destructor
00155    */
00156   CORBA_Environment_var (void);
00157   CORBA_Environment_var (CORBA_Environment_ptr);
00158   CORBA_Environment_var (const CORBA_Environment_var &);
00159   ~CORBA_Environment_var (void);
00160 
00161   CORBA_Environment_var &operator= (CORBA_Environment_ptr);
00162   CORBA_Environment_var &operator= (const CORBA_Environment_var &);
00163   CORBA_Environment_ptr operator-> (void) const;
00164 
00165   /// in, inout, out, _retn
00166   operator const CORBA_Environment_ptr &() const;
00167   operator CORBA_Environment_ptr &();
00168   CORBA_Environment_ptr in (void) const;
00169   CORBA_Environment_ptr &inout (void);
00170   CORBA_Environment_ptr &out (void);
00171   CORBA_Environment_ptr _retn (void);
00172   CORBA_Environment_ptr ptr (void) const;
00173 
00174 private:
00175   CORBA_Environment_ptr ptr_;
00176 };
00177 
00178 /**
00179  * @class CORBA_Environment_out
00180  *
00181  * @brief CORBA_Environment_out
00182  *
00183  * The _out class for CORBA_Environment. This is used to help in
00184  * managing the out parameters.
00185  */
00186 class TAO_Export CORBA_Environment_out
00187 {
00188 public:
00189   CORBA_Environment_out (CORBA_Environment_ptr &);
00190   CORBA_Environment_out (CORBA_Environment_var &);
00191   CORBA_Environment_out (const CORBA_Environment_out &);
00192   CORBA_Environment_out &operator= (const CORBA_Environment_out &);
00193   CORBA_Environment_out &operator= (CORBA_Environment_ptr);
00194   operator CORBA_Environment_ptr &();
00195   CORBA_Environment_ptr &ptr (void);
00196   CORBA_Environment_ptr operator-> (void);
00197 
00198 private:
00199   CORBA_Environment_ptr &ptr_;
00200 
00201   /// Assignment from _var not allowed.
00202   CORBA_Environment_out &operator= (const CORBA_Environment_var &);
00203 };
00204 
00205 #if defined (__ACE_INLINE__)
00206 # include "tao/Environment.i"
00207 #endif /* __ACE_INLINE__ */
00208 
00209 #include "ace/post.h"
00210 #endif /* TAO_ENVIRONMENT_H */

Generated on Mon Jun 16 13:48:22 2003 for TAO by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002