| Server IP : 82.208.35.60 / Your IP : 216.73.216.168 Web Server : Apache/2.4.55 (FreeBSD) OpenSSL/1.1.1q-freebsd PHP/7.3.31 System : FreeBSD server7.d2m.cz 12.4-RELEASE-p9 FreeBSD 12.4-RELEASE-p9 GENERIC amd64 User : studiokobylisy_cz ( 1008) PHP Version : 7.3.31 Disable Function : NONE MySQL : OFF | cURL : ON | WGET : OFF | Perl : OFF | Python : OFF | Sudo : OFF | Pkexec : OFF Directory : /usr/local/share/doc/mpdecimal/libmpdec/ |
Upload File : |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /><meta content="index,follow" name="robots" />
<meta content="libmpdec documentation" name="description" />
<title>Advanced Memory Handling — mpdecimal 2.5.1 documentation</title>
<link rel="stylesheet" href="_static/mpdecimal-doc.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/language_data.js"></script>
<link rel="search" title="Search" href="search.html" />
<link rel="prev" title="Various Functions" href="various.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="various.html" title="Various Functions"
accesskey="P">previous</a></li>
<li><a href="http://www.bytereef.org/mpdecimal/index.html">project home</a></li>
</ul>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Advanced Memory Handling</a><ul>
<li><a class="reference internal" href="#static-and-dynamic-decimals">Static and Dynamic Decimals</a></li>
<li><a class="reference internal" href="#shared-and-constant-decimals">Shared and Constant Decimals</a></li>
<li><a class="reference internal" href="#mpd-minalloc">MPD_MINALLOC</a></li>
<li><a class="reference internal" href="#resizing-decimals">Resizing Decimals</a></li>
<li><a class="reference internal" href="#custom-allocation-functions">Custom Allocation Functions</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="various.html"
title="previous chapter">Various Functions</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="advanced-memory-handling">
<span id="id1"></span><h1>Advanced Memory Handling</h1>
<p>The allocation scheme used in <strong>libmpdec</strong> allows for mixing statically
and dynamically allocated decimals. If a decimal with a static coefficient
needs to grow beyond the fixed array size, the coefficient automatically
switches to dynamic memory. This is very fast in practice and eliminates
the need for <code class="xref c c-func docutils literal notranslate"><span class="pre">alloca</span></code>.</p>
<p>It is <em>not necessary</em> to read this section if only dynamically allocated
decimals are used.</p>
<div class="section" id="static-and-dynamic-decimals">
<h2>Static and Dynamic Decimals</h2>
<p>Static and dynamic decimals may be mixed freely. In particular, they may
be used in the position of the <em>result operand</em> or passed as an argument
to <code class="xref c c-func docutils literal notranslate"><span class="pre">mpd_del</span></code>.</p>
<p>The coefficient of a static decimal <em>must</em> have the size <code class="xref c c-macro docutils literal notranslate"><span class="pre">MPD_MINALLOC_MAX</span></code>
(see below).</p>
<blockquote>
<div><table border="1" class="docutils align-default">
<colgroup>
<col width="37%" />
<col width="63%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td><code class="xref c c-macro docutils literal notranslate"><span class="pre">MPD_STATIC</span></code></td>
<td>if set, the <code class="xref c c-macro docutils literal notranslate"><span class="pre">mpd_t</span></code> struct is static</td>
</tr>
<tr class="row-even"><td><code class="xref c c-macro docutils literal notranslate"><span class="pre">MPD_STATIC_DATA</span></code></td>
<td>if set, the coefficient is static</td>
</tr>
</tbody>
</table>
</div></blockquote>
</div>
<div class="section" id="shared-and-constant-decimals">
<h2>Shared and Constant Decimals</h2>
<p>The coefficient of a decimal can be marked shared or constant. Decimals with
such coefficients <em>must not</em> be <em>result operands</em> or passed to <code class="xref c c-func docutils literal notranslate"><span class="pre">mpd_del</span></code>.
Since these flags are intended for internal use, the memory reallocation
functions only check for their presence using <code class="xref c c-func docutils literal notranslate"><span class="pre">assert</span></code>.</p>
<blockquote>
<div><table border="1" class="docutils align-default">
<colgroup>
<col width="41%" />
<col width="59%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td><code class="xref c c-macro docutils literal notranslate"><span class="pre">MPD_SHARED_DATA</span></code></td>
<td>if set, the coefficient is shared</td>
</tr>
<tr class="row-even"><td><code class="xref c c-macro docutils literal notranslate"><span class="pre">MPD_CONST_DATA</span></code></td>
<td>if set, the coefficient is constant</td>
</tr>
</tbody>
</table>
</div></blockquote>
</div>
<div class="section" id="mpd-minalloc">
<h2>MPD_MINALLOC</h2>
<p>In order to avoid frequent resizing operations, the global variable
<code class="xref c c-macro docutils literal notranslate"><span class="pre">MPD_MINALLOC</span></code> guarantees a minimum amount of allocated words for
the coefficient of each <code class="xref c c-macro docutils literal notranslate"><span class="pre">mpd_t</span></code>. The variable can be set <em>once</em>
at program start and all memory functions respect it. The minimum value
for <code class="xref c c-macro docutils literal notranslate"><span class="pre">MPD_MINALLOC</span></code> is <code class="xref c c-macro docutils literal notranslate"><span class="pre">MPD_MINALLOC_MIN=2</span></code>, the maximum value
is <code class="xref c c-macro docutils literal notranslate"><span class="pre">MPD_MINALLOC_MAX=64</span></code>.</p>
<div class="highlight-c notranslate" id="std:topic-mpd_setminalloc"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">mpd_setminalloc</span><span class="p">(</span><span class="n">mpd_ssize_t</span> <span class="n">n</span><span class="p">);</span>
</pre></div>
</div>
<p>At program start, set <code class="xref c c-macro docutils literal notranslate"><span class="pre">MPD_MINALLOC</span></code> to <em>n</em>. If <em>n</em> is outside the
limits, the function prints an error and exits. If an attempt is made to
set <code class="xref c c-macro docutils literal notranslate"><span class="pre">MPD_MINALLOC</span></code> a second time, the function does nothing but
print a warning.</p>
</div>
<div class="section" id="resizing-decimals">
<h2>Resizing Decimals</h2>
<p>When writing functions that operate directly on the data of a decimal,
it is necessary to resize the coefficient. All the above functions may
be called on static decimals, since they are smart enough to allocate
dynamic storage if the static array is too small. The functions
<em>must not</em> be called on constant or shared decimals.</p>
<span class="target" id="std:topic-mpd_qresize"></span><span class="target" id="std:topic-mpd_resize"></span><span class="target" id="std:topic-mpd_qresize_zero"></span><div class="highlight-c notranslate" id="std:topic-mpd_resize_zero"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">mpd_qresize</span><span class="p">(</span><span class="n">mpd_t</span> <span class="o">*</span><span class="n">result</span><span class="p">,</span> <span class="n">mpd_ssize_t</span> <span class="n">size</span><span class="p">,</span> <span class="kt">uint32_t</span> <span class="o">*</span><span class="n">status</span><span class="p">);</span>
<span class="kt">int</span> <span class="nf">mpd_resize</span><span class="p">(</span><span class="n">mpd_t</span> <span class="o">*</span><span class="n">result</span><span class="p">,</span> <span class="n">mpd_ssize_t</span> <span class="n">size</span><span class="p">,</span> <span class="n">mpd_context_t</span> <span class="o">*</span><span class="n">ctx</span><span class="p">);</span>
<span class="kt">int</span> <span class="nf">mpd_qresize_zero</span><span class="p">(</span><span class="n">mpd_t</span> <span class="o">*</span><span class="n">result</span><span class="p">,</span> <span class="n">mpd_ssize_t</span> <span class="n">size</span><span class="p">,</span> <span class="kt">uint32_t</span> <span class="o">*</span><span class="n">status</span><span class="p">);</span>
<span class="kt">int</span> <span class="nf">mpd_resize_zero</span><span class="p">(</span><span class="n">mpd_t</span> <span class="o">*</span><span class="n">result</span><span class="p">,</span> <span class="n">mpd_ssize_t</span> <span class="n">size</span><span class="p">,</span> <span class="n">mpd_context_t</span> <span class="o">*</span><span class="n">ctx</span><span class="p">);</span>
</pre></div>
</div>
<p><code class="xref c c-func docutils literal notranslate"><span class="pre">mpd_qresize</span></code> tries to resize result to size words. If the size is
increased, the existing coefficient data is left untouched. On success, 1
is returned. On failure, 0 is returned and <code class="xref c c-macro docutils literal notranslate"><span class="pre">MPD_Malloc_error</span></code> is
added to the status parameter.</p>
<p><code class="xref c c-func docutils literal notranslate"><span class="pre">mpd_qresize_zero</span></code> is the same, but initializes the complete
coefficient - including the old memory area - to zero.</p>
<div class="highlight-c notranslate" id="std:topic-mpd_minalloc"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">mpd_minalloc</span><span class="p">(</span><span class="n">mpd_t</span> <span class="o">*</span><span class="n">result</span><span class="p">);</span>
</pre></div>
</div>
<p>Reduce the size of the coefficient to <code class="xref c c-macro docutils literal notranslate"><span class="pre">MPD_MINALLOC</span></code> words. This
function cannot fail.</p>
</div>
<div class="section" id="custom-allocation-functions">
<h2>Custom Allocation Functions</h2>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">extern</span> <span class="kt">void</span> <span class="o">*</span><span class="p">(</span><span class="o">*</span> <span class="n">mpd_mallocfunc</span><span class="p">)(</span><span class="kt">size_t</span> <span class="n">size</span><span class="p">);</span>
<span class="k">extern</span> <span class="kt">void</span> <span class="o">*</span><span class="p">(</span><span class="o">*</span> <span class="n">mpd_callocfunc</span><span class="p">)(</span><span class="kt">size_t</span> <span class="n">nmemb</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">size</span><span class="p">);</span>
<span class="k">extern</span> <span class="kt">void</span> <span class="o">*</span><span class="p">(</span><span class="o">*</span> <span class="n">mpd_reallocfunc</span><span class="p">)(</span><span class="kt">void</span> <span class="o">*</span><span class="n">ptr</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">size</span><span class="p">);</span>
<span class="k">extern</span> <span class="nf">void</span> <span class="p">(</span><span class="o">*</span> <span class="n">mpd_free</span><span class="p">)(</span><span class="kt">void</span> <span class="o">*</span><span class="n">ptr</span><span class="p">);</span>
</pre></div>
</div>
<p>At program start, these variables can be set to custom memory allocation
functions. By default, they are set to the standard C functions.</p>
<span class="target" id="std:topic-mpd_alloc"></span><div class="highlight-c notranslate" id="std:topic-mpd_calloc"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="o">*</span><span class="nf">mpd_alloc</span><span class="p">(</span><span class="n">mpd_size_t</span> <span class="n">nmemb</span><span class="p">,</span> <span class="n">mpd_size_t</span> <span class="n">size</span><span class="p">);</span>
<span class="kt">void</span> <span class="o">*</span><span class="nf">mpd_calloc</span><span class="p">(</span><span class="n">mpd_size_t</span> <span class="n">nmemb</span><span class="p">,</span> <span class="n">mpd_size_t</span> <span class="n">size</span><span class="p">);</span>
</pre></div>
</div>
<p>Memory allocation with overflow checking, using the custom allocation
functions. If the allocation fails, <code class="xref c c-macro docutils literal notranslate"><span class="pre">NULL</span></code> is returned.</p>
<p>In the overflow case, the functions print an error and exit. Note
that overflow can only happen due to a serious programming error,
like using a context with invalid values.</p>
<div class="highlight-c notranslate" id="std:topic-mpd_realloc"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="o">*</span><span class="nf">mpd_realloc</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">ptr</span><span class="p">,</span> <span class="n">mpd_size_t</span> <span class="n">nmemb</span><span class="p">,</span> <span class="n">mpd_size_t</span> <span class="n">size</span><span class="p">,</span>
<span class="kt">uint8_t</span> <span class="o">*</span><span class="n">err</span><span class="p">);</span>
</pre></div>
</div>
<p>If successful, return the pointer to the new memory area. Otherwise,
return <em>ptr</em> and set <em>err</em> to 1.</p>
<p>Overflow handling as above.</p>
<div class="highlight-c notranslate" id="std:topic-mpd_sh_alloc"><div class="highlight"><pre><span></span><span class="cm">/* struct hack alloc */</span>
<span class="kt">void</span> <span class="o">*</span><span class="nf">mpd_sh_alloc</span><span class="p">(</span><span class="n">mpd_size_t</span> <span class="n">struct_size</span><span class="p">,</span> <span class="n">mpd_size_t</span> <span class="n">nmemb</span><span class="p">,</span>
<span class="n">mpd_size_t</span> <span class="n">size</span><span class="p">);</span>
</pre></div>
</div>
<p>Like <code class="xref c c-func docutils literal notranslate"><span class="pre">mpd_alloc</span></code>, with an additional parameter for <em>struct hack</em>
allocations.</p>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="various.html" title="Various Functions"
>previous</a></li>
<li><a href="http://www.bytereef.org/mpdecimal/index.html">project home</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2010-2020, Stefan Krah.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 2.4.4.
</div>
</body>
</html>