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.
276 lines
10 KiB
276 lines
10 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
|
|
------->
|
|
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<meta name="GENERATOR" content="Mozilla/4.7 [en] (X11; U; SunOS 5.7 sun4u) [Netscape]">
|
|
<meta name="sandia.approved" content="SAND99-1376">
|
|
<meta name="author" content="karen devine, kddevin@sandia.gov">
|
|
<title> Zoltan Developer's Guide: Adding Algorithms: How to handle memory</title>
|
|
|
|
</head>
|
|
<body bgcolor="#FFFFFF">
|
|
|
|
<div align=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>
|
|
| <a href="dev_add_params.html">Next</a> | <a href="dev_add_struct.html">Previous</a></i></b></div>
|
|
<!------------------------------------------------------------------------->
|
|
|
|
|
|
<h2>
|
|
Memory Management in Zoltan Algorithms</h2>
|
|
Zoltan uses a <a href="../ug_html/ug_util_mem.html">memory management
|
|
package</a> to simplify debugging of memory problems.
|
|
It is strongly recommended that algorithm
|
|
developers use the routines in this package, such as
|
|
<a href="../ug_html/ug_util_mem.html#Zoltan_Malloc"><b>ZOLTAN_MALLOC</b> </a>,
|
|
<a href="../ug_html/ug_util_mem.html#Zoltan_Calloc"><b>ZOLTAN_CALLOC</b> </a> and
|
|
<b><a href="../ug_html/ug_util_mem.html#Zoltan_Free">ZOLTAN_FREE</a></b>, instead
|
|
of the standard C routines for most memory management.
|
|
<p>
|
|
Macros that simplify the <a href="dev_lb_types.html#ID alloc">allocation of global and local identifiers (IDs)</a>
|
|
are defined in <i>zz/zz_id_const.h</i>. These macros are described in the
|
|
<a href="dev_lb_types.html">ID Data Types</a> section. The macros include
|
|
error checking for the allocations and, thus, their use is highly recommended.
|
|
|
|
<p>When a dynamic structure needs to be returned to the application,
|
|
special memory allocation routines are needed. For example, the import
|
|
and export lists of data to migrate are returned to an application from
|
|
<b><a href="../ug_html/ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>
|
|
and
|
|
<b><a href="../ug_html/ug_interface_mig.html#Zoltan_Invert_Lists">Zoltan_Invert_Lists</a></b>.
|
|
There are two special routines for managing memory for such situations,
|
|
called <b><a href="#Zoltan_Special_Malloc">Zoltan_Special_Malloc</a></b> and <b><a href="#Zoltan_Special_Free">Zoltan_Special_Free</a></b>.
|
|
Algorithms must use these functions to maintain compatibility with both
|
|
C and Fortran90 applications; these special routines manage memory in a
|
|
way that is compatible with both languages.
|
|
<p>Some load-balancing algorithms may contain persistent data structures,
|
|
that is, data structures that are preserved between calls to the load-balancing
|
|
routine. The <a href="dev_lb_structs.html"><b>Zoltan_Struct</b></a> structure contains a field
|
|
<a href="dev_add_struct.html"><i>LB.Data_Structure</i></a>
|
|
for this purpose, allowing multiple Zoltan structures to preserve
|
|
their own decomposition data. The developer should write a function that
|
|
frees this data structure. Use <b>Zoltan_RCB_Free_Structure </b>as an
|
|
example.
|
|
<p>
|
|
|
|
<!------------------------------------------------------------------------->
|
|
<hr>
|
|
<a NAME="Zoltan_Special_Malloc"></a>
|
|
<hr>
|
|
int <b>Zoltan_Special_Malloc</b>(struct
|
|
<b><a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a></b>
|
|
*<i>zz</i>, void **<i>array</i>, int <i>size</i>, <b>ZOLTAN_SPECIAL_MALLOC_TYPE</b><i>type</i>);
|
|
<hr>
|
|
<p>The <b>Zoltan_Special_Malloc</b> routine allocates memory to be returned to the application by Zoltan (e.g., the result arrays
|
|
of
|
|
<b><a href="../ug_html/ug_interface_lb.html#Zoltan_LB_Partition">Zoltan_LB_Partition</a></b>
|
|
and
|
|
<b><a href="../ug_html/ug_interface_mig.html#Zoltan_Invert_Lists">Zoltan_Invert_Lists</a></b>).
|
|
Returned memory must be allocated by <b>Zoltan_Special_Malloc</b> to insure it is allocated
|
|
by the same language as the application. Memory allocated by <b>Zoltan_Special_Malloc</b>
|
|
must be deallocated by <b><a href="#Zoltan_Special_Free">Zoltan_Special_Free</a></b>.
|
|
<br>
|
|
<table WIDTH="100%" >
|
|
<tr VALIGN=TOP>
|
|
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
|
|
|
|
<td WIDTH="80%"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> zz</i></td>
|
|
|
|
<td>The Zoltan structure currently in use.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> array</i></td>
|
|
|
|
<td>
|
|
Upon return, a pointer to the allocated space.
|
|
Usually of type int** or <b><a href="dev_lb_types.html">ZOLTAN_ID_PTR</a></b>*.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> size</i></td>
|
|
|
|
<td>The number of elements (not bytes) to be allocated.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP> <i>type</i></td>
|
|
|
|
<td>The type of array to allocate. Must be one of <b>ZOLTAN_SPECIAL_MALLOC_INT</b>,
|
|
<b>ZOLTAN_SPECIAL_MALLOC_GID</b>
|
|
or <b>ZOLTAN_SPECIAL_MALLOC_LID</b> for processor numbers, <a href="dev_lb_types.html">global IDs</a> and <a href="dev_lb_types.html">local IDs</a>, respectively.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><b>Returned Value:</b></td>
|
|
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP> int</td>
|
|
|
|
<td>1 if the allocation succeeded; 0 if it failed.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><b>Example:</b></td>
|
|
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP></td>
|
|
|
|
<td>
|
|
<tt>
|
|
ierr = <b>Zoltan_Special_Malloc</b>(<i>zz</i>, (void **)<i>import_gid</i>,
|
|
<br> <i>num_import</i>,
|
|
<br> <b>ZOLTAN_SPECIAL_MALLOC_GID</b>);
|
|
</tt>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP></td>
|
|
|
|
<td>Allocates an array with <i>num_import</i> <a href="dev_lb_types.html">global IDs</a>
|
|
and returns a pointer to the allocated space in <i>import_gid</i>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>
|
|
|
|
<!------------------------------------------------------------------------->
|
|
<hr>
|
|
<a NAME="Zoltan_Special_Free"></a>
|
|
<hr>
|
|
int <b>Zoltan_Special_Free</b>(struct <b><a href="dev_lb_structs.html#Zoltan_Struct">Zoltan_Struct</a></b>
|
|
*<i>zz</i>, void **<i>array</i>,<b> ZOLTAN_SPECIAL_MALLOC_TYPE</b> <i>type</i>);
|
|
<hr>
|
|
<p><b>Zoltan_Special_Free</b> frees memory allocated by <b><a href="#Zoltan_Special_Malloc">Zoltan_Special_Malloc</a></b>.
|
|
The array pointer is set to NULL upon return.
|
|
<br>
|
|
<table WIDTH="100%" >
|
|
<tr VALIGN=TOP>
|
|
<td VALIGN=TOP WIDTH="20%"><b>Arguments:</b></td>
|
|
|
|
<td WIDTH="80%"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> zz</i></td>
|
|
|
|
<td>The Zoltan structure currently in use.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><i> array</i></td>
|
|
|
|
<td>The array to be freed. Upon return, the pointer is set to NULL.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP> <i>type</i></td>
|
|
|
|
<td>The type of the array. Must be one of <b>ZOLTAN_SPECIAL_MALLOC_INT</b>,
|
|
<b>ZOLTAN_SPECIAL_MALLOC_GID</b>
|
|
or <b>ZOLTAN_SPECIAL_MALLOC_LID</b> for processor numbers, <a href="dev_lb_types.html">global IDs</a> and <a href="dev_lb_types.html">local IDs</a>, respectively.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><b>Returned Value:</b></td>
|
|
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP> int</td>
|
|
|
|
<td>1 if the deallocation succeeded; 0 if it failed.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP><b>Example:</b></td>
|
|
|
|
<td></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP></td>
|
|
|
|
<td>
|
|
<tt>
|
|
ierr = <b>Zoltan_Special_Free</b>(<i>zz</i>, (void **)<i>import_gid</i>,
|
|
<br> <b>ZOLTAN_SPECIAL_MALLOC_GID</b>);
|
|
</tt>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td VALIGN=TOP></td>
|
|
|
|
<td>Frees the <b><a href="dev_lb_types.html">global IDs</a></b>
|
|
array <i>import_gid</i> and sets it to NULL.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<p>
|
|
<!------------------------------------------------------------------------->
|
|
<hr WIDTH="100%">
|
|
<br>[<a href="dev.html">Table of Contents</a> | <a href="dev_add_params.html">Next:
|
|
Parameters</a> | <a href="dev_add_struct.html">Previous:
|
|
Data Structures</a> | <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
|
|
</body>
|
|
</html>
|
|
|