haiku-website/static/legacy-docs/bebook/TheMediaKit_RealTimeFunctio...

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>The Be Book - Classes And Methods - The Media Kit</title><link rel="stylesheet" href="be_book.css" type="text/css" media="all" /><link rel="shortcut icon" type="image/vnd.microsoft.icon" href="./images/favicon.ico" /><!--[if IE]>
    <link rel="stylesheet" type="text/css" href="be_book_ie.css" />
    <![endif]--><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="Access, BeOS, BeBook, API" /><link rel="start" href="index.html" title="The Be Book" /><link rel="up" href="TheMediaKit.html" title="The Media Kit" /><link rel="prev" href="TheMediaKit_Functions.html" title="Functions" /><link rel="next" href="TheMediaKit_Constants.html" title="Constants" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="TheMediaKit_Functions.html" title="Functions"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a accesskey="u" href="TheMediaKit.html" title="The Media Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a accesskey="n" href="TheMediaKit_Constants.html" title="Constants"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="headerTR"><div id="navigpeople"><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div><div class="navigboxed" id="navigindex"><a accesskey="i" href="ClassIndex.html" title="Index">I</a></div><div class="navigboxed" id="naviglang" title="English">en</div></div><div id="headerTC">The Be Book - Classes And Methods - The Media Kit</div></div><div id="headerB">Prev: <a href="TheMediaKit_Functions.html">Functions</a>  Up: <a href="TheMediaKit.html">The Media Kit</a>  Next: <a href="TheMediaKit_Constants.html">Constants</a></div><hr /></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h2 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheMediaKit_RealTimeFunctions"></a>Real Time Functions</h2></div></div></div><div class="informaltable"><table border="0"><colgroup><col /><col /></colgroup><tbody><tr><td>Declared in:</td><td><code class="filename">media/RealtimeAlloc.h</code></td></tr><tr><td>Library:</td><td><code class="filename">libmedia.so</code></td></tr></tbody></table></div><p>Media nodes are highly timing-sensitive creatures. The slightest delay in
