This coherence namespace contains the following general purpose namespaces:

• coherence::lang—the essential classes that comprise the object model

• coherence::util—utility code, including collections

• coherence::net—network and cache

• coherence::stl—C++ Standard Template Library integration

• coherence::io—serialization

Although each class is defined within its own header file, you can use namespace-wide header files to facilitate the inclusion of related classes. As a best practice include, at a minimum, coherence/lang.ns in code that uses this object model.

The coherence::lang::Object class is the root of the class hierarchy. This class provides the common interface for abstractly working with Coherence class instances. Object is an instantiable class that provides default implementations for the following functions.

• equals

• hashCode

• clone (optional)

• toStream (that is, writing an Object to an std::ostream)

See coherence::lang::Object in the C++ API for more information.

In addition to its public interface, the Object class provides several features used internally. Of these features, the reference counter is perhaps the most important. It provides automatic memory management for the object. This automatic management eliminates many of the problems associated with object reference validity and object deletion responsibility. This management reduces the potential of programming errors which may lead to memory leaks or corruption. This results in a stable platform for building complex systems.

The reference count, and other object "life-cycle" information, operates in an efficient and thread-safe manner by using lock-free atomic compare-and-set operations. This allows objects to be safely shared between threads without the risk of corrupting the count or of the object being unexpectedly deleted due to the action of another thread.

This section includes the following topics:

• Referencing Managed Objects
  
• Using handles
  
• Managed Object Instantiation
  

String::Handle hs = getStringFromElsewhere();
cout << "length is " << hs->length() << end1;

String::Handle hs = String::create("hello world");

String str("hello world");
String* ps = new String("hello world");

All objects within the model, including strings, are managed and extend from Object. Instead of using char* or std::string, the object model uses its own managed coherence::lang::String class. The String class supports ASCII and the full Unicode BML character set.

This section includes the following topics:

• String Instantiation
  
• Auto-Boxed Strings
  

const char*    pcstr = "hello world";
std:string     stdstr(pcstr);
String::Handle hs   = String::create(pcstr);
String::Handle hs2  = String::create(stdstr);

String::Handle hs = COH_TO_STRING("hello " << getName() << " it is currently " << getTime());

String::Handle hs  = "hello world";
String::Handle hs2 = stdstr;

Handles are type safe, in the following example, the compiler does not allow you to assign an Object::Handle to a String::Handle, because not all Objects are Strings.

Object::Handle ho = getObjectFromSomewhere();
String::Handel hs = ho; // does not compile

However, the following example does compile, as all Strings are Objects.

String::Handle hs = String::create("hello world");
Object::Handle ho = hs; // does compile

This section includes the following topics:

• Down Casting
  

Object::Handle ho = getObjectFromSomewhere();
String::Handle hs = cast<String::Handle>(ho);

Object::Handle ho = getObjectFromSomewhere();

if (instanceof<String::Handle>(ho))
  {
  String::Handle hs = cast<String::Handle>(ho);
  }
else if (instanceof<Integer32::Handle>(ho))
  {
  Integer32::Handle hn = cast<Integer32::Handle>(ho);
  }
else
  {
  ...
  }

Managed arrays are provided by using the coherence::lang::Array<T> template class. In addition to being managed and adding safe and automatic memory management, this class includes the overall length of the array, and bounds checked indexing.

You can index an array by using its Handle's subscript operator, as shown in this example:

Array<int32_t>::Handle harr = Array<int32_t>::create(10);

int32_t nTotal = 0;
for (size32_t i = 0, c = harr->length; i < c; ++i)
    {
    nTotal += harr[i];
    }

The object model supports arrays of C++ primitives and managed Objects. Arrays of derived Object types are not supported, only arrays of Object, casting must be employed to retrieve the derived handle type. Arrays of Objects are technically Array<MemberHolder<Object> >, and defined to ObjectArray for easier readability.

The coherence::util* namespace includes several collection classes and interfaces that may be useful in your application. These include:

• coherence::util::Collection —interface

• coherence::util::List—interface

• coherence::util::Set—interface

• coherence::util::Queue—interface

• coherence::util::Map—interface

• coherence::util::Arrays—implementation

• coherence::util::LinkedList—implementation

