13.3 Using var Classes

Automatic variables (vars) are provided to simplify memory management. Vars are provided through a var class that assumes ownership for the memory required for the type and frees the memory when the instance of the var object is destroyed or when a new value is assigned to the var object.

The Oracle Tuxedo provides var classes for the following types:

• String (CORBA::String_var)
• Object references (CORBA::Object_var)
• User-defined OMG IDL types (struct, union, sequence, array, and interface)

The var classes have common member functions, but may support additional operators depending upon the OMG IDL type. For an OMG IDL type TYPE, the TYPE_var class contains constructors, destructors, assignment operators, and operators to access the underlying TYPE type. An example var class is as follows:

class TYPE_var
    {
    public:
        // constructors
        TYPE_var();
        TYPE_var(TYPE *);
        TYPE_var(const TYPE_var &);
        // destructor
        ~TYPE_var();

        // assignment operators
        TYPE_var &operator=(TYPE *);
        TYPE_var &operator=(const TYPE_var &);

       // accessor operators
       TYPE *operator->();
       TYPE *operator->() const;
       TYPE_var_ptr in() const;
       TYPE_var_ptr& inout();
       TYPE_var_ptr& out();

       TYPE_var_ptr _retn();
       operator const TYPE_ptr&() const;
       operator TYPE_ptr&();
       operator TYPE_ptr;
       };

The details of the member functions are as follows:

TYPE_var()

This is the default constructor for the TYPE_var class. The constructor initializes to 0 (zero) the TYPE * owned by the var class. You may not invoke the operator-> on a TYPE_var class unless a valid TYPE * has been assigned to it.

TYPE_var(TYPE * Value);

This constructor assumes ownership of the specified TYPE * parameter. When the TYPE_ var is destroyed, the TYPE is released. The Value argument is a pointer to the TYPE to be owned by this var class. This pointer must not be 0 (zero).

TYPE_var(const TYPE_var &From);

This copy constructor allocates a new TYPE and makes a deep copy of the data contained in the TYPE owned by the From parameter. When the TYPE_ var is destroyed, the copy of the TYPE is released or deleted. The From parameter specifies the var class that points to the TYPE to be copied.

~TYPE_var();

This destructor uses the appropriate mechanism to release the TYPE owned by the var class. For strings, this is the CORBA::string_free routine. For object references, this is the CORBA::release routine. For other types, this may be delete or a generated static routine used to free allocated memory.

TYPE_var &operator=(TYPE * NewValue);

This assignment operator assumes ownership of the TYPE pointed to by the NewValue parameter. If the TYPE_ var currently owns a TYPE, it is released before assuming ownership of the NewValue parameter. The NewValue argument is a pointer to the TYPE to be owned by this var class. This pointer must not be 0 (zero).

TYPE_var &operator=(const TYPE_var &From);

This assignment operator allocates a new TYPE and makes a deep copy of the data contained in the TYPE owned by the From TYPE_ var parameter. If TYPE_ var currently owns a TYPE, it is released. When the TYPE_ var is destroyed, the copy of the TYPE is released. The From parameter specifies the var class that points to the data to be copied.

TYPE *operator->(); TYPE *operator->() const;

These operators return a pointer to the TYPE owned by the var class. The var class continues to own the TYPE and it is the responsibility of the var class to release TYPE. You cannot use the operator-> until the var owns a valid TYPE. Do not try to release this return value or access this return value after the TYPE_var has been destroyed.

TYPE_var_ptr in() const; TYPE_var_ptr&inout(); TYPE_var_ptr&out(); TYPE_var_ptr _retn();

Because implicit conversions can sometimes cause a problem with some C++ compilers and with code readability, the TYPE _var types also support member functions that allow them to be explicitly converted for purposes of parameter passing. To pass a TYPE _var and an in parameter, call the in() member function; for inout parameters, the inout() member function; for out parameters, the out() member function. To obtain a return value from the TYPE _var, call the _return() function. For each TYPE _var type, the return types of each of these functions will match the type shown in the following table for the in, inout, out, and return modes for the underlying type TYPE, respectively.

Some differences occur in the operators supported for the user-defined data types. The following table describes the various operators supported by each OMG IDL data type, in the generated C++ code. Because the assignment operators are supported for all of the data types described in the following table, they are not included in the comparison.

Table 13-3 Comparison of Operators Supported for User-defined Data Type var Classes

OMG IDL Data Type	operator ->	operator []
struct	Yes	No
union	Yes	No
sequence	Yes	Yes, non-const only
array	No	Yes

The signatures are as shown in the following table.

Table 13-4 Operator Signatures for _var Classes

OMG IDL Data Type	Operator Member Functions
struct	TYPE * operator-> () TYPE * operator-> () const
union	TYPE * operator-> () TYPE * operator-> () const
sequence	TYPE * operator-> () TYPE * operator-> () const TYPE & operator[](CORBA::Long index)
array	TYPE_slice & operator[](CORBA::Long index) TYPE_slice & operator[](CORBA::Long index) const

• Sequence vars
  
• Array vars
  
• String vars