performing their work can cause drastic problems in media playback or
recording quality. Virtual memory, normally of great benefit to users,
can work against them when doing media work. A poorly-timed virtual
memory hit can cause breaks in media performances.</p><p>The realtime memory allocation and locking functions provide a means for
nodes to lock down their memory to prevent it from being cached to disk
by the virtual memory system. This avoids situations in which the node
has to pause while it or its memory is fetched back from the swap file.</p><p>The user can use the Media preference application to configure what types
of nodes should use locked memory. Nodes should typically use the
realtime memory allocation functions instead of
<code class="function">malloc()</code> and <code class="function">free()</code>.
<a class="link" href="TheMediaKit_RealTimeFunctions.html#rtm_alloc" title="rtm_alloc(), rtm_realloc()"><code class="function">rtm_alloc()</code></a>
will automatically handle locking the memory if the
<a class="link" href="TheMediaKit_Constants.html#B_MEDIA_REALTIME_ALLOCATOR"><code class="constant">B_MEDIA_REALTIME_ALLOCATOR</code></a>
flag is set, so your node doesn't have to worry about it.</p><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheMediaKit_RealTimeFunctions_MemoryPools"></a>Memory Pools</h3></div></div></div><p>Real-time memory blocks are allocated in pools. Pools are locked into
physical RAM if realtime allocators are turned on in the
<a class="link" href="BMediaRoster.html" title="BMediaRoster"><code class="classname">BMediaRoster</code></a>.
While pools are locked in memory, that reduces the amount of physical RAM
available to other applications, so don't use real-time blocks unless
it's really going to benefit your performance.</p><p>When you create a pool, you specify the total size of the pool. This size
is the maximum number of bytes that can be allocated from the pool.
Memory can then be allocated out of the pool by calling
<a class="link" href="TheMediaKit_RealTimeFunctions.html#rtm_alloc" title="rtm_alloc(), rtm_realloc()"><code class="function">rtm_alloc()</code></a>
and memory blocks in the pool can be freed by calling
<a class="link" href="TheMediaKit_RealTimeFunctions.html#rtm_free" title="rtm_free()"><code class="function">rtm_free()</code></a>.</p><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheMediaKit_RealTimeFunctions_TheDefaultPool"></a>The Default Pool</h4></div></div></div><p>There's a special pool, called the default (or shared) pool. You can
allocate memory blocks in this pool if you wish, but it's a scarce
resource and as a general rule you should avoid it.</p><p>Instead, you should create your own pool and use that; let the media
nodes and Media Kit use the default pool for its own purposes.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheMediaKit_RealTimeFunctions_MALLOC_DEBUG"></a>MALLOC_DEBUG</h4></div></div></div><p><a class="link" href="TheMediaKit_RealTimeFunctions.html#rtm_alloc" title="rtm_alloc(), rtm_realloc()"><code class="function">rtm_alloc()</code></a>
responds to the value of <code class="envar">MALLOC_DEBUG</code>. If the <code class="envar">MALLOC_DEBUG</code>
environment variable is set to anything other than 0, new and freed
blocks will be cleared to some junk value. If it's set to an integer
greater than 1 it will also do pool, heap, and block validations at
opportune times. It's not perfect validation, but it's better than
nothing.</p></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheMediaKit_RealTimeFunctions_GlobalCFunctions"></a>Global C Functions</h3></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="rtm_alloc"></a><a id="rtm_realloc"></a>
rtm_alloc(), rtm_realloc()</h4></div></div></div><a id="id1180718" class="indexterm"></a><a id="id1180725" class="indexterm"></a><code class="methodsynopsis c"><span class="type">void* </span><span class="methodname">rtm_alloc</span>(<span class="methodparam"><span class="type">rtm_pool* </span><span class="parameter">pool</span></span>,<br />                <span class="methodparam"><span class="type">size_t </span><span class="parameter">size</span></span>);</code><code class="methodsynopsis c"><span class="type">status_t* </span><span class="methodname">rtm_realloc</span>(<span class="methodparam"><span class="type">void** </span><span class="parameter">data</span></span>,<br />                      <span class="methodparam"><span class="type">size_t </span><span class="parameter">newSize</span></span>);</code><p><code class="function">rtm_alloc()</code> allocates a block of memory of
size bytes in the specified pool. If you specify
<code class="constant">NULL</code> for <code class="parameter">pool</code>, the
memory is allocated in the default pool.</p><p><code class="function">rtm_realloc()</code> resizes the block referenced
by data to be <code class="parameter">newSize</code> bytes long. Since the
buffer may have to move to accomodate the new size, the pointer pointed to
by <code class="parameter">data</code> may change. If
<code class="parameter">data</code> is <code class="constant">NULL</code>, this is
just like calling <code class="function">rtm_alloc()</code> on the default
pool.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_VALUE</code></span></p></td><td><p>The <code class="parameter">data</code> pointer is <code class="constant">NULL</code>.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NO_MEMORY</code></span></p></td><td><p>The pool is full.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="rtm_create_pool"></a><a id="rtm_delete_pool"></a>
rtm_create_pool(), rtm_delete_pool()</h4></div></div></div><a id="id1180911" class="indexterm"></a><a id="id1180918" class="indexterm"></a><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">rtm_create_pool</span>(<span class="methodparam"><span class="type">rtm_pool** </span><span class="parameter">outPool</span></span>,<br />                         <span class="methodparam"><span class="type">size_t </span><span class="parameter">totalSize</span></span>,<br />                         <span class="methodparam"><span class="modifier">const </span><span class="type">char* </span><span class="parameter">name</span><span class="initializer"> = <span class="constant">NULL</span></span></span>);</code><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">rtm_delete_pool</span>(<span class="methodparam"><span class="type">rtm_pool* </span><span class="parameter">pool</span></span>);</code><p><code class="function">rtm_create_pool()</code> creates a new memory
pool. The pool's <span class="type">rtm_pool</span> reference is stored in
<code class="parameter">outPool</code>. The pool is capable of holding up to
<code class="parameter">totalSize</code> bytes of data, and is given the
specified <code class="parameter">name</code>.</p><p>If <code class="parameter">outPool</code> is
<code class="constant">NULL</code>, the default pool is created if it doesn't
already exist. If it does, <code class="constant">EALREADY</code> is
returned.</p><p><code class="function">rtm_delete_pool()</code> deletes the specified
<code class="parameter">pool</code>. You can't delete the default pool; passing
<code class="constant">NULL</code> as pool will return
<code class="constant">B_BAD_VALUE</code>.</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>Be sure to delete a pool once you're finished with it.</p></div></div></div><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error.</p></td></tr><tr><td><p><span class="term"><code class="constant">EALREADY</code></span></p></td><td><p>The default pool already exists
(<code class="function">rtm_create_pool()</code> only).</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_VALUE</code></span></p></td><td><p>You can't delete the default pool.</p></td></tr><tr><td><p><span class="term">Other Errors</span></p></td><td><p><a class="link" href="TheKernelKit_Areas.html" title="Areas">Area</a> errors.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="rtm_default_pool"></a>rtm_default_pool()</h4></div></div></div><a id="id1181149" class="indexterm"></a><code class="methodsynopsis c"><span class="type">rtm_pool* </span><span class="methodname">rtm_default_pool</span>();</code><p>Returns a pointer to the default pool, or <code class="constant">NULL</code> if it hasn't been
initialized yet.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="rtm_free"></a>rtm_free()</h4></div></div></div><a id="id1181190" class="indexterm"></a><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">rtm_free</span>(<span class="methodparam"><span class="type">void* </span><span class="parameter">data</span></span>);</code><p>Frees the specified block of data.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_VALUE</code></span></p></td><td><p>A <code class="constant">NULL</code> pointer was given.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="rtm_size_for"></a><a id="rtm_phys_size_for"></a>
rtm_size_for(), rtm_phys_size_for()</h4></div></div></div><a id="id1181279" class="indexterm"></a><a id="id1181286" class="indexterm"></a><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">rtm_size_for</span>(<span class="methodparam"><span class="type">void* </span><span class="parameter">data</span></span>);</code><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">rtm_phys_size_for</span>(<span class="methodparam"><span class="type">void* </span><span class="parameter">data</span></span>);</code><p><code class="function">rtm_size_for()</code> returns the size of the
specified block of memory.</p><p><code class="function">rtm_phys_size_for()</code> returns the physical size of the specified block of
memory. This is the maximum number of bytes the block can grow to without
risking
<a class="link" href="TheMediaKit_RealTimeFunctions.html#rtm_realloc"><code class="function">rtm_realloc()</code></a>
actually moving the block; the physical size is
always greater than or equal to the block size.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code></span></p></td><td><p>No error.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_VALUE</code></span></p></td><td><p>The <code class="parameter">data</code> pointer is
<code class="constant">NULL</code>.</p></td></tr></tbody></table></div></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="TheMediaKit_Functions.html">Functions</a>  Up: <a href="TheMediaKit.html">The Media Kit</a>  Next: <a href="TheMediaKit_Constants.html">Constants</a> </div><div id="footerB"><div id="footerBL"><a href="TheMediaKit_Functions.html" title="Functions"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a href="TheMediaKit.html" title="The Media Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a href="TheMediaKit_Constants.html" title="Constants"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="footerBR"><div><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div></div><div id="footerBC"><a href="http://www.access-company.com/home.html" title="ACCESS Co."><img alt="Access Company" src="./images/access_logo.png" /></a></div></div></div><div id="licenseFooter"><div id="licenseFooterBL"><a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/" title="Creative Commons License"><img alt="Creative Commons License" style="border-width:0" src="https://licensebuttons.net/l/by-nc-nd/3.0/88x31.png" /></a></div><div id="licenseFooterBR"><a href="./LegalNotice.html">Legal Notice</a></div><div id="licenseFooterBC"><span id="licenseText">This work is licensed under a
          <a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/">Creative
          Commons Attribution-Non commercial-No Derivative Works 3.0 License</a>.</span></div></div></body></html>