<!-------- @HEADER
!
! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!
! Zoltan Toolkit for Load-balancing, Partitioning, Ordering and Coloring
! Copyright 2012 Sandia Corporation
!
! Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
! the U.S. Government retains certain rights in this software.
!
! Redistribution and use in source and binary forms, with or without
! modification, are permitted provided that the following conditions are
! met:
!
! 1. Redistributions of source code must retain the above copyright
! notice, this list of conditions and the following disclaimer.
!
! 2. Redistributions in binary form must reproduce the above copyright
! notice, this list of conditions and the following disclaimer in the
! documentation and/or other materials provided with the distribution.
!
! 3. Neither the name of the Corporation nor the names of the
! contributors may be used to endorse or promote products derived from
! this software without specific prior written permission.
!
! THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
! EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
! PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
! CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
! EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
! PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
! PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
! LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
! NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
! SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
!
! Questions? Contact Karen Devine kddevin@sandia.gov
! Erik Boman egboman@sandia.gov
!
! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!
! @HEADER
------->
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="GENERATOR" CONTENT="Mozilla/4.04 [en] (X11; U; SunOS 4.1.3_U1 sun4m) [Netscape]">
<meta name="sandia.approval_type" content="formal">
<meta name="sandia.approved" content="SAND2007-4748W">
<meta name="author" content="Zoltan PI">
<TITLE>Zoltan User's Guide: C++ Interface</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<div ALIGN=right><b><i><a href="ug.html">Zoltan User's Guide</a> | <a href="ug_fortran.html">Next</a> | <a href="ug_usage.html">Previous</a></i></b></div>
<H2>
<A NAME="cpp ug"></A>C++ Interface</H2>
The C++ interface to the Zoltan library is contained in the header files
listed below.
Each header file defines one class. Each class represents a Zoltan
data structure and the functions that operate on that data structure.
The class methods in the header files call functions in the Zoltan C library.
So to use the C++ interface from your application, include
the appropriate header file and link with the Zoltan C library.
<P><TABLE rules=cols,rows frame=box align=center cellpadding=5>
<TR> <TH>header file</TH> <TH>class</TH></TR>
<TR> <TD><I>include/zoltan_cpp.h</I></TD>
<TD><B>Zoltan</B>, representing a
<a href="ug_interface_init.html">load balancing</a> instance</TD>
<TR> <TD><I>Utilities/Communication/zoltan_comm_cpp.h</I></TD>
<TD><B>Zoltan_Comm</B>, representing an
<a href="ug_util_comm.html">unstructured communication</a> instance </TD>
</TR>
<TR> <TD><I>Utilities/DDirectory/zoltan_dd_cpp.h</I></TD>
<TD><B>Zoltan_DD</B>, representing a
<a href="ug_util_dd.html">distributed directory</a> instance </TD>
</TR>
<TR> <TD><I>Utilities/Timer/zoltan_timer_cpp.h</I></TD>
<TD><B>Zoltan_Timer</B>, representing a timer instance </TD>
</TR>
</TABLE>
<p>
More detailed information about the interface may be found in the
<a href="../dev_html/dev_cpp.html">Zoltan Developer's Guide</a>.
<p>
Simple examples of the use of the interface may be found in the
<I>examples/CPP</I> directory. A more complete example is the
test driver <a href="../dev_html/dev_driver.html">zCPPdrive</a>. The
source code for this test driver is in the <I>driver</I> directory.
<p>
A note on declaring application registered query functions from a
C++ application may be found in the section titled
<a href="ug_query.html">Application-Registered Query Functions</a>.
<p>
Two peculiarities of the wrapping of Zoltan with C++ classes are
mentioned here:
<ol>
<li>
You must call the C language function
<a href="ug_interface_init.html#Zoltan_Initialize"><I>Zoltan_Initialize</I> </a>
before using the C++ interface to the Zoltan library. This function should only
be called once. Due to design choices,
the C++ interface maintains no global state that is
independent of any instantiated objects, so it does not know if the
function has been called or not. Therefore, the C++ wrappers do not call
<a href="ug_interface_init.html#Zoltan_Initialize"><I>Zoltan_Initialize</I> </a>
for you.
<li>
It is preferable to allocate <B>Zoltan</B> objects dynamically so you can
explicitly delete them before your application exits.
(<B>Zoltan</B> objects allocated instead on the stack will be deleted
automatically at the completion of the scope in which they were created.)
The reason is that the <B>Zoltan</B>
destructor calls Zoltan_Destroy(), which makes an MPI call to free
the communicator in use by the <B>Zoltan</B> object. However the
MPI destructor may have been called before the <B>Zoltan</B>
destructor. In this case you
would receive an error while your application is exiting.
</ol>
This second point is illustrated in the good and bad example below.
<p>
<CENTER><TABLE BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
<TR>
<TD><A NAME="c++ item 1"></A>
<TT>int main(int argc, char *argv[])</tt><br>
<TT>{</tt><br>
<TT> MPI::Init(argc, argv);</tt><br>
<TT> int rank = MPI::COMM_WORLD.Get_rank();</tt><br>
<TT> int size = MPI::COMM_WORLD.Get_size();</tt><br><br>
<TT> //<I>Initialize the Zoltan library with a C language call</I></TT><br>
<TT> float version;</TT><br>
<TT> Zoltan_Initialize</A>(argc, argv, &version);</TT><br><br>
<TT> //<I>Dynamically create Zoltan object.</I></tt><br>
<TT> Zoltan *zz = new Zoltan(MPI::COMM_WORLD);</tt><br>
<TT> zz->Set_Param("LB_METHOD", "RCB");</tt><br><br>
<TT> //<I>Several lines of code would follow, working with zz</I></tt><br><br>
<TT> //<I>Explicitly delete the Zoltan object</I></tt><br>
<TT> delete zz;</tt><br>
<TT> MPI::Finalize();</tt><br>
<TT> }</tt><br>
</TR>
<CAPTION ALIGN=BOTTOM><I>Good example, Zoltan object is dynamically allocated
and explicity deleted before exit.</I></CAPTION>
</TABLE></CENTER>
<br>
<br>
<CENTER><TABLE BORDER=2 COLS=1 WIDTH="90%" NOSAVE >
<TR>
<TD><A NAME="c++ item 2"></A>
<TT>int main(int argc, char *argv[])</tt><br>
<TT>{</tt><br>
<TT>Zoltan zz;</tt><br><br>
<TT> MPI::Init(argc, argv);</tt><br>
<TT> int rank = MPI::COMM_WORLD.Get_rank();</tt><br>
<TT> int size = MPI::COMM_WORLD.Get_size();</tt><br><br>
<TT> //<I>Initialize the Zoltan library with a C language call</I></TT><br>
<TT> float version;</TT><br>
<TT> Zoltan_Initialize</A>(argc, argv, &version);</TT><br><br>
<TT> zz.Set_Param("LB_METHOD", "RCB");</tt><br><br>
<TT> //<I>Several lines of code would follow, working with zz</I></tt><br><br>
<TT> MPI::Finalize();</tt><br>
<TT> }</tt><br>
</TR>
<CAPTION ALIGN=BOTTOM><I>Bad example, the MPI destructor may execute before the
Zoltan destructor at process exit.</I></CAPTION>
</TABLE></CENTER>
<br>
<br>
<HR WIDTH="100%">[<A HREF="ug.html">Table of Contents</A> |
<A HREF="ug_fortran.html">Next: Fortran Interface</A>
| <A HREF="ug_usage.html">Previous: Zoltan Usage</A> | <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</BODY>
</HTML>