GA++: C++ Bindings for Global Arrays
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Overview
========

GA++  provides a C++ interface to global arrays (GA) libraries. This is the
second beta release. Here is the doxygen documentation of GA++:

    http://www.emsl.pnl.gov/docs/global/ga++/index.html

The GA C++ bindings are a layer built directly on top of the GA C bindings.
GA++ provides new names for the C bindings of GA functions (For example,
GA_Add_patch() is renamed as addPatch()).

GA++ classes
============

GA++ declares a GA namespace.  Within this namespace is the GlobalArray class
and various "service" functions.  For backwards compatibility, the GAServices
class and its GA::SERVICES singleton is preserved within the GA namespace,
however we recommend using the same functions found within the GA namespace.

Although namespace is part of ANSI C++ standard, not all C++ compilers support
namespaces.  The configure script will automatically detect whether namespaces
are supported.  In the rare case where namespaces are not supported, you will
not be able to use the GA++ interface::

    namespace GA {
          class GAServices;
          class GlobalArray;
    };

The current implementation has no derived classes (no (virtual) inheritance),
templates or exception handling. Eventually, more object oriented
functionalities will be added, and standard library facilities will be used
without affecting the performance.

Initialization and Termination
==============================

GA namespace has the following functions for initialization and termination of
Global Arrays::

    GA::Initialize(): 
        Initialize Global Arrays, allocates and initializes internal data
        structures in Global Arrays. This is a collective operation. 

    GA::Terminate(): 
        Delete all active arrays and destroy internal data structures. This is
        a collective operation. 

    namespace GA {
          void Initialize(int argc, char *argv[], size_t limit = 0);

          void Initialize(int argc, char *argv[], unsigned long heapSize,
                          unsigned long stackSize, int type, size_t limit = 0);

          void Terminate();
    };

	Example:

    #include <iostream.h>
    #include "ga++.h"
        
    int 
    main(int argc, char **argv) {

         GA::Initialize(argc, argv, 0);
         cout << "Hello World\n";
         GA::Terminate();
    }
			 

GAServices
==========

NOTE: The GAServices class is deprecated in favor of using the same functions
directly within the GA namespace.

GAServices class has member functions that does all the global operations
(non-array operations) like Process Information (number of processes, process
id, ..), Inter-process Synchronization (sync, lock, broadcast, reduce,..),
etc,.

SERVICES Object
===============

NOTE: The SERVICES object is deprecated.  See GAServices above.

GA namespace has a global singleton "SERVICES" object (of type "GAServices"),
which can be used to invoke the non-array operations. To call the functions
(for example, sync()), we invoke them on this SERVICES object (for example,
GA::SERVICES.sync()). As this object is in the global address space, the
functions can be invoked from anywhere inside the program (provided the ga++.h
is included in that file/program).

Global Array
============

GlobalArray class has member functions that do: 
    *   Array operations, 
    *   One-sided(get/put), 
    *   Collective array operations, 
    *   Utility operations , etc,. 

Note:
In order to build GA++, configure must be run with --enable-cxx::

    configure --enable-cxx

Testing
=======

If the GA++ interface is enabled, the GA++ test programs located in
ga++/testing will automatically be built and run as part of the GA test suite.
See the top-level README for details.