• coherence::util::HashSet—implementation

• coherence::util::DualQueue—implementation

• coherence::util::HashMap—implementation

• coherence::util::SafeHashMap—implementation

• coherence::util::WeakHashMap—implementation

• coherence::util::IdentityHashMap—implementation

These classes also appear as part of the Coherence Extend API.

Similar to ObjectArray, Collections contain Object::Holders, allowing them to store any managed object instance type. For example:

Map::Handle  hMap = HashMap::create();
String::View vKey = "hello world";

hMap->put(vKey, Integer32::create(123));

Integer32::Handle hValue = cast<Integer32::Handle>(hMap->get(vKey));

In the object model, exceptions are also managed objects. Managed Exceptions allow caught exceptions to be held as a local variable or data member without the risk of object slicing.

All Coherence exceptions are defined by using a throwable_spec and derive from the coherence::lang::Exception class, which derives from Object. Managed exceptions are not explicitly thrown by using the standard C++ throw statement, but rather by using a COH_THROW macro. This macro sets stack information and then calls the exception's raise method, which ultimately calls throw. The resulting thrown object may be caught an the corresponding exceptions View type, or an inherited View type. Additionally these managed exceptions may be caught as standard const std::exception classes. The following example shows a try/catch block with managed exceptions:

try
    {
    Object::Handle h = NULL;
    h->hashCode(); // trigger an exception
    }
catch (NullPointerException::View e)
    {
    cerr << "caught" << e <<endl;
    COH_THROW(e); // rethrow
    }

In C++ the information of how an object was declared (such as const) is not available from a pointer or reference to an object. For instance a pointer of type const Foo*, only indicates that the user of that pointer cannot change the objects state. It does not indicate if the referenced object was actually declared const, and is guaranteed not to change. The object model adds a run-time immutability feature to allow the identification of objects which can no longer change state.

The Object class maintains two reference counters: one for Handles and one for Views. If an object is referenced only from Views, then it is by definition immutable, as Views cannot change the state, and Handles cannot be obtained from Views. The isImmutable() method (included in the Object class) can test for this condition. The method is virtual, allowing subclasses to alter the definition of immutable. For example, String contains no non-const methods, and therefore has an isImmutable() method that always returns true.

Note that when immutable, an object cannot revert to being mutable. You cannot cast away const-ness to turn a View into a Handle as this would violate the proved immutability.

Immutability is important with caching. The Coherence NearCache and ContinuouQueryCache can take advantage of the immutability to determine if a direct reference of an object can be stored in the cache or if a copy must be created. Additionally, knowing that an object cannot change allows safe multi-threaded interaction without synchronization.

Frequently, existing classes must be integrated into the object model. A typical example would be to store a data-object into a Coherence cache, which only supports storage of managed objects. As it would not be reasonable to require that pre-existing classes be modified to extend from coherence::lang::Object, the object model provides an adapter which automatically converts a non-managed plain old C++ class instance into a managed class instance at run time.

This is accomplished by using the coherence::lang::Managed<T> template class. This template class extends from Object and from the supplied template parameter type T, effectively producing a new class which is both an Object and a T. The new class can be initialized from a T, and converted back to a T. The result is an easy to use, yet very powerful bridge between managed and non-managed code.

See the API doc for coherence::lang::Managed for details and examples.

Specification-based definitions (specs) enable you to quickly define managed classes in C++.

Specification-based definitions are helpful when you are writing your own implementation of managed objects.

There are various forms of specs used to create different class types:

• class_spec—standard instantiatable class definitions

• cloneable_spec—cloneable class definitions

• abstract_spec—non-instantiatable class definitions, with zero or more pure virtual methods

• interface_spec—for defining interfaces (pure virtual, multiply inheritable classes)

• throwable_spec—managed classes capable of being thrown as exceptions

Specs automatically define these features on the class being spec'd:

• Handles, Views, Holders

• static create() methods which delegate to protected constructors

• virtual clone() method delegating to the copy constructor

• virtual sizeOf() method based on ::sizeof()

• super typedef for referencing the class from which the defined class derives

• inheritance from coherence::lang::Object, when no parent class is specified by using extends<>

