You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
183 lines
7.9 KiB
183 lines
7.9 KiB
<!-------- @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>
|
|
|