Slice classes are mapped to C++ classes with the same name. The generated class contains a public data member for each Slice data member, and a virtual member function for each operation. Consider the following class definition:
class TimeOfDay {
short hour; // 0 ‑ 23
short minute; // 0 ‑ 59
short second; // 0 ‑ 59
string format(); // Return time as hh:mm:ss
};
class TimeOfDay;
typedef IceInternal::ProxyHandle<IceProxy::TimeOfDay> TimeOfDayPrx;
typedef IceInternal::Handle<TimeOfDay> TimeOfDayPtr;
class TimeOfDay : virtual public Ice::Object {
public:
Ice::Short hour;
Ice::Short minute;
Ice::Short second;
virtual std::string format() = 0;
TimeOfDay() {};
TimeOfDay(Ice::Short, Ice::Short, Ice::Short);
virtual bool ice_isA(const std::string&);
virtual const std::string& ice_id();
static const std::string& ice_staticId();
typedef TimeOfDayPrx ProxyType;
typedef TimeOfDayPtr PointerType;
// ...
};
1. The generated class TimeOfDay inherits from
Ice::Object. This means that all classes implicitly inherit from
Ice::Object, which is the ultimate ancestor of all classes. Note that
Ice::Object is
not the same as
IceProxy::Ice::Object. In other words, you
cannot pass a class where a proxy is expected and vice versa. (However, you
can pass a proxy for the class—see
Section 6.14.6.)
6.
The compiler generates a type definition TimeOfDayPtr. This type implements a smart pointer that wraps dynamically-allocated instances of the class. In general, the name of this type is
<class‑name>Ptr. Do not confuse this with
<class‑name>Prx—that type exists as well, but is the proxy handle for the class, not a smart pointer.
Like interfaces, classes implicitly inherit from a common base class, Ice::Object. However, as shown in
Figure 6.1, classes inherit from
Ice::Object instead of
Ice::ObjectPrx (which is at the base of the inheritance hierarchy for proxies). As a result, you cannot pass a class where a proxy is expected (and vice versa) because the base types for classes and proxies are not compatible.
Ice::Object contains a number of member functions:
namespace Ice {
class Object : public IceInternal::GCShared {
public:
virtual bool ice_isA(const std::string&,
const Current& = Current()) const;
virtual void ice_ping(const Current& = Current()) const;
virtual std::vector<std::string> ice_ids(
const Current& = Current()) const;
virtual const std::string& ice_id(
const Current& = Current()) const;
static const std::string& ice_staticId();
virtual Ice::Int ice_hash() const;
virtual ObjectPtr ice_clone() const;
virtual void ice_preMarshal();
virtual void ice_postUnmarshal();
virtual DispatchStatus ice_dispatch(
Ice::Request&,
const DispatchInterceptorAsyncCallbackPtr& = 0);
virtual bool operator==(const Object&) const;
virtual bool operator!=(const Object&) const;
virtual bool operator<(const Object&) const;
virtual bool operator<=(const Object&) const;
virtual bool operator>(const Object&) const;
virtual bool operator>=(const Object&) const;
};
}
The member functions of Ice::Object behave as follows:
•
operator==
operator!=
operator<
operator<=
operator>
operator>=By default, data members of classes are mapped exactly as for structures and exceptions: for each data member in the Slice definition, the generated class contains a corresponding public data member.
If you wish to restrict access to a data member, you can modify its visibility using the
protected metadata directive. The presence of this directive causes the Slice compiler to generate the data member with protected visibility. As a result, the member can be accessed only by the class itself or by one of its subclasses. For example, the
TimeOfDay class shown below has the
protected metadata directive applied to each of its data members:
class TimeOfDay {
["protected"] short hour; // 0 ‑ 23
["protected"] short minute; // 0 ‑ 59
["protected"] short second; // 0 ‑ 59
string format(); // Return time as hh:mm:ss
};
class TimeOfDay : virtual public Ice::Object {
public:
virtual std::string format() = 0;
// ...
protected:
Ice::Short hour;
Ice::Short minute;
Ice::Short second;
};
For a class in which all of the data members are protected, the metadata directive can be applied to the class itself rather than to each member individually. For example, we can rewrite the
TimeOfDay class as follows:
["protected"] class TimeOfDay {
short hour; // 0 ‑ 23
short minute; // 0 ‑ 59
short second; // 0 ‑ 59
string format(); // Return time as hh:mm:ss
};
Classes have a default constructor. This constructor default-constructs each data member. This means that, for members of simple built‑in type, such as integers, the default constructor performs no initialization, whereas members of complex type, such as strings, sequences, and dictionaries, are initialized by their own default constructor.
In addition, classes have a second constructor that has one parameter for each data member. This allows you to construct and initialize a class instance in a single statement (instead of first having to construct the instance and then assigning to its members).
For derived classes, the constructor has one parameter for each of the base class’s data members, plus one parameter for each of the derived class’s data members, in base-to-derived order. For example:
class Base {
int i;
};
class Derived extends Base {
string s;
};
class Base : virtual public ::Ice::Object
{
public:
::Ice::Int i;
Base() {};
explicit Base(::Ice::Int);
// ...
};
class Derived : virtual public Base
{
public:
::std::string s;
Derived() {};
Derived(::Ice::Int, const ::std::string&);
// ...
};
Operations of classes are mapped to pure virtual member functions in the generated class. This means that, if a class contains operations (such as the
format operation of our
TimeOfDay class), you must provide an implementation of the operation in a class that is derived from the generated class. For example:
2
class TimeOfDayI : virtual public TimeOfDay {
public:
virtual std::string format() {
std::ostringstream s;
s << setw(2) << setfill('0') << hour << ":";
s << setw(2) << setfill('0') << minute << ":";
s << setw(2) << setfill('0') << second;
return s.c_str();
}
protected:
virtual ~TimeOfDayI() {} // Optional
};
Having created a class such as TimeOfDayI, we have an implementation and we can instantiate the
TimeOfDayI class, but we cannot receive it as the return value or as an out-parameter from an operation invocation. To see why, consider the following simple interface:
When a client invokes the get operation, the Ice run time must instantiate and return an instance of the
TimeOfDay class. However,
TimeOfDay is an abstract class that cannot be instantiated. Unless we tell it, the Ice run time cannot magically know that we have created a
TimeOfDayI class that implements the abstract
format operation of the
TimeOfDay abstract class. In other words, we must provide the Ice run time with a factory that knows that the
TimeOfDay abstract class has a
TimeOfDayI concrete implementation. The
Ice::Communicator interface provides us with the necessary operations:
module Ice {
local interface ObjectFactory {
Object create(string type);
void destroy();
};
local interface Communicator {
void addObjectFactory(ObjectFactory factory, string id);
ObjectFactory findObjectFactory(string id);
// ...
};
};
To supply the Ice run time with a factory for our TimeOfDayI class, we must implement the
ObjectFactory interface:
module Ice {
local interface ObjectFactory {
Object create(string type);
void destroy();
};
};
The object factory’s create operation is called by the Ice run time when it needs to instantiate a
TimeOfDay class. The factory’s
destroy operation is called by the Ice run time when its communicator is destroyed. A possible implementation of our object factory is:
class ObjectFactory : public Ice::ObjectFactory {
public:
virtual Ice::ObjectPtr create(const std::string& type) {
assert(type == M::TimeOfDay::ice_staticId());
return new TimeOfDayI;
}
virtual void destroy() {}
};
The create method is passed the type ID (see
Section 4.13) of the class to instantiate. For our
TimeOfDay class, the type ID is
"::M::TimeOfDay". Our implementation of
create checks the type ID: if it matches, the method instantiates and returns a
TimeOfDayI object. For other type IDs, the method asserts because it does not know how to instantiate other types of objects.
Note that we used the ice_staticId method to obtain the type ID rather than embedding a literal string. Using a literal type ID string in your code is discouraged because it can lead to errors that are only detected at run time. For example, if a Slice class or one of its enclosing modules is renamed and the literal string is not changed accordingly, a receiver will fail to unmarshal the object and the Ice run time will raise
NoObjectFactoryException. By using
ice_staticId instead, we avoid any risk of a misspelled or obsolete type ID, and we can discover at compile time if a Slice class or module has been renamed.
Given a factory implementation, such as our ObjectFactory, we must inform the Ice run time of the existence of the factory:
Ice::CommunicatorPtr ic = ...;
ic‑>addObjectFactory(new ObjectFactory,
M::TimeOfDay::ice_staticId());
Now, whenever the Ice run time needs to instantiate a class with the type ID "::M::TimeOfDay", it calls the
create method of the registered
ObjectFactory instance.
The destroy operation of the object factory is invoked by the Ice run time when the communicator is destroyed. This gives you a chance to clean up any resources that may be used by your factory. Do not call
destroy on the factory while it is registered with the communicator—if you do, the Ice run time has no idea that this has happened and, depending on what your
destroy implementation is doing, may cause undefined behavior when the Ice run time tries to next use the factory.
The run time guarantees that destroy will be the last call made on the factory, that is,
create will not be called concurrently with
destroy, and
create will not be called once
destroy has been called. However, calls to
create can be made concurrently.
Note that you cannot register a factory for the same type ID twice: if you call addObjectFactory with a type ID for which a factory is registered, the Ice run time throws an
AlreadyRegisteredException.
Finally, keep in mind that if a class has only data members, but no operations, you need not create and register an object factory to transmit instances of such a class. Only if a class has operations do you have to define and register an object factory.
A recurring theme for C++ programmers is the need to deal with memory allocations and deallocations in their programs. The difficulty of doing so is well known: in the face of exceptions, multiple return paths from functions, and callee-allocated memory that must be deallocated by the caller, it can be extremely difficult to ensure that a program does not leak resources. This is particularly important in multi-threaded programs: if you do not rigorously track ownership of dynamic memory, a thread may delete memory that is still used by another thread, usually with disastrous consequences.
To alleviate this problem, Ice provides smart pointers for classes. These smart pointers use reference counting to keep track of each class instance and, when the last reference to a class instance disappears, automatically delete the instance.
3 Smart pointers are generated by the Slice compiler for each class type. For a Slice class
<class‑name>, the compiler generates a C++ smart pointer called
<class‑name>Ptr. Rather than showing all the details of the generated class, here is the basic usage pattern: whenever you allocate a class instance on the heap, you simply assign the pointer returned from
new to a smart pointer for the class. Thereafter, memory management is automatic and the class instance is deleted once the last smart pointer for it goes out of scope:
{ // Open scope
TimeOfDayPtr tod = new TimeOfDayI; // Allocate instance
// Initialize...
tod‑>hour = 18;
tod‑>minute = 11;
tod‑>second = 15;
// ...
} // No memory leak here!
As you can see, you use operator‑> to access the members of the class via its smart pointer. When the
tod smart pointer goes out of scope, its destructor runs and, in turn, the destructor takes care of calling
delete on the underlying class instance, so no memory is leaked.
Figure 6.2 shows the situation after default-constructing a smart pointer as follows:
Constructing a class instance creates that instance with a reference count of zero; the assignment to the class pointer causes the smart pointer to increment the class’s reference count:
tod = new TimeOfDayI; // Refcount == 1
Assigning or copy-constructing a smart pointer assigns and copy-constructs the smart pointer (not the underlying instance) and increments the reference count of the instance:
TimeOfDayPtr tod2(tod); // Copy‑construct tod2
TimeOfDayPtr tod3;
tod3 = tod; // Assign to tod3
This decrements the reference count of the class originally denoted by tod2 and increments the reference count of the class that is assigned to
tod2. The resulting situation is shown in
Figure 6.5.
If a smart pointer goes out of scope, is cleared, or has a new instance assigned to it, the smart pointer decrements the reference count of its instance; if the reference count drops to zero, the smart pointer calls
delete to deallocate the instance. The following code snippet deallocates the instance on the right by assigning
tod2 to
tod3:
TimeOfDayPtr tod = new TimeOfDayI(2, 3, 4); // Create instance
TimeOfDayPtr tod2 = new TimeOfDayI(*tod); // Copy instance
TimeOfDayPtr tod3 = new TimeOfDayI;
*tod3 = *tod; // Assign instance
Copying and assignment in this manner performs a memberwise shallow copy or assignment, that is, the source members are copied into the target members; if a class contains class members (which are mapped as smart pointers), what is copied or assigned is the smart pointer, not the target of the smart pointer.
class Node {
int i;
Node next;
};
NodePtr p1 = new Node(99, new Node(48, 0));
NodePtr p2 = new Node(23, 0);
// ...
*p2 = *p1; // Assignment
class TimeOfDayI;
typedef IceUtil::Handle<TimeOfDayI> TimeOfDayIPtr;
class TimeOfDayI : virtual public TimeOfDay {
// As before...
};
TimeOfDayIPtr tod1 = new TimeOfDayI;
TimeOfDayIPtr tod2 = new TimeOfDayI(*tod1); // Make copy
Of course, if your implementation class contains raw pointers (for which a memberwise copy would almost certainly be inappropriate), you must implement your own copy constructor and assignment operator that take the appropriate action (and probably call the base copy constructor or assignment operator to take care of the base part).
Note that the preceding code uses TimeOfDayIPtr as a typedef for
IceUtil::Handle<TimeOfDayI>. This class is a template that contains the smart pointer implementation. If you want smart pointers for the implementation of an abstract class, you must define a smart pointer type as illustrated by this type definition.
Copying and assignment of classes also works correctly for derived classes: you can assign a derived class to a base class, but not vice-versa; during such an assignment, the derived part of the source class is sliced, as per the usual C++ assignment semantics.
Polymorphic Copying of Classes
As shown in Section 6.14.1 on page 237, the C++ mapping generates an
ice_clone member function for every class:
class TimeOfDay : virtual public Ice::Object {
public:
// ...
virtual Ice::ObjectPtr ice_clone() const;
};
This member function makes a polymorphic shallow copy of a class: members that are not class members are deep copied; all members that are class members are shallow copied. To illustrate, consider the following class definition:
class Node {
Node n1;
Node n2;
};
Assume that we have an instance of this class, with the n1 and
n2 members initialized to point at separate instances, as shown in
Figure 6.10.
If we call ice_clone on the instance on the left, we end up with the situation shown in
Figure 6.11.
As you can see, class members are shallow copied, that is, ice_clone makes a copy of the class instance on which it is invoked, but does not copy any class instances that are pointed at by the copied instance.
Note that ice_clone returns a value of type
Ice::ObjectPtr, to avoid problems with compilers that do not support covariant return types. The generated
Ptr classes contain a
dynamicCast member that allows you to safely down-cast the return value of
ice_clone. For example, the code to achieve the situation shown in
Figure 6.11 looks as follows:
NodePtr p1 = new Node(new Node, new Node);
NodePtr p2 = NodePtr::dynamicCast(p1‑>ice_clone());
ice_clone is generated by the Slice compiler for concrete classes (that is, classes that do not have operations). However, because classes with operations are abstract, for abstract classes, the generated
ice_clone cannot know how to instantiate an instance of the derived concrete class (because the name of the derived class is not known). This means that, for abstract classes, the generated
ice_clone throws a
CloneNotImplementedException.
If you want to clone the implementation of an abstract class, you must override the virtual
ice_clone member in your concrete implementation class. For example:
class TimeOfDayI : public TimeOfDay {
public:
virtual Ice::ObjectPtr ice_clone() const
{
return new TimeOfDayI(*this);
}
};
A null smart pointer contains a null C++ pointer to its underlying instance. This means that if you attempt to dereference a null smart pointer, you get an
IceUtil::NullHandleException:
TimeOfDayPtr tod; // Construct null handle
try {
tod‑>minute = 0; // Dereference null handle
assert(false); // Cannot get here
} catch (const IceUtil::NullHandleException&) {
; // OK, expected
} catch (...) {
assert(false); // Must get NullHandleException
}
The Ice C++ mapping expects class instances to be allocated on the heap. Allocating class instances on the stack or in static variables is pragmatically useless because all the Ice APIs expect parameters that are smart pointers, not class instances. This means that, to do anything with a stack-allocated class instance, you must initialize a smart pointer for the instance. However, doing so does not work because it inevitably leads to a crash:
{ // Enter scope
TimeOfDayI t; // Stack‑allocated class instance
TimeOfDayPtr todp; // Handle for a TimeOfDay instance
todp = &t; // Legal, but dangerous
// ...
} // Leave scope, looming crash!
This goes badly wrong because, when todp goes out of scope, it decrements the reference count of the class to zero, which then calls
delete on itself. However, the instance is stack-allocated and cannot be deleted, and we end up with undefined behavior (typically, a core dump).
{ // Enter scope
TimeOfDayI t; // Stack‑allocated class instance
TimeOfDayPtr todp; // Handle for a TimeOfDay instance
todp = &t; // Legal, but dangerous
// ...
todp = 0; // Crash imminent!
}
This code attempts to circumvent the problem by clearing the smart pointer explicitly. However, doing so also causes the smart pointer to drop the reference count on the class to zero, so this code ends up with the same call to
delete on the stack-allocated instance as the previous example.
The upshot of all this is: never allocate a class instance on the stack or in a static variable. The C++ mapping assumes that all class instances are allocated on the heap and no amount of coding trickery will change this.
4
You can prevent allocation of class instances on the stack or in static variables by adding a protected destructor to your implementation of the class: if a class has a protected destructor, allocation must be made with
new, and static or stack allocation causes a compile time error. In addition, explicit calls to
delete on a heap-allocated instance also are flagged at compile time. You may want to habitually add a protected destructor to your implementation of abstract Slice classes to protect yourself from accidental heap allocation, as shown on
page 241. (For Slice classes that do not have operations, the Slice compiler automatically adds a protected destructor.)
Smart pointers are exception safe: if an exception causes the thread of execution to leave a scope containing a stack-allocated smart pointer, the C++ run time ensures that the smart pointer’s destructor is called, so no resource leaks can occur:
{ // Enter scope...
TimeOfDayPtr tod = new TimeOfDayI; // Allocate instance
someFuncThatMightThrow(); // Might throw...
// ...
} // No leak here, even if an exception is thrown
If an exception is thrown, the destructor of tod runs and ensures that it deallocates the underlying class instance.
There is one potential pitfall you must be aware of though: if a constructor of a base class throws an exception, and another class instance holds a smart pointer to the instance being constructed, you can end up with a double deallocation. Consider the following example, which reduces the problem to its bare-bones minimum:
class Base;
typedef IceUtil::Handle<Base> BasePtr;
class Listener : public virtual IceUtil::Shared {
public:
Listener(BasePtr p) {
_parent = p;
}
virtual ~Listener() {
_parent = 0;
}
private:
BasePtr _parent;
};
typedef IceUtil::Handle<Listener> ListenerPtr;
class Base : public virtual IceUtil::Shared {
public:
Base() {
_listener = new Listener(this);
}
virtual ~Base() {
_listener = 0;
}
private:
ListenerPtr _listener;
};
class Derived : public virtual Base {
public:
Derived() {
if (errorCondition)
throw "Some error";
}
};
typedef IceUtil::Handle<Derived> DerivedPtr;
int main()
{
try {
DerivedPtr d = new Derived;
} catch (...) {
// ...
}
return 0;
}
is executed in main and
errorCondition is true:
1. The Base constructor is called (because
Base is a base class of
Derived).
2.
The constructor of Base allocates an instance of
Listener, which results in a call to the
Listener constructor.
3.
The Listener constructor assigns its argument to the
_parent member, which leaves the reference count of the
Derived object being instantiated at one.
4.
The Listener constructor completes and returns control to the
Base constructor, which assigns the newly-constructed
Listener object to its
_listener member, of type
ListenerPtr. At this point, the reference count of the
Listener object changes from zero to one.
5.
The Base constructor completes, so the C++ run time continues to construct the
Derived object being instantiated by calling the
Derived constructor.
6.
The Derived constructor throws an exception. As a result, the C++ run time calls the
Base destructor.
7.
The Base destructor assigns null to its
_listener member, which drops the reference count of its
Listener object to zero. As a result, the
Listener object calls
delete this;.
8.
The Listener destructor runs and assigns null to its
_listener member. The
_listener smart pointer drops the reference count of its
Base object to zero. As a result, the
Base object calls
delete this;.
We can solve the problem by telling the Derived instance that it should
not deallocate itself while the
Derived constructor may still throw an exception. The
IceUtil::Shared class provides a
__setNoDelete member function that allows us to do this:
class Derived : public virtual Base {
public:
Derived() {
__setNoDelete(true);
if (errorCondition)
throw "Some error";
__setNoDelete(false);
}
};
Here, we have changed the Derived constructor to disable deallocation of its object until we know that no more exceptions can be thrown. Once the constructor is certain to complete successfully, it enables deallocation again, so the object will be deallocated once its reference count drops to zero.
One thing you need to be aware of is the inability of reference counting to deal with cyclic dependencies. For example, consider the following simple self-referential class:
class Node {
int val;
Node next;
};
Intuitively, this class implements a linked list of nodes. As long as there are no cycles in the list of nodes, everything is fine, and our smart pointers will correctly deallocate the class instances. However, if we introduce a cycle, we have a problem:
{ // Open scope...
NodePtr n1 = new Node; // N1 refcount == 1
NodePtr n2 = new Node; // N2 refcount == 1
n1‑>next = n2; // N2 refcount == 2
n2‑>next = n1; // N1 refcount == 2
} // Destructors run: // N2 refcount == 1,
// N1 refcount == 1, memory leak!
The nodes pointed to by n1 and
n2 do not have names but, for the sake of illustration, let us assume that
n1’s node is called N1, and
n2’s node is called N2. When we allocate the N1 instance and assign it to
n1, the smart pointer
n1 increments N1’s reference count to 1. Similarly, N2’s reference count is 1 after allocating the node and assigning it to
n2. The next two statements set up a cyclic dependency between
n1 and
n2 by making their
next pointers point at each other. This sets the reference count of both N1 and N2 to 2. When the enclosing scope closes, the destructor of
n2 is called first and decrements N2’s reference count to 1, followed by the destructor of
n1, which decrements N1’s reference count to 1. The net effect is that neither reference count ever drops to zero, so both N1 and N2 are leaked.
The previous example illustrates a problem that is generic to using reference counts for deallocation: if a cyclic dependency exists anywhere in a graph (possibly via many intermediate nodes), all nodes in the cycle are leaked.
To avoid memory leaks due to such cycles, Ice for C++ contains a garbage collector. The collector identifies class instances that are part of one or more cycles but are no longer reachable from the program and deletes such instances:
{ // Open scope...
NodePtr n1 = new Node; // N1 refcount == 1
NodePtr n2 = new Node; // N2 refcount == 1
n1‑>next = n2; // N1 refcount == 2
n2‑>next = n1; // N2 refcount == 2
} // Destructors run: // N2 refcount == 1,
// N1 refcount == 1
Ice::collectGarbage(); // Deletes N1 and N2
The call to Ice::collectGarbage deletes the no longer reachable instances N1 and N2 (as well as any other non-reachable instances that may have accumulated earlier).
•
Deleting leaked memory with explicit calls to the garbage collector can be inconvenient because it requires polluting the code with calls to the collector. You can ask the Ice run time to run a garbage collection thread that periodically cleans up leaked memory by setting the property
Ice.GC.Interval to a non-zero value.
5 For example, setting
Ice.GC.Interval to 5 causes the collector thread to run the garbage collector once every five seconds. You can trace the execution of the collector by setting
Ice.Trace.GC to a non-zero value (
Appendix C).
Note that the garbage collector is useful only if your program actually creates cyclic class graphs. There is no point in running the garbage collector in programs that do not create such cycles. (For this reason, the collector thread is disabled by default and runs only if you explicitly set
Ice.GC.Interval to a non-zero value.)
As for proxy handles (see Section 6.11.4 on page 224), class handles support the comparison operators
==,
!=, and
<. This allows you to use class handles in STL sorted containers. Be aware that, for smart pointers, object identity is
not used for the comparison, because class instances do not have identity. Instead, these operators simply compare the memory address of the classes they point to. This means that
operator== returns true only if two smart pointers point at the same physical class instance:
// Create a class instance and initialize
//
TimeOfDayIPtr p1 = new TimeOfDayI;
p1‑>hour = 23;
p1‑>minute = 10;
p1‑>second = 18;
// Create another class instance with
// the same member values
//
TimeOfDayIPtr p2 = new TimeOfDayI;
p2‑>hour = 23;
p2‑>minute = 10;
p2‑>second = 18;
assert(p1 != p2); // The two do not compare equal
TimeOfDayIPtr p3 = p1; // Point at first class again
assert(p1 == p3); // Now they compare equal
