mirror of
https://github.com/PhasicFlow/phasicFlow.git
synced 2025-06-12 16:26:23 +00:00
Zoltan is added as thirdParty package
This commit is contained in:
Hamidreza
227
thirdParty/Zoltan/docs/dev_html/dev_cpp.html
vendored
Normal file
227
thirdParty/Zoltan/docs/dev_html/dev_cpp.html
vendored
Normal file
@ -0,0 +1,227 @@
|
||||
<!-------- @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.approved" CONTENT="SAND99-1376">
|
||||
<META NAME="author" CONTENT="lee ann fisk, lafisk@sandia.gov">
|
||||
|
||||
<TITLE> Zoltan Developer's Guide: C++ Interface</TITLE>
|
||||
</HEAD>
|
||||
<BODY BGCOLOR="#FFFFFF">
|
||||
|
||||
<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a> | <a href="dev_refs.html">Next</a> | <a href="dev_fortran.html">Previous</a></i></b></div>
|
||||
|
||||
|
||||
<H2>
|
||||
<A NAME="cpp dev"></A>C++ Interface</H2>
|
||||
As with the Fortran interface just described, any change to the user
|
||||
API of Zoltan should be reflected in the C++ interface. This section
|
||||
explains the conventions used in the C++ interface, which you will want
|
||||
to follow when you modify or expand it.
|
||||
|
||||
<UL><A HREF="#cpp dev classes">Classes</A><BR>
|
||||
<A HREF="#cpp dev conventions">Programming Conventions</A>
|
||||
<UL>
|
||||
<A HREF="#cpp dev namespaces"><I>Namespaces</I></A><BR>
|
||||
<A HREF="#cpp dev cnames"><I>Class names</I></A><BR>
|
||||
<A HREF="#cpp dev mnames"><I>Method names</I></A><BR>
|
||||
<A HREF="#cpp dev constmethods"><I>Const methods</I></A><BR>
|
||||
<A HREF="#cpp dev parameters"><I>Declaration of method parameters</I></A><BR>
|
||||
<A HREF="#cpp dev copy"><I>Copy constructor, copy operator</I></A>
|
||||
</UL>
|
||||
<A HREF="#cpp dev updating">Keeping the C++ interface up-to-date</A><BR>
|
||||
</UL>
|
||||
|
||||
<H3> <A NAME="cpp dev classes"></A>Classes</H3>
|
||||
The C language Zoltan library already observes the principles of
|
||||
object oriented program design. Each sub function of Zoltan (load
|
||||
balancing, timing, etc.) has a data structure
|
||||
associated with it. This data structure maintains all the state required
|
||||
for one instance of that sub function. Each request of the library for
|
||||
some operation requires that data structure.
|
||||
|
||||
<P>The classes in the Zoltan C++ library follow the structure just described.
|
||||
Each class is defined in a header
|
||||
file and encapsulates a Zoltan data structure and the functions that
|
||||
operate on that structure. A C++ application wishing to use a
|
||||
feature of Zoltan, would include the feature's header file in it's source, and
|
||||
link with the Zoltan C library.
|
||||
|
||||
<P>The C language load balancing data stucture
|
||||
(<B><A HREF="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</A></B>)
|
||||
and the C functions that operate on it are accessed
|
||||
through the C++ <B>Zoltan</B> class, defined in <I>zoltan_cpp.h</I>.
|
||||
|
||||
<P>The communication package is encapsulated the <B>Zoltan_Comm</B> class
|
||||
defined in <I>zoltan_comm_cpp.h</I>.
|
||||
Again, to use the communication utility of Zoltan from a C++ program,
|
||||
include <I>zoltan_comm_cpp.h</I> and use the C++ methods defined there.
|
||||
|
||||
<P>The C++ Zoltan timer class is called <B>Zoltan_Timer_Object</B> and
|
||||
is defined in <I>zoltan_timer_cpp.h</I>.
|
||||
|
||||
<P>The distributed directory utility of Zoltan is encapsulated in the
|
||||
class <B>Zoltan_DD</B> defined in <I>zoltan_dd_cpp.h</I>
|
||||
|
||||
<H3> <A NAME="cpp dev conventions"></A>Programming Conventions</H3>
|
||||
When modifying the interface to Zoltan , you will want to modify
|
||||
the appropriate C++ header file accordingly. This section describes the
|
||||
conventions to follow to maintain a consistent and correct library interface
|
||||
for the C++ user of Zoltan.
|
||||
|
||||
<H4><I><A NAME="cpp dev namespaces">Namespaces</A></I></H4>
|
||||
In order to maintain portability across platforms, there is no Zoltan
|
||||
namespace. Many C++ compilers do not support namespaces at this time.
|
||||
The name of each Zoltan class begins with <B>Zoltan_</B>, and hopefully
|
||||
this will never clash with another namespace.
|
||||
|
||||
<H4><I><A NAME="cpp dev cnames">Class names</A></I></H4>
|
||||
Class names are <B>Zoltan_</B> followed by text indicating the sub
|
||||
function of Zoltan that is encapsulated by the class.
|
||||
|
||||
<H4><I><A NAME="cpp dev mnames">Method names</A></I></H4>
|
||||
Method names are derived from the C library function names in such a
|
||||
way that the name will be obvious to a person familiar with the C library.
|
||||
We remove the beginning of the C library name, the part that identifies
|
||||
the subset of the Zoltan library that the function is part of, and keep
|
||||
the last part of the C library name, the part that describes what the
|
||||
function does. For example the C function <B>Zoltan_LB_Partition</B> becomes
|
||||
the C++ method <B>LB_Partition</B> in the class <B>Zoltan</B> and
|
||||
C function <B>Zoltan_Comm_Create</B> becomes the C++ method
|
||||
<B>Create</B> in the class <B>Zoltan_Comm</B>.
|
||||
|
||||
<H4><I><A NAME="cpp dev constmethods">Const methods</A></I></H4>
|
||||
All class methods which can be declared <B>const</B>, because they
|
||||
do not modify the object, should be declared <B>const</B>. This allows
|
||||
C++ programmers to call these methods on their <B>const</B> objects.
|
||||
|
||||
<H4><I><A NAME="cpp dev parameters">Declaration of method parameters</A></I></H4>
|
||||
|
||||
Parameters that are not changed in the method should be declared <B>const</B>.
|
||||
This can get complicated, but it helps to read declarations from right to
|
||||
left. <B>const int * & p</B> says <I>p is a reference to a pointer to
|
||||
a const int</I> and means the method will not change the value pointed
|
||||
to by <I>p</I>. On the other hand <B>int * const & p</B> says that
|
||||
<I>p is a reference to a const pointer to int</I> so the method will
|
||||
not change the pointer.
|
||||
|
||||
<P>Variables that are passed by value in a C function will be passed by
|
||||
const reference in the C++ method. This is semantically the same, but
|
||||
it is more efficient, and it will work with temporary variables created
|
||||
by a compiler.
|
||||
|
||||
<P>If a C function takes a pointer to a single built-in type (not an aggregate
|
||||
type), the associated C++ method will take a reference variable.
|
||||
If a C function takes a pointer to a pointer, the C++ function will take
|
||||
a pointer reference. The references are more efficient, and it is
|
||||
the behavior a C++ programmer expects.
|
||||
A pointer to an array remains a pointer to an array.
|
||||
|
||||
<P><TABLE rules=cols,rows frame=box align=center cellpadding=5>
|
||||
<TR> <TH>C function parameter</TH> <TH>C++ method parameter</TH> <TH> method's const behavior</TR>
|
||||
<TR> <TD>int val</TD>
|
||||
<TD>const int &val</TD>
|
||||
<TD>won't change value</TD></TR>
|
||||
<TR> <TD>int *singlep</TD>
|
||||
<TD>int &singlep <br> const int &singlep</TD>
|
||||
<TD>may change value <br> won't change value</TD></TR>
|
||||
<TR> <TD>int **singlep</TD>
|
||||
<TD>int *&singlep <br> const int * &p <br> int *const &p <br> const int * const &p</TD>
|
||||
<TD>may change pointer or value<br>won't change value<br>won't change pointer to value<br>won't change anything</TD></TR>
|
||||
<TR> <TD>int *arrayp</TD>
|
||||
<TD>int *arrayp <br> const int * arrayp</TD>
|
||||
<TD>may change array contents <br> won't change array contents</TD> </TR>
|
||||
</TABLE>
|
||||
|
||||
<P>If a C function takes a pointer to an array of <I>char</I>, the
|
||||
associated C++ method will take a <I>string</I> object.
|
||||
|
||||
<P><TABLE rules=cols,rows frame=box align=center cellpadding=5>
|
||||
<TR> <TH>C function parameter</TH> <TH>C++ method parameter</TH> </TR>
|
||||
<TR> <TD>char *fname</TD> <TD>std::string &fname</TD> </TR>
|
||||
</TABLE>
|
||||
|
||||
<P> In all honesty, it is tedious to carefully apply const'ness in
|
||||
parameter declarations, and we did not do it consistently throughout the
|
||||
C++ wrapping of Zoltan. Please feel free to add <I>const</I> declarations
|
||||
where they belong, and try to use them correctly if you add or modify Zoltan
|
||||
C++ methods.
|
||||
|
||||
<H4><I><A NAME="cpp dev copy">Copy constructor, copy operator</A></I></H4>
|
||||
Each class should have a copy constructor and a copy operator.
|
||||
|
||||
|
||||
<H3> <A NAME="cpp dev updating"></A>Keeping the C++ interface up-to-date</H3>
|
||||
Here we provide a checklist of things to be done when the C interface to
|
||||
the Zoltan library is changed:
|
||||
|
||||
<UL>
|
||||
<LI>If a new major component is added to Zoltan, create a C++ class for
|
||||
that component in a new header file, using the programming conventions
|
||||
described above. </LI>
|
||||
<LI>If functions are added or removed, or their parameter lists are
|
||||
changed, then update the header file defining the class that contains
|
||||
those functions.</LI>
|
||||
<LI>When Zoltan data structures are changed, be sure to change the C functions
|
||||
that copy the data structure. (They contain <B>Copy</B> in their name.)
|
||||
Correct copying is more important in C++,
|
||||
where the compiler may generate new temporary objects, than it is in C.</LI>
|
||||
<LI>If you change the C++ API, be sure to change:
|
||||
<UL>
|
||||
<LI><B>zCPPdrive</B>, the test program for the Zoltan C++ library</LI>
|
||||
<LI>the C++ examples in the <B>Examples</B> directory</LI>
|
||||
<LI>the method prototypes in the <A HREF="../ug_html/ug.html">Zoltan User's Guide</A>.</LI>
|
||||
</UL>
|
||||
</UL>
|
||||
|
||||
<HR WIDTH="100%">
|
||||
<BR>[<A HREF="dev.html">Table of Contents</A> | <A HREF="dev_refs.html">Next:
|
||||
References</A> | <A HREF="dev_fortran.html">Previous:
|
||||
FORTRAN Interface</A> | <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
|
||||
</BODY>
|
||||
</HTML>
|
||||
Reference in New Issue
Block a user