blob: e5a24cc90ba6ed58144b57452a6d68f1db6bb8e2 [file] [log] [blame]
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>ImageMagick - MagickCore, C API: Memory Allocation</title>
<meta name="application-name" content="ImageMagick" />
<meta name="description" content="Use ImageMagick® to create, edit, compose, and convert digital images. Resize an image, crop it, change its shades and colors, add captions, and more." />
<meta name="application-url" content="https://imagemagick.org" />
<meta name="generator" content="PHP" />
<meta name="keywords" content="magickcore, c, api:, memory, allocation, image processing software" />
<meta name="rating" content="GENERAL" />
<meta name="robots" content="INDEX, FOLLOW" />
<meta name="generator" content="ImageMagick Studio LLC" />
<meta name="author" content="ImageMagick Studio LLC" />
<meta name="revisit-after" content="2 DAYS" />
<meta name="resource-type" content="document" />
<meta name="copyright" content="Copyright (c) 1999-2020 ImageMagick Studio LLC" />
<meta name="distribution" content="Global" />
<meta name="magick-serial" content="P131-S030410-R485315270133-P82224-A6668-G1245-1" />
<meta property='og:url' content='../../' />
<meta property='og:title' content='ImageMagick' />
<meta property='og:image' content='../../../images/logo.png' />
<meta property='og:type' content='website' />
<meta property='og:site_name' content='ImageMagick' />
<meta property='og:description' content="Create, Edit, Compose, or Convert Digital Images" />
<meta name="google-site-verification" content="_bMOCDpkx9ZAzBwb2kF3PRHbfUUdFj2uO8Jd1AXArz4" />
<link href="memory.html" rel="canonical" />
<link href="../../../images/wand.png" rel="icon" />
<link href="../../../images/wand.ico" rel="shortcut icon" />
<link href="../../assets/magick.css" rel="stylesheet" />
</head>
<body>
<nav class="navbar navbar-expand-md navbar-dark bg-dark fixed-top">
<div class="container-fluid">
<a class="navbar-brand" href="../../"><img class="d-block" id="icon" alt="ImageMagick" width="32" height="32" src="../../../images/wand.ico"/></a>
<button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#magick-navbars" aria-controls="magick-navbars" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<div class="collapse navbar-collapse" id="magick-navbars">
<ul class="navbar-nav me-auto mb-2 mb-md-0">
<li class="nav-item">
<a class="nav-link " href="../../www/index.html">Home</a>
</li>
<li class="nav-item">
<a class="nav-link " href="../../www/download.html">Download</a>
</li>
<li class="nav-item">
<a class="nav-link " href="../../www/command-line-tools.html">Tools</a>
</li>
<li class="nav-item">
<a class="nav-link " href="../../www/command-line-processing.html">CLI</a>
</li>
<li class="nav-item">
<a class="nav-link " href="../../www/develop.html">Develop</a>
</li>
<li class="nav-item">
<a class="nav-link" target="_blank" href="https://github.com/ImageMagick/ImageMagick/discussions">Community</a>
</li>
<li class="nav-item">
<iframe src="https://github.com/sponsors/ImageMagick/button" title="Sponsor ImageMagick" height="35" width="107" style="border: 0;"></iframe>
</li>
</ul>
<form class="d-flex form-inline" action="https://imagemagick.org/script/search.php">
<input class="form-control me-2" type="text" name="q" placeholder="Search" aria-label="Search">
<button class="btn btn-outline-success" type="submit" name="sa">Search</button>
</form>
</div>
</div>
</nav>
<div class="container">
<script async="async" src="https://localhost/pagead/js/adsbygoogle.js"></script>
<ins class="adsbygoogle"
style="display:block"
data-ad-client="ca-pub-3129977114552745"
data-ad-slot="6345125851"
data-full-width-responsive="true"
data-ad-format="horizontal"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>
</div>
<main class="container">
<div class="magick-template">
<div class="magick-header">
<p class="text-center"><a href="memory.html#AcquireCriticalMemory">AcquireCriticalMemory</a> &#8226; <a href="memory.html#AcquireAlignedMemory">AcquireAlignedMemory</a> &#8226; <a href="memory.html#AcquireMagickMemory">AcquireMagickMemory</a> &#8226; <a href="memory.html#AcquireCriticalMemory">AcquireCriticalMemory</a> &#8226; <a href="memory.html#AcquireQuantumMemory">AcquireQuantumMemory</a> &#8226; <a href="memory.html#AcquireVirtualMemory">AcquireVirtualMemory</a> &#8226; <a href="memory.html#CopyMagickMemory">CopyMagickMemory</a> &#8226; <a href="memory.html#GetMagickMemoryMethods">GetMagickMemoryMethods</a> &#8226; <a href="memory.html#GetVirtualMemoryBlob">GetVirtualMemoryBlob</a> &#8226; <a href="memory.html#RelinquishAlignedMemory">RelinquishAlignedMemory</a> &#8226; <a href="memory.html#RelinquishMagickMemory">RelinquishMagickMemory</a> &#8226; <a href="memory.html#RelinquishVirtualMemory">RelinquishVirtualMemory</a> &#8226; <a href="memory.html#ResetMagickMemory">ResetMagickMemory</a> &#8226; <a href="memory.html#ResizeMagickMemory">ResizeMagickMemory</a> &#8226; <a href="memory.html#ResizeQuantumMemory">ResizeQuantumMemory</a> &#8226; <a href="memory.html#SetMagickAlignedMemoryMethods">SetMagickAlignedMemoryMethods</a> &#8226; <a href="memory.html#SetMagickMemoryMethods">SetMagickMemoryMethods</a></p>
<h2><a href="../../api/MagickCore/memory_8c.html" id="AcquireCriticalMemory">AcquireCriticalMemory</a></h2>
<p>AcquireCriticalMemory(): allocate a small memory request with AcquireMagickMemory(), however, on fail throw a fatal exception and exit. Free the memory reserve with RelinquishMagickMemory(). AcquireAlignedMemory(): allocate a small memory request that is aligned on a cache line. On fail, return NULL for possible recovery. Free the memory reserve with RelinquishMagickMemory(). AcquireMagickMemory()/ResizeMagickMemory(): allocate a small to medium memory request, typically with malloc()/realloc(). On fail, return NULL for possible recovery. Free the memory reserve with RelinquishMagickMemory(). AcquireQuantumMemory()/ResizeQuantumMemory(): allocate a small to medium memory request. This is a secure memory allocator as it accepts two parameters, count and quantum, to ensure the request does not overflow. It also check to ensure the request does not exceed the maximum memory per the security policy. Free the memory reserve with RelinquishMagickMemory(). AcquireVirtualMemory(): allocate a large memory request either in heap, memory-mapped, or memory-mapped on disk depending on whether heap allocation fails or if the request exceeds the maximum memory policy. Free the memory reserve with RelinquishVirtualMemory(). ResetMagickMemory(): fills the bytes of the memory area with a constant byte.</p>
<p>In addition, we provide hooks for your own memory constructor/destructors.</p>
<dt>utilize our internal custom allocator as follows</dt>
<p>Segregate our memory requirements from any program that calls our API. This should help reduce the risk of others changing our program state or causing memory corruption.</p>
<p>Our custom memory allocation manager implements a best-fit allocation policy using segregated free lists. It uses a linear distribution of size classes for lower sizes and a power of two distribution of size classes at higher sizes. It is based on the paper, "Fast Memory Allocation using Lazy Fits." written by Yoo C. Chung.</p>
<p>By default, C's standard library is used (e.g. malloc); use the custom memory allocator by defining MAGICKCORE_ANONYMOUS_MEMORY_SUPPORT to allocate memory with private anonymous mapping rather than from the heap.</p>
<h2><a href="../../api/MagickCore/memory_8c.html" id="AcquireAlignedMemory">AcquireAlignedMemory</a></h2>
<p>AcquireAlignedMemory() returns a pointer to a block of memory whose size is at least (count*quantum) bytes, and whose address is aligned on a cache line.</p>
<p>The format of the AcquireAlignedMemory method is:</p>
<pre class="text">
void *AcquireAlignedMemory(const size_t count,const size_t quantum)
</pre>
<p>A description of each parameter follows:</p>
<dd>
</dd>
<dd> </dd>
<dl class="dl-horizontal">
<dt>count</dt>
<dd>the number of objects to allocate contiguously. </dd>
<dd> </dd>
<dt>quantum</dt>
<dd>the size (in bytes) of each object. </dd>
<dd> </dd>
</dl>
<h2><a href="../../api/MagickCore/memory_8c.html" id="AcquireMagickMemory">AcquireMagickMemory</a></h2>
<p>AcquireMagickMemory() returns a pointer to a block of memory at least size bytes suitably aligned for any use.</p>
<p>The format of the AcquireMagickMemory method is:</p>
<pre class="text">
void *AcquireMagickMemory(const size_t size)
</pre>
<p>A description of each parameter follows:</p>
<dd>
</dd>
<dd> </dd>
<dl class="dl-horizontal">
<dt>size</dt>
<dd>the size of the memory in bytes to allocate. </dd>
<dd> </dd>
</dl>
<h2><a href="../../api/MagickCore/memory_8c.html" id="AcquireCriticalMemory">AcquireCriticalMemory</a></h2>
<p>AcquireCriticalMemory() is just like AcquireMagickMemory(), throws a fatal exception if the memory cannot be acquired.</p>
<p>That is, AcquireCriticalMemory() returns a pointer to a block of memory that is at least size bytes, and that is suitably aligned for any use; however, if this is not possible, it throws an exception and terminates the program as unceremoniously as possible.</p>
<p>The format of the AcquireCriticalMemory method is:</p>
<pre class="text">
void *AcquireCriticalMemory(const size_t size)
</pre>
<p>A description of each parameter follows:</p>
<dd>
</dd>
<dd> </dd>
<dl class="dl-horizontal">
<dt>size</dt>
<dd>the size (in bytes) of the memory to allocate. </dd>
<dd> </dd>
</dl>
<h2><a href="../../api/MagickCore/memory_8c.html" id="AcquireQuantumMemory">AcquireQuantumMemory</a></h2>
<p>AcquireQuantumMemory() returns a pointer to a block of memory at least count * quantum bytes suitably aligned for any use.</p>
<p>The format of the AcquireQuantumMemory method is:</p>
<pre class="text">
void *AcquireQuantumMemory(const size_t count,const size_t quantum)
</pre>
<p>A description of each parameter follows:</p>
<dd>
</dd>
<dd> </dd>
<dl class="dl-horizontal">
<dt>count</dt>
<dd>the number of objects to allocate contiguously. </dd>
<dd> </dd>
<dt>quantum</dt>
<dd>the size (in bytes) of each object. </dd>
<dd> </dd>
</dl>
<h2><a href="../../api/MagickCore/memory_8c.html" id="AcquireVirtualMemory">AcquireVirtualMemory</a></h2>
<p>AcquireVirtualMemory() allocates a pointer to a block of memory at least size bytes suitably aligned for any use. In addition to heap, it also supports memory-mapped and file-based memory-mapped memory requests.</p>
<p>The format of the AcquireVirtualMemory method is:</p>
<pre class="text">
MemoryInfo *AcquireVirtualMemory(const size_t count,const size_t quantum)
</pre>
<p>A description of each parameter follows:</p>
<dd>
</dd>
<dd> </dd>
<dl class="dl-horizontal">
<dt>count</dt>
<dd>the number of objects to allocate contiguously. </dd>
<dd> </dd>
<dt>quantum</dt>
<dd>the size (in bytes) of each object. </dd>
<dd> </dd>
</dl>
<h2><a href="../../api/MagickCore/memory_8c.html" id="CopyMagickMemory">CopyMagickMemory</a></h2>
<p>CopyMagickMemory() copies size bytes from memory area source to the destination. Copying between objects that overlap will take place correctly. It returns destination.</p>
<p>The format of the CopyMagickMemory method is:</p>
<pre class="text">
void *CopyMagickMemory(void *magick_restrict destination,
const void *magick_restrict source,const size_t size)
</pre>
<p>A description of each parameter follows:</p>
<dd>
</dd>
<dd> </dd>
<dl class="dl-horizontal">
<dt>destination</dt>
<dd>the destination. </dd>
<dd> </dd>
<dt>source</dt>
<dd>the source. </dd>
<dd> </dd>
<dt>size</dt>
<dd>the size of the memory in bytes to allocate. </dd>
<dd> </dd>
</dl>
<h2><a href="../../api/MagickCore/memory_8c.html" id="GetMagickMemoryMethods">GetMagickMemoryMethods</a></h2>
<p>GetMagickMemoryMethods() gets the methods to acquire, resize, and destroy memory.</p>
<p>The format of the GetMagickMemoryMethods() method is:</p>
<pre class="text">
void GetMagickMemoryMethods(AcquireMemoryHandler *acquire_memory_handler,
ResizeMemoryHandler *resize_memory_handler,
DestroyMemoryHandler *destroy_memory_handler)
</pre>
<p>A description of each parameter follows:</p>
<dd>
</dd>
<dd> </dd>
<dl class="dl-horizontal">
<dt>acquire_memory_handler</dt>
<dd>method to acquire memory (e.g. malloc). </dd>
<dd> </dd>
<dt>resize_memory_handler</dt>
<dd>method to resize memory (e.g. realloc). </dd>
<dd> </dd>
<dt>destroy_memory_handler</dt>
<dd>method to destroy memory (e.g. free). </dd>
<dd> </dd>
</dl>
<h2><a href="../../api/MagickCore/memory_8c.html" id="GetVirtualMemoryBlob">GetVirtualMemoryBlob</a></h2>
<p>GetVirtualMemoryBlob() returns the virtual memory blob associated with the specified MemoryInfo structure.</p>
<p>The format of the GetVirtualMemoryBlob method is:</p>
<pre class="text">
void *GetVirtualMemoryBlob(const MemoryInfo *memory_info)
</pre>
<p>A description of each parameter follows:</p>
<dd>
</dd>
<dd> </dd>
<dl class="dl-horizontal">
<dt>memory_info</dt>
<dd>The MemoryInfo structure. </dd>
</dl>
<h2><a href="../../api/MagickCore/memory_8c.html" id="RelinquishAlignedMemory">RelinquishAlignedMemory</a></h2>
<p>RelinquishAlignedMemory() frees memory acquired with AcquireAlignedMemory() or reuse.</p>
<p>The format of the RelinquishAlignedMemory method is:</p>
<pre class="text">
void *RelinquishAlignedMemory(void *memory)
</pre>
<p>A description of each parameter follows:</p>
<dd>
</dd>
<dd> </dd>
<dl class="dl-horizontal">
<dt>memory</dt>
<dd>A pointer to a block of memory to free for reuse. </dd>
<dd> </dd>
</dl>
<h2><a href="../../api/MagickCore/memory_8c.html" id="RelinquishMagickMemory">RelinquishMagickMemory</a></h2>
<p>RelinquishMagickMemory() frees memory acquired with AcquireMagickMemory() or AcquireQuantumMemory() for reuse.</p>
<p>The format of the RelinquishMagickMemory method is:</p>
<pre class="text">
void *RelinquishMagickMemory(void *memory)
</pre>
<p>A description of each parameter follows:</p>
<dd>
</dd>
<dd> </dd>
<dl class="dl-horizontal">
<dt>memory</dt>
<dd>A pointer to a block of memory to free for reuse. </dd>
<dd> </dd>
</dl>
<h2><a href="../../api/MagickCore/memory_8c.html" id="RelinquishVirtualMemory">RelinquishVirtualMemory</a></h2>
<p>RelinquishVirtualMemory() frees memory acquired with AcquireVirtualMemory().</p>
<p>The format of the RelinquishVirtualMemory method is:</p>
<pre class="text">
MemoryInfo *RelinquishVirtualMemory(MemoryInfo *memory_info)
</pre>
<p>A description of each parameter follows:</p>
<dd>
</dd>
<dd> </dd>
<dl class="dl-horizontal">
<dt>memory_info</dt>
<dd>A pointer to a block of memory to free for reuse. </dd>
<dd> </dd>
</dl>
<h2><a href="../../api/MagickCore/memory_8c.html" id="ResetMagickMemory">ResetMagickMemory</a></h2>
<p>ResetMagickMemory() fills the first size bytes of the memory area pointed to by memory with the constant byte c.</p>
<p>The format of the ResetMagickMemory method is:</p>
<pre class="text">
void *ResetMagickMemory(void *memory,int byte,const size_t size)
</pre>
<p>A description of each parameter follows:</p>
<dd>
</dd>
<dd> </dd>
<dl class="dl-horizontal">
<dt>memory</dt>
<dd>a pointer to a memory allocation. </dd>
<dd> </dd>
<dt>byte</dt>
<dd>set the memory to this value. </dd>
<dd> </dd>
<dt>size</dt>
<dd>size of the memory to reset. </dd>
<dd> </dd>
</dl>
<h2><a href="../../api/MagickCore/memory_8c.html" id="ResizeMagickMemory">ResizeMagickMemory</a></h2>
<p>ResizeMagickMemory() changes the size of the memory and returns a pointer to the (possibly moved) block. The contents will be unchanged up to the lesser of the new and old sizes.</p>
<p>The format of the ResizeMagickMemory method is:</p>
<pre class="text">
void *ResizeMagickMemory(void *memory,const size_t size)
</pre>
<p>A description of each parameter follows:</p>
<dd>
</dd>
<dd> </dd>
<dl class="dl-horizontal">
<dt>memory</dt>
<dd>A pointer to a memory allocation. </dd>
<dd> </dd>
<dt>size</dt>
<dd>the new size of the allocated memory. </dd>
<dd> </dd>
</dl>
<h2><a href="../../api/MagickCore/memory_8c.html" id="ResizeQuantumMemory">ResizeQuantumMemory</a></h2>
<p>ResizeQuantumMemory() changes the size of the memory and returns a pointer to the (possibly moved) block. The contents will be unchanged up to the lesser of the new and old sizes.</p>
<p>The format of the ResizeQuantumMemory method is:</p>
<pre class="text">
void *ResizeQuantumMemory(void *memory,const size_t count,
const size_t quantum)
</pre>
<p>A description of each parameter follows:</p>
<dd>
</dd>
<dd> </dd>
<dl class="dl-horizontal">
<dt>memory</dt>
<dd>A pointer to a memory allocation. </dd>
<dd> </dd>
<dt>count</dt>
<dd>the number of objects to allocate contiguously. </dd>
<dd> </dd>
<dt>quantum</dt>
<dd>the size (in bytes) of each object. </dd>
<dd> </dd>
</dl>
<h2><a href="../../api/MagickCore/memory_8c.html" id="SetMagickAlignedMemoryMethods">SetMagickAlignedMemoryMethods</a></h2>
<p>SetMagickAlignedMemoryMethods() sets the methods to acquire and relinquish aligned memory.</p>
<p>The format of the SetMagickAlignedMemoryMethods() method is:</p>
<pre class="text">
SetMagickAlignedMemoryMethods(
AcquireAlignedMemoryHandler acquire_aligned_memory_handler,
RelinquishAlignedMemoryHandler relinquish_aligned_memory_handler)
</pre>
<p>A description of each parameter follows:</p>
<dd>
</dd>
<dd> </dd>
<dl class="dl-horizontal">
<dt>acquire_memory_handler</dt>
<dd>method to acquire aligned memory. </dd>
<dd> </dd>
<dt>relinquish_aligned_memory_handler</dt>
<dd>method to relinquish aligned memory. </dd>
<dd> </dd>
</dl>
<h2><a href="../../api/MagickCore/memory_8c.html" id="SetMagickMemoryMethods">SetMagickMemoryMethods</a></h2>
<p>SetMagickMemoryMethods() sets the methods to acquire, resize, and destroy memory. Your custom memory methods must be set prior to the MagickCoreGenesis() method.</p>
<p>The format of the SetMagickMemoryMethods() method is:</p>
<pre class="text">
SetMagickMemoryMethods(AcquireMemoryHandler acquire_memory_handler,
ResizeMemoryHandler resize_memory_handler,
DestroyMemoryHandler destroy_memory_handler)
</pre>
<p>A description of each parameter follows:</p>
<dd>
</dd>
<dd> </dd>
<dl class="dl-horizontal">
<dt>acquire_memory_handler</dt>
<dd>method to acquire memory (e.g. malloc). </dd>
<dd> </dd>
<dt>resize_memory_handler</dt>
<dd>method to resize memory (e.g. realloc). </dd>
<dd> </dd>
<dt>destroy_memory_handler</dt>
<dd>method to destroy memory (e.g. free). </dd>
<dd> </dd>
</dl>
</div>
</div>
</main><!-- /.container -->
<footer class="magick-footer">
<div class="container-fluid">
<a href="../../www/security-policy.html">Security</a>
<a href="../../www/news.html">News</a>
<a href="memory.html#"><img class="d-inline" id="wand" alt="And Now a Touch of Magick" width="16" height="16" src="../../../images/wand.ico"/></a>
<a href="../../www/links.html">Related</a>
<a href="../../www/sitemap.html">Sitemap</a>
<br/>
<a href="../../www/support.html">Sponsor</a>
<a href="../../www/cite.html">Cite</a>
<a href="http://pgp.mit.edu/pks/lookup?op=get&amp;search=0x89AB63D48277377A">Public Key</a>
<a href="../../www/contact.html">Contact Us</a>
<br/>
<a href="https://github.com/imagemagick/imagemagick" target="_blank" rel="noopener" aria-label="GitHub"><svg xmlns="http://www.w3.org/2000/svg" class="navbar-nav-svg" viewBox="0 0 512 499.36" width="2%" height="2%" role="img" focusable="false"><title>GitHub</title><path fill="currentColor" fill-rule="evenodd" d="M256 0C114.64 0 0 114.61 0 256c0 113.09 73.34 209 175.08 242.9 12.8 2.35 17.47-5.56 17.47-12.34 0-6.08-.22-22.18-.35-43.54-71.2 15.49-86.2-34.34-86.2-34.34-11.64-29.57-28.42-37.45-28.42-37.45-23.27-15.84 1.73-15.55 1.73-15.55 25.69 1.81 39.21 26.38 39.21 26.38 22.84 39.12 59.92 27.82 74.5 21.27 2.33-16.54 8.94-27.82 16.25-34.22-56.84-6.43-116.6-28.43-116.6-126.49 0-27.95 10-50.8 26.35-68.69-2.63-6.48-11.42-32.5 2.51-67.75 0 0 21.49-6.88 70.4 26.24a242.65 242.65 0 0 1 128.18 0c48.87-33.13 70.33-26.24 70.33-26.24 14 35.25 5.18 61.27 2.55 67.75 16.41 17.9 26.31 40.75 26.31 68.69 0 98.35-59.85 120-116.88 126.32 9.19 7.9 17.38 23.53 17.38 47.41 0 34.22-.31 61.83-.31 70.23 0 6.85 4.61 14.81 17.6 12.31C438.72 464.97 512 369.08 512 256.02 512 114.62 397.37 0 256 0z"/></svg></a>
<a href="https://twitter.com/imagemagick" target="_blank" rel="noopener" aria-label="Twitter"><svg xmlns="http://www.w3.org/2000/svg" class="navbar-nav-svg" viewBox="0 0 512 416.32" width="2%" height="2%" role="img" focusable="false"><title>Twitter</title><path fill="currentColor" d="M160.83 416.32c193.2 0 298.92-160.22 298.92-298.92 0-4.51 0-9-.2-13.52A214 214 0 0 0 512 49.38a212.93 212.93 0 0 1-60.44 16.6 105.7 105.7 0 0 0 46.3-58.19 209 209 0 0 1-66.79 25.37 105.09 105.09 0 0 0-181.73 71.91 116.12 116.12 0 0 0 2.66 24c-87.28-4.3-164.73-46.3-216.56-109.82A105.48 105.48 0 0 0 68 159.6a106.27 106.27 0 0 1-47.53-13.11v1.43a105.28 105.28 0 0 0 84.21 103.06 105.67 105.67 0 0 1-47.33 1.84 105.06 105.06 0 0 0 98.14 72.94A210.72 210.72 0 0 1 25 370.84a202.17 202.17 0 0 1-25-1.43 298.85 298.85 0 0 0 160.83 46.92"/></svg></a>
<br/>
<small>© 1999-2021 ImageMagick Studio LLC</small>
</div>
</footer>
<!-- Javascript assets -->
<script src="../../assets/magick.js" ></script>
</body>
</html>