To define a class using specs, the class publicly inherits from the specs above. Each of these specs are parametrized templates. The parameters are as follows:

• The name of the class being defined.

• The class to publicly inherit from, specified by using an extends<> statement, defaults to extends<Object>

  • This element is not supplied in interface_spec

  • Except for extends<Object>, the parent class is not derived from virtually

• A list of interfaces implemented by the class, specified by using an implements<> statement

  • All interfaces are derived from using public virtual inheritance

Note that the extends<> parameter is note used in defining interfaces.

The following example illustrates using interface_spec to define a Comparable interface:

class Comparable
    : public interface_spec<Comparable>
    {
    public:
        virtual int32_t compareTo(Object::View v) const = 0;
    };

The following example illustrates using interface_spec to define a derived interface Number:

class Number
    : public interface_spec<Number,
        implements<Comparable> >
    {
    public:
        virtual int32_t getValue() const = 0;
    };

The following example uses cloneable_spec to produce an implementation.

class Integer
    : public cloneable_spec<Integer,
        extends<Object>,
        implements<Number> >
    {
    friend class factory<Integer>;

    protected:
        Integer(int32_t n)
            : super(), m_n(n)
            {
            }

        Integer(const Integer& that)
            : super(that), m_n(that.m_n)
            {
            }

    public:
        virtual int32_t getValue() const
            {
            return m_n;
            }

        virtual int32_t compareTo(Object::View v) const
            {
            return getValue() - cast<Integer::View>(v)->getValue();
            }

        virtual void toStream(std::ostream& out) const
            {
            out << getValue();
            }

    private:
        int32_t m_n;
    };

The class definition can also be defined without the use of specs. For example:

class Integer
    : public virtual Object, public virtual Number
    {
    public:
        typedef TypedHandle<const Integer> View;   // was auto-generated
        typedef TypedHandle<Integer>       Handle; // was auto-generated
        typedef TypedHolder<Integer>       Holder; // was auto-generated
        typedef super                      Object; // was auto-generated

        // was auto-generated
        static Integer::Handle create(const int32_t& n)
            {
            return new Integer(n);
            }

    protected:
        Integer(int32_t n)
            : super(), m_n(n)
            {
            }

        Integer(const Integer& that)
            : super(that), m_n(that.n)
            {
            }

    public:
        virtual int32_t getValue() const
            {
            return m_n;
            }

        virtual int32_t compareTo(Object::View v) const
            {
            return getValue() - cast<Integer::View>(v)->getValue();
            }

        virtual void toStream(std::ostream& out) const
            {
            out << getValue();
            }

        // was auto-generated
        virtual Object::Handle clone() const
            {
            return new Integer(*this);
            }

        // was auto-generated
        virtual size32_t sizeOf() const
            {
            return ::sizeof(Integer);
            }

    private:
        int32_t m_n;
    };

The following example illustrates using the spec'd class:

Integer::Handle hNum1 = Integer::create(123);
Integer::Handle hNum2 = Integer::create(456);

if (hNum1->compareTo(hNum2) > 0)
    {
    std::cout << hNum1 << " is greater then " << hNum2 << std::endl;
    }

Equality, Hashing, Cloning, Immutability, and Serialization all identify the state of an object and generally have similar implementation concerns. Simply put, all data members referenced in one of these methods, are likely referenced in all of the methods. Conversely any data members which are not referenced by one, should likely not be referenced by any of these methods.

Consider the simple case of a HashSet::Entry, which contains the well known key and value data members. These are to be considered in the equals method and would likely be tested for equality by using a call to their own equals method rather than through reference equality. If Entry also contains, as part of the implementation of the HashSet, a handle to the next Entry within the HashSet's bucket and perhaps also contains a handle back to the HashSet itself, should these be considered in equals as well? Likely not, it would seem reasonable that comparing two entries consisting of equal keys and values from two maps should be considered equal. Following this line of thought the hashCode method on Entry would completely ignore data members except for key and value, and hashCode would be computed using the results of its key and value hashCode, rather then using their identity hashCode. that is, a deep equality check in equals implies a deep hash in hashCode.

For clone, only the key and value (not all the data members) require cloning. To clone the parent Map as part of clone, the Entry would make no sense and a similar argument can be made for cloning the handle to the next Entry. This line of thinking can be extended to the isImmutable method, and to serialization as well. While it is certainly not a hard and fast rule, it is worth considering this approach when implementing any of these methods.

The object model includes managed threads, which allows for easy creation of platform independent, multi-threaded, applications. The threading abstraction includes support for creating, interrupting, and joining threads. Thread local storage is available from the coherence::lang::ThreadLocalreference class. Thread dumps are also available for diagnostic and troubleshooting purposes. The managed threads are ultimately wrappers around the system's native thread type, such as POSIX or Windows Threads. This threading abstraction is used internally by Coherence, but is available for the application, if necessary.

The following example illustrates how to create a Runnable instance and spawn a thread:

class HelloRunner
      : public class_spec<HelloRunner,
          extends<Object>,
          implements<Runnable> >
     {
     friend class factory<HelloRunner>;

     protected:
          HelloRunner(int cReps)
              : super(), m_cReps(cReps)
              {
              }

     public:
          virtual void run()
              {
              for (int i = 0; i < m_Reps; ++i)
                  {
                  Thread::sleep(1000);
                  std::cout << "hello world" << std::endl;
                  }
              }

      protected:
          int m_cReps;
      };

...

Thread::Handle hThread = Thread::create(HelloRunner::create(10));
hThread->start();
hThread->join();

Refer to coherence::lang::Thread and coherence::lang::Runnable for more information.

The primary functional limitation of a reference counting scheme is automatic cleanup of cyclical object graphs. Consider the simple bi-directional relationship illustrated in Figure 9-1.

In this picture, both A and B have a reference count of one, which keeps them active. What they do not realize is that they are the only things keeping each other active, and that no external references to them exist. Reference counting alone is unable to handle these self sustaining graphs and memory would be leaked.

The provided mechanism for dealing with graphs is weak references. A weak reference is one which references an object, but not prevent it from being deleted. As illustrated in Figure 9-2, the A->B->A issue could be resolved by changing it to the following.

Where A now has a weak reference to B. If B were to reach a point where it was only referenced weakly, it would clear all weak references to itself and then be deleted. In this simple example that would also trigger the deletion of A, as B had held the only reference to A.

Weak references allow for construction of more complicated structures then this. But it becomes necessary to adopt a convention for which references are weak and which are strong. Consider a tree illustrated in Figure 9-3. The tree consists of nodes A, B, C; and two external references to the tree X, and Y.

In this tree parent (A) use strong references to children (B, C), and children use weak references to their parent. With the picture as it is, reference Y could navigate the entire tree, starting at child B, and moving up to A, and then down to C. But what if reference X were to be reset to NULL? This would leave A only being weakly referenced and it would clear all weak references to itself, and be deleted. In deleting itself there would no longer be any references to C, which would also be deleted. At this point reference Y, without having taken any action would now refer to the situation illustrated in Figure 9-4.

This is not necessarily a problem, just a possibility which must be considered when using weak references. To work around this issue, the holder of Y would also likely maintain a reference to A to ensure the tree did not dissolve away unexpectedly.

See the Javadoc for coherence::lang::WeakReference, WeakHandle, and WeakView for usage details.

As is typical in C++, referencing an object under construction can be dangerous. Specifically references to this are to be avoided within a constructor, as the object initialization has not yet completed. For managed objects, creating a handle to this from the constructor usually causes the object to be destructed before it ever finishes being created. Instead, the object model includes support for virtual constructors. The virtual constructor onInit is defined by Object and can be overridden on derived classes. This method is called automatically by the object model just after construction completes, and just before the new object is returned from its static create method. Within the onInit method, it is safe to reference this to call virtual functions and to hand out references to the new object to other class instances. Any derived implementation of onInit must include a call to super::onInit() to allow the parent class to also initialize itself.

In addition to the Handle and View smart pointers (discussed previously), the object model contains several other specialized variants that can be used. For the most part use of these specialized smart pointers is limited to writing new managed classes, and they do not appear in normal application code.

Although the base Object class is thread-safe, this cannot provide automatic thread safety for the state of derived classes. As is typical it is up to each individual derived class implementation to provide for higher level thread-safety. The object model provides some facilities to aid in writing thread-safe code.

This section includes the following topics:

• Synchronization and Notification
  
• Thread Safe Handles
  
• Escape Analysis
  
• Thread-Local Allocator
  

SomeClass::Handle h = getObjectFromSomewhere();

COH_SYNCHRONIZED (h)
    {
    // monitor of Object referenced by h has been acquired

    if (h->checkSomeState())
        {
        h->actOnThatState();
        }
    } // monitor is automatically released

class Employee
    : public class_spec<Employee>
    {
    friend class factory<Employee>;

    protected:
        Employee(String::View vsName, int32_t nId)
            : super(), m_vsName(self(), vsName), m_nId(nId)
            {
            }

    public:
        String::View getName() const
            {
            return m_vsName; // read is automatically thread-safe
            }

        void setName(String::View vsName)
            {
            m_vsName = vsName; // write is automatically thread-safe
            }

        int32_t getId() const
            {
            return m_nId;
            }          

    private:
        MemberView<String>    m_vsName;
        const int32_t         m_nId;
    };

class Employee
    {
    public:
        Employee(String::View vsName, int32_t nId)
            : m_vsName(System::common(), vsName), m_nId(nId)
            {
            }

    public:
        String::View getName() const
            {
            return m_vsName;
            }

        void setName(String::View vsName)
            {
            m_vsName = vsName;
            }

        int32_t getId() const
            {
            return m_nId;
            }          

    private:
         MemberView<String> m_vsName;
         const int32_t m_nId;
    };

MemberView<NamedCache> MY_CACHE(System::common());

int main(int argc, char** argv)
    {
    MY_CACHE = CacheFactory::getCache(argv[0]);
    }

Logs can be enabled to view the efficiency of the thread-local allocator pool. To enable the logs, set the coherence.heap.logging system property to true.

The log entries indicate the memory location of the pool, the size of the pool, how many allocation areas are in the pool and the fraction of successful hits on the pool (the rate of finding a slot within the pool). The following example demonstrates a typical allocator log entry:

(thread=main): Allocator hit: pool=0x7f8e5ac039d0, size=128, slots=512, hit rate=0.62963

Thread dumps are available for diagnostic and troubleshooting purposes. These thread dumps also include the stack trace. You can generate a thread dump by performing a CTRL+BREAK (Windows) or a CTRL+BACKSLASH (UNIX). The following output illustrates a sample thread dump:

Thread dump Oracle Coherence for C++ v3.4b397 (Pre-release) (Apple Mac OS X x86 debug) pid=0xf853; spanning 190ms

"main" tid=0x101790 runnable: <native>
    at coherence::lang::Object::wait(long long) const
    at coherence::lang::Thread::dumpStacks(std::ostream&, long long)
    at main
    at start

"coherence::util::logging::Logger" tid=0x127eb0 runnable: Daemon{State=DAEMON_RUNNING, Notification=false, 
StartTimeStamp=1216390067197, WaitTime=0, ThreadName=coherence::util::logging::Logger}
    at coherence::lang::Object::wait(long long) const
    at coherence::component::util::Daemon::onWait()
    at coherence::component::util::Daemon::run()
    at coherence::lang::Thread::run()

While the managed object model reference counting helps prevent memory leaks they are still possible. The most common way in which they are triggered is through cyclical object graphs. The object model includes heap analysis support to help identify if leaks are occurring, by tracking the number of live objects in the system. Comparing this value over time provides a simple means of detecting if the object count is consistently increasing, and thereby likely leaking. After a probable leak has been detected, the heap analyzer can help track it down as well, by provided statistics on what types of objects appeared to have leaked.

Coherence provides a pluggable coherence::lang::HeapAnalyzer interface. The HeapAnalyzer implementation can be specified by using the coherence.heap.analyzer system property. The property can be set to the following values:

• none—No heap analysis is performed. This is the default.

• object—The coherence::lang::ObjectCountHeapAnalyzer is used. It provides simple heap analysis based solely on the count of the number of live objects in the system.

• class—The coherence::lang::ClassBasedHeapAnalyzer is used. It provides heap analysis at the class level, that is it tracks the number of live instances of each class, and the associated byte level usage.

• alloc —Specialization of coherence::lang::ClassBasedHeapAnalyzer which additionally tracks the allocation counts at the class level.

• custom—Lets you define your own analysis routines. You specify the name of a class registered with the SystemClassLoader.

Heap information is returned when you perform a CTRL+BREAK (Windows) or CTRL+BACKSLASH (UNIX).

The following output illustrates heap analysis information returned by the class-based analyzer. It returns the heap analysis delta resulting from the insertion of a new entry into a Map.

Space           Count           Class
44 B            1               coherence::lang::Integer32
70 B            1               coherence::lang::String
132 B           1               coherence::util::SafeHashMap::Entry

Total: 246 B, 3 objects, 3 classes

For all that the object model does to prevent memory corruption, it is typically used along side non-managed code which could cause corruption. Therefore, the object model includes memory corruption detection support. When enabled, the object model's memory allocator pads the beginning and end of each object allocation by a configurable number of pad bytes. This padding is encoded with a pattern which can later be validated to ensure that the pad has not been touched. If memory corruption occurs, and affects a pad, subsequent validations detect the corruption. Validation is performed when the object is destroyed.

The debug version of the Coherence C++ API has padding enabled by default, using a pad size of 2*(word size), on each side of an object allocation. In a 32-bit build, this adds 16 bytes per object. Increasing the size of the padding increases the chances of corruption affecting a pad, and thus the chance of detecting corruption.

The size of the pad can be configured by using the coherence.heap.padding system property, which can be set to the number of bytes for the pre/post pad. Setting this system property to a nonzero value enables the feature, and is available even in release builds.

The following output illustrates the results from an instance of memory corruption detection:

Error during ~MemberHolder: coherence::lang::IllegalStateException: memory corruption detected in 5B post-padding at offset 4 of memory allocated at 0x132095

The launcher named sanka works similar to java, in that it is provided with one or more shared libraries to load, and a fully qualified class name to execute.

ge: sanka [-options] <native class> [args...]
 
available options include:
    -l <native library list>  dynamic libraries to load, separated by : or ;
    -D<property>=<value>      set a system property
    -version                  print the Coherence version
    -?                        print this help message
    <native class>            the fully qualified class. For example,
                              coherence::net::CacheFactory

The specified libraries must either be accessible from the operating system library path (PATH, LD_LIBRARY_PATH, DYLD_LIBRARY_PATH), or they may be specified with an absolute or relative path. Library names may also leave off any operating specific prefix or suffix. For instance the UNIX libfoo.so or Windows foo.dll can be specified simply as foo. The Coherence shared library which the application was linked against must be accessible from the system's library path as well.

Several utility executables classes are included in the Coherence shared library:

• coherence::net::CacheFactory runs the Coherence C++ console

• coherence::lang::SystemClassLoader prints out the registered managed classes

• coherence::io::pof::SystemPofContext prints out the registered POF types

The later two executables can be optionally supplied with shared libraries to inspect, in which case they output the registration which exists in the supplied library rather then all registrations.

Applications can of course still be made executable in the traditional C++ means using a global main function. If desired you can make your own classes executable using Sanka as well. The following is a simple example of an executable class:

#include "coherence/lang.ns"
 
COH_OPEN_NAMESPACE2(my,test)
 
using namespace coherence::lang;
 
class Echo
    : public class_spec<Echo>
    {
    friend class factory<Echo>;
 
    public:
        static void main(ObjectArray::View vasArg)
            {
            for (size32_t i = 0, c = vasArg->length; i < c; ++i)
                {
                std::cout << vasArg[i] << std::endl;
                }
            }
    };
COH_REGISTER_EXECUTABLE_CLASS(Echo); // must appear in .cpp
 
COH_CLOSE_NAMESPACE2

As you can see the specified class must have been registered as an ExecutableClass and have a main method matching the following signature:

static void main(ObjectArray::View)

The supplied ObjectArray parameter is an array of String::View objects corresponding to the command-line arguments which followed the executable class name.

When linked into a shared library, for instance libecho.so or echo.dll, the Echo class can be run as follows:

> sanka -l echo my::test::Echo Hello World
Hello